Pyzig Modülü

pyzig, Faebryk'in native modüllerinin (graph, sexp, faebryk typegraph, …) kullanmış olduğu Zig↔Python birlikte çalışabilirlik katmanıdır.

Ayırt edilmesi gereken üç ayrı katman vardır:

• Python loader/glue: src/faebryk/core/zig/__init__.py (build-on-import + .pyi syncing)
• Zig build: src/faebryk/core/zig/build.zig (pyzig.so + pyzig_sexp.so inşa eder, stub'lar üretir)
• Zig binding utilities: src/faebryk/core/zig/src/pyzig/* (wrapper generation + minimal C-API surface)

Hızlı Başlangıç

ato dev compile
python -c "import faebryk.core.zig; import faebryk.core.graph"

İlgili Dosyalar

• Python tarafı 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 (extensions'ı inşa eder + .pyi generator'ı çalıştırır)
• 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)
• Örnek tüketiciler:
  • src/faebryk/core/zig/src/python/graph/graph_py.zig
  • src/faebryk/core/zig/src/python/sexp/sexp_py.zig

Bağımlılar (Çağrı Siteleri)

• 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/* (ve diğerleri)

Nasıl Çalışılır / Geliştiriş / Test

Temel Konseptler

• Direct binding: pyzig, CPython C-API'ı doğrudan çağırır (cffi/ctypes yok).
• Wrapper types: çoğu exposed Zig struct, wrap_in_python(...) / wrap_in_python_simple(...) aracılığıyla Python heap type'larına dönüşür.
• Global type registry: aynı Zig type'ı için Python PyTypeObject'lerin yeniden oluşturulmasını engeller (type_registry).
• Varsayılan olarak doğrudan __init__ yok: birçok "reference" type'ı kullanıcı tarafından inşa edilmesi amaçlanmamıştır; pyzig sıklıkla bir exception raise eden init kurar.
• Debug handle: oluşturulan wrapper'lar pointer kimliği debug'lamaya yardımcı olmak için __zig_address__() içerir.

Geliştirme Akışı

1. Zig'i düzenleyin:
   • binding helpers: src/faebryk/core/zig/src/pyzig/*
   • module wrappers: src/faebryk/core/zig/src/python/**
2. Native modüllerini yeniden inşa edin:
   • ato dev compile (faebryk.core.zig'i import eder; editable installs compile-on-import yapar)
   • gerektiğinde ZIG_RELEASEMODE=ReleaseFast|ReleaseSafe|Debug ayarlayın
3. Stub'ları/çıktıyı değiştirdiyseniz:
   • src/faebryk/core/zig/gen/**'nin güncellendiğinden emin olun (bu src/faebryk/core/zig/__init__.py tarafından yönlendirilir)

Test

• Smoke test'ler genellikle downstream modüller aracılığıyla yapılır:
  • python -m faebryk.core.graph (GraphView allocation/cleanup stress)
  • ato dev test --llm test/core/solver (graph'i ve birçok alt sistem aracılığıyla binding'leri yoğun kullanır)

En İyi Uygulamalar

• Hataların segfault yapacağını varsayın: buradaki değişiklikleri güvenli olmayan systems programming'i gibi ele alın.
• Ownership konusunda açık olun:
  • eğer bir wrapper, Zig memory'yi allocate ederse, nasıl serbest bırakıldığını tanımlayın (açık .destroy() vs tp_dealloc çağırıp .deinit()).
  • eğer input buffer'larını duplicate ederseniz (sexp yapar), bir free(...) path'i expose edin ve belgelendirin.
• Zig arena'ları için Python GC'ye güvenmeyin unless deliberately installed a tp_dealloc çağıran deinit.
• Stub hygiene'i önemser: .pyi surface'ini doğru tutun; birçok çağrıcı, navigation için type'lara güvenir.

Build-on-import davranışı (önemli)

src/faebryk/core/zig/__init__.py şunlardan sorumludur:

• editable installs'te extension'ları derlemek (ZIG_NORECOMPILE=1 olmadığı sürece)
• pyzig.so ve pyzig_sexp.so'yu src/faebryk/core/zig/zig-out/lib/'ten yüklemek
• oluşturulan .pyi dosyalarını src/faebryk/core/zig/gen/**'ye kopyalama + formatting (black + ruff)