皮齐格
- 作者仓库星标 3,367
- 许可证 MIT
- 作者仓库 atopile
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @atopile · MIT
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
ato dev compile
python -c "import faebryk.core.zig; import faebryk.core.graph"
# 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)
章节与文件索引
按说明文件中的顺序排列。
相关文件
家属(呼叫站点)
核心概念
开发流程
测试
文件/命令 -> 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
内容校验值 -> 3df8cb8b6ee4
当前原文的自动摘译,尚未人工审校。
相关文件
Python 端加载器/构建胶水:
src/faebryk/core/zig/__init__.py(ZIG_NORECOMPILE、ZIG_RELEASEMODE、锁定、存根同步) Zig 构建 + 存根生成:src/faebryk/core/zig/build.zig(构建扩展 + 运行.pyi生成器) 核心 pyzig 实用程序:家属(呼叫站点)
图绑定:
src/faebryk/core/zig/src/python/graph/*Sexp 绑定:src/faebryk/core/zig/src/python/sexp/*TypeGraph 绑定:src/faebryk/core/zig/src/python/faebryk/*(和朋友)核心概念
直接绑定:pyzig 直接调用 CPython C-API(无 cffi/ctypes)。包装类型:大多数公开的 Zig 结构通过
wrap_in_python(...)/wrap_in_python_simple(...)成为 Python 堆类型。全局类型注册表:防止为相同的 Zig 类型 (type_registry) 重新创建 PythonPyTypeObject。没有直接的__init__(默认情况下):许多“参考”类型并不意味着由用户构建;pyzig经常安装一个引发的 init。开发流程
编辑 Zig:绑定助手:
src/faebryk/core/zig/src/pyzig/*模块包装器:src/faebryk/core/zig/src/python/重建本机模块:ato dev compile(导入faebryk.core.zig;可编辑安装导入时编译)测试
冒烟测试通常通过下游模块进行:
python -m faebryk.core.graph(GraphView 分配/清理压力)ato dev test --llm test/core/solver(图形+通过许多子系统进行绑定的大量用户)