Pyzig

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 PyTypeObjects 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)