性别
- 作者仓库星标 3,367
- 许可证 MIT
- 作者仓库 atopile
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @atopile · MIT
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
from pathlib import Path
from faebryk.libs.kicad.fileformats import kicad
pcb = kicad.loads(kicad.pcb.PcbFile, Path("board.kicad_pcb"))
_text = kicad.dumps(pcb)
# Sexp Module
The sexp subsystem provides:
- a fast S-expression tokenizer/parser/pretty-printer in Zig, and
- typed Zig models for KiCad formats (PCB, footprint, netlist, symbol, schematic, fp_lib_table),
exposed to Python via the `pyzig_sexp` extension module.
Source-of-truth docs and code:
- `src/faebryk/core/zig/README.md` (high-level overview)
- `src/faebryk/core/zig/src/sexp/*` (tokenizer/AST/structure)
- `src/faebryk/core/zig/src/python/sexp/sexp_py.zig` (Python API + critical memory rules)
## Quick Start
```python
from pathlib import Path
from faebryk.libs.kicad.fileformats import kicad
pcb = kicad.loads(kicad.pcb.PcbFile, Path("board.kicad_pcb"))
_text = kicad.dumps(pcb)
```
## Relevant Files
- Zig core:
- `src/faebryk/core/zig/src/sexp/tokenizer.zig` (tokenization + line/column tracking)
- `src/faebryk/core/zig/src/sexp/ast.zig` (SExp tree + KiCad pretty formatting)
- `src/faebryk/core/zig/src/sexp/structure.zig` (decode/encode + error context)
- `src/faebryk/core/zig/src/sexp/kicad/*` (typed KiCad models)
- Python extension entrypoint:
- `src/faebryk/core/zig/src/python/sexp/init.zig` (exports `PyInit_pyzig_sexp`)
- `src/faebryk/core/zig/src/python/sexp/sexp_py.zig` (module + type binding generation)
- Generated Python stubs (what users “see”):
- `src/faebryk/core/zig/gen/sexp/*.pyi`
- Convenience wrapper used throughout the codebase:
- `src/faebryk/libs/kicad/fileformats.py` (namespaces modules + caching + `loads/dumps`)
## Dependants (Call Sites)
- `src/faebryk/libs/kicad/fileformats.py` (primary integration layer)
- KiCad exporters and layout sync:
- `src/faebryk/exporters/pcb/kicad/*`
- `src/faebryk/exporters/pcb/layout/layout_sync.py`
- KiCad plugin workflow: `src/atopile/kicad_plugin/*`
## How to Work With / Develop / Test
### Core Concepts
- **Two-level model**:
- raw `SExp` parsing/formatting (`tokenizer.zig`, `ast.zig`)
- typed KiCad decoding/encoding (`structure.zig` + `sexp/kicad/*.zig`)
- **Python API shape**: the extension exposes per-format modules (e.g. `pcb`, `netlist`) with:
- module-level `loads(data: str) -> File`
- module-level `dumps(file: File) -> str`
- `File.free(...)` for releasing Zig-owned allocations
- **Convenience wrapper**: `faebryk.libs.kicad.fileformats.kicad` wraps these modules and provides `kicad.loads(...)`/`kicad.dumps(...)`.
### Development Workflow
1) Modify Zig:
- parsing/formatting: `src/faebryk/core/zig/src/sexp/*`
- Python exposure: `src/faebryk/core/zig/src/python/sexp/sexp_py.zig`
2) Rebuild:
- `ato dev compile` (imports `faebryk.core.zig`)
3) If you changed the API:
- verify stubs under `src/faebryk/core/zig/gen/sexp/*.pyi` update accordingly
- adjust `src/faebryk/libs/kicad/fileformats.py` if needed
### Testing
- Best practical test is round-trip:
- load a known `.kicad_pcb` / `.kicad_sch`, dump it, and ensure KiCad accepts it (formatting-sensitive).
- Zig unit tests (where present):
- `zig test src/faebryk/core/zig/src/sexp/ast.zig`
- `zig test src/faebryk/core/zig/src/sexp/structure.zig`
## Best Practices
- Prefer `faebryk.libs.kicad.fileformats.kicad` unless you explicitly need the raw module API.
- Be mindful of **shared-object caching** in `kicad.loads(...)`: path-based loads are cached and returned by reference (mutations are shared).
## Memory & Lifetime Invariants (critical)
The Python bindings duplicate the input S-expression string into a persistent allocator because parsed structs contain pointers into the input buffer.
Implications:
- Repeated `loads(...)` of large files can grow memory if you never call `free(...)` on the returned `*File`.
- The convenience wrapper currently caches loaded objects by path; do not `free(...)` cached objects unless you also invalidate the cache.
章节与文件索引
按说明文件中的顺序排列。
相关文件
家属(呼叫站点)
核心概念
开发流程
测试
文件/命令 -> pyzig_sexp · src/faebryk/core/zig/README.md · src/faebryk/core/zig/src/sexp/* · src/faebryk/core/zig/src/python/sexp/sexp_py.zig · src/faebryk/core/zig/src/sexp/tokenizer.zig · src/faebryk/core/zig/src/sexp/ast.zig · src/faebryk/core/zig/src/sexp/structure.zig · src/faebryk/core/zig/src/sexp/kicad/*
内容校验值 -> 6c65510f5923
当前原文的自动摘译,尚未人工审校。
相关文件
Zig 核心:
src/faebryk/core/zig/src/sexp/tokenizer.zig(标记化 + 行/列跟踪)src/faebryk/core/zig/src/sexp/ast.zig(SExp 树 + KiCad 漂亮格式)src/faebryk/core/zig/src/sexp/structure.zig(解码/编码 + 错误上下文)src/faebryk/core/zig/src/sexp/kicad/*(类型化 KiCad 模型)家属(呼叫站点)
src/faebryk/libs/kicad/fileformats.py(主要集成层)KiCad 导出器和布局同步:src/faebryk/exporters/pcb/kicad/*src/faebryk/exporters/pcb/layout/layout_sync.pyKiCad 插件工作流程:src/atopile/kicad_plugin/*核心概念
两级模型:原始
SExp解析/格式化(tokenizer.zig、ast.zig)类型化 KiCad 解码/编码(structure.zig+sexp/kicad/*.zig)Python API 形状:扩展公开每种格式的模块(例如pcb、netlist):模块级loads(data: str) -> File开发流程
修改 Zig:解析/格式化:
src/faebryk/core/zig/src/sexp/*Python 暴露:src/faebryk/core/zig/src/python/sexp/sexp_py.zig重建:ato dev compile(导入faebryk.core.zig)测试
最好的实际测试是往返:加载已知的
.kicad_pcb/.kicad_sch,转储它,并确保 KiCad 接受它(格式敏感)。 Zig 单元测试(如果存在):zig test src/faebryk/core/zig/src/sexp/ast.zigzig test src/faebryk/core/zig/src/sexp/structure.zig