pyzig
- Repo stars 3,367
- License MIT
- Author repo atopile
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @atopile · MIT
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Pyzig Module
`pyzig` is the Zig↔Python interoperability layer used by Faebryk’s native modules (graph, sexp, faebryk typegraph, …).
There are three distinct layers to keep straight:
- **Python loader/glue**: `src/faebryk/core/zig/__init__.py` (build-on-import + `.pyi` syncing)
- **Zig build**: `src/faebryk/core/zig/build.zig` (builds `pyzig.so` + `pyzig_sexp.so`, generates stubs)
- **Zig binding utilities**: `src/faebryk/core/zig/src/pyzig/*` (wrapper generation + minimal C-API surface)
## Quick Start
```bash
ato dev compile
python -c "import faebryk.core.zig; import faebryk.core.graph"
```
## Relevant Files
- Python-side loader/build glue:
- `src/faebryk/core/zig/__init__.py` (`ZIG_NORECOMPILE`, `ZIG_RELEASEMODE`, lock, stub syncing)
- Zig build + stub generation:
- `src/faebryk/core/zig/build.zig` (builds extensions + runs `.pyi` generator)
- Core pyzig utilities:
- `src/faebryk/core/zig/src/pyzig/pybindings.zig` (minimal CPython C-API declarations)
- `src/faebryk/core/zig/src/pyzig/pyzig.zig` (wrapper generation helpers)
- `src/faebryk/core/zig/src/pyzig/type_registry.zig` (global type-object registry)
- `src/faebryk/core/zig/src/pyzig/pyi.zig` (stub generation helpers)
- Example consumers:
- `src/faebryk/core/zig/src/python/graph/graph_py.zig`
- `src/faebryk/core/zig/src/python/sexp/sexp_py.zig`
## Dependants (Call Sites)
- Graph bindings: `src/faebryk/core/zig/src/python/graph/*`
- Sexp bindings: `src/faebryk/core/zig/src/python/sexp/*`
- TypeGraph bindings: `src/faebryk/core/zig/src/python/faebryk/*` (and friends)
## How to Work With / Develop / Test
### Core Concepts
- **Direct binding**: pyzig calls the CPython C-API directly (no cffi/ctypes).
- **Wrapper types**: most exposed Zig structs become Python heap types via `wrap_in_python(...)` / `wrap_in_python_simple(...)`.
- **Global type registry**: prevents re-creating Python `PyTypeObject`s for the same Zig type (`type_registry`).
- **No direct `__init__` (by default)**: many “reference” types are not meant to be user-constructed; `pyzig` often installs an init that raises.
- **Debug handle**: generated wrappers include `__zig_address__()` to help debug pointer identity.
### Development Workflow
1) Edit Zig:
- binding helpers: `src/faebryk/core/zig/src/pyzig/*`
- module wrappers: `src/faebryk/core/zig/src/python/**`
2) Rebuild native modules:
- `ato dev compile` (imports `faebryk.core.zig`; editable installs compile-on-import)
- set `ZIG_RELEASEMODE=ReleaseFast|ReleaseSafe|Debug` as needed
3) If you changed stubs/output:
- ensure `src/faebryk/core/zig/gen/**` gets updated (this is driven by `src/faebryk/core/zig/__init__.py`)
### Testing
- Smoke tests are usually through downstream modules:
- `python -m faebryk.core.graph` (GraphView allocation/cleanup stress)
- `ato dev test --llm test/core/solver` (heavy user of graph + bindings via many subsystems)
## Best Practices
- **Assume mistakes segfault**: treat changes here like unsafe systems programming.
- **Be explicit about ownership**:
- if a wrapper allocates Zig memory, define how it is freed (explicit `.destroy()` vs `tp_dealloc` calling `.deinit()`).
- if you duplicate input buffers (sexp does), expose a `free(...)` path and document it.
- **Don’t rely on Python GC for Zig arenas** unless you intentionally installed a `tp_dealloc` that calls `deinit`.
- **Stub hygiene matters**: keep the `.pyi` surface accurate; many callers rely on types for navigation.
## Build-on-import behavior (important)
`src/faebryk/core/zig/__init__.py` is responsible for:
- compiling extensions in editable installs (unless `ZIG_NORECOMPILE=1`)
- loading `pyzig.so` and `pyzig_sexp.so` from `src/faebryk/core/zig/zig-out/lib/`
- copying + formatting generated `.pyi` files into `src/faebryk/core/zig/gen/**` (black + ruff)
Sections and files
Listed in source order.
sections -> Quick Start → Relevant Files → Dependants (Call Sites) → How to Work With / Develop / Test → Core Concepts → Development Workflow
terms -> Python loader/glue · Zig build · Zig binding utilities · Direct binding · Wrapper types · Global type registry · No direct init (by default) · Debug handle
files/cmd -> pyzig · src/faebryk/core/zig/__init__.py · .pyi · src/faebryk/core/zig/build.zig · pyzig.so · pyzig_sexp.so · src/faebryk/core/zig/src/pyzig/* · ZIG_NORECOMPILE
body sha256 -> 3df8cb8b6ee4
Relevant Files
Python-side loader/build glue:
src/faebryk/core/zig/__init__.py(ZIG_NORECOMPILE,ZIG_RELEASEMODE, lock, stub syncing) Zig build + stub generation:src/faebryk/core/zig/build.zig(builds extensions + runs.pyigenerator) Core pyzig utilities:Dependants (Call Sites)
Graph bindings:
src/faebryk/core/zig/src/python/graph/*Sexp bindings:src/faebryk/core/zig/src/python/sexp/*TypeGraph bindings:src/faebryk/core/zig/src/python/faebryk/*(and friends)Core Concepts
Direct binding: pyzig calls the CPython C-API directly (no cffi/ctypes). Wrapper types: most exposed Zig structs become Python heap types via
wrap_in_python(...)/wrap_in_python_simple(...). Global type registry: prevents re-creating PythonPyTypeObjects for the same Zig type (type_registry). No direct__init__(by default): many “reference” types are not meant to be user-constructed;pyzigoften installs an init that raises.Development Workflow
Edit Zig: binding helpers:
src/faebryk/core/zig/src/pyzig/*module wrappers:src/faebryk/core/zig/src/python/Rebuild native modules:ato dev compile(importsfaebryk.core.zig; editable installs compile-on-import)Testing
Smoke tests are usually through downstream modules:
python -m faebryk.core.graph(GraphView allocation/cleanup stress)ato dev test --llm test/core/solver(heavy user of graph + bindings via many subsystems)