图形
- 作者仓库星标 3,367
- 许可证 MIT
- 作者仓库 atopile
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @atopile · MIT
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
from faebryk.core.graph import GraphView
g = GraphView.create()
try:
_ = g.create_and_insert_node()
finally:
g.destroy()
# Graph Module
The `faebryk.core.graph` module is a thin Python wrapper around the Zig graph implementation.
Source-of-truth for behavior is:
- Zig implementation: `src/faebryk/core/zig/src/graph/graph.zig`
- Python bindings: `src/faebryk/core/zig/src/python/graph/graph_py.zig`
- Public Python API surface (stubs): `src/faebryk/core/zig/gen/graph/graph.pyi`
## Quick Start
```python
from faebryk.core.graph import GraphView
g = GraphView.create()
try:
_ = g.create_and_insert_node()
finally:
g.destroy()
```
## Relevant Files
- Python wrapper/re-export: `src/faebryk/core/graph.py`
- Zig graph core: `src/faebryk/core/zig/src/graph/graph.zig`
- Zig → Python wrappers: `src/faebryk/core/zig/src/python/graph/graph_py.zig`
- Generated type stubs: `src/faebryk/core/zig/gen/graph/graph.pyi`
## Dependants (Call Sites)
- `src/faebryk/core/node.py` (FabLL: nodes/traits are graph-backed)
- `src/atopile/compiler/gentypegraph.py` (compiler constructs typegraphs/instances via graph APIs)
- `src/faebryk/core/graph_render.py` (graph visualization)
## How to Work With / Develop / Test
### Mental Model
- `NodeReference` / `EdgeReference`: value-like handles (UUIDs) into global backing storage in Zig.
- `GraphView`: a *membership + adjacency* view over those references (per-view arena + maps + bitsets).
- `BoundNode` / `BoundEdge`: “reference + owning GraphView pointer” wrappers used for traversal helpers.
### Core Invariants (do not violate)
- **No direct constructors**: `GraphView()`, `NodeReference()`, `EdgeReference()` are not meant to be called; use the exposed factory methods.
- `GraphView.create()`
- `NodeReference.create(**attrs)`
- `EdgeReference.create(source=..., target=..., edge_type=..., **attrs)`
- **Explicit cleanup**: `GraphView.create()` allocates a Zig-side graph on the C allocator; it is freed only by `GraphView.destroy()`.
- Do not rely on Python GC to reclaim Zig allocations.
- **Attribute limits**: node/edge dynamic attributes are fixed-capacity in Zig (currently 6 entries). Exceeding this is a hard failure.
- **Edge type width**: edge types are `u8` in Zig; treat them as `0..255` in Python (hashing/modulo happens on the Zig side).
- **Self node exists**: `GraphView.init` inserts a `self_node`; counts include it.
### API Cheatsheet (matches `src/faebryk/core/zig/gen/graph/graph.pyi`)
```python
from faebryk.core.graph import GraphView, Node, Edge
g = GraphView.create()
try:
n1 = g.create_and_insert_node() # -> BoundNode
n2 = Node.create(name="n2") # -> NodeReference (not inserted yet)
bn2 = g.insert_node(node=n2) # -> BoundNode
e = Edge.create(source=n1.node(), target=bn2.node(), edge_type=7, name="link")
_be = g.insert_edge(edge=e) # -> BoundEdge
finally:
g.destroy()
```
### Debugging
- `GraphView.__repr__()` prints `GraphView(id=..., |V|=..., |E|=...)` from Zig.
- Graph wrapper has a stress test: `python -m faebryk.core.graph` (runs `test_graph_garbage_collection`).
### Development Workflow
1) Zig changes: edit `src/faebryk/core/zig/src/graph/*`.
2) Rebuild: `ato dev compile` (imports `faebryk.core.zig`, which compiles in editable installs).
3) If you add/remove exposed methods: update the wrapper in `src/faebryk/core/zig/src/python/graph/graph_py.zig` and ensure stubs regenerate.
### Testing
Key test entrypoints:
- Python: `python -m faebryk.core.graph`
- Zig: `zig test src/faebryk/core/zig/src/graph/graph.zig`
章节与文件索引
按说明文件中的顺序排列。
相关文件
家属(呼叫站点)
心智模型
核心不变量(请勿违反)
调试
文件/命令 -> faebryk.core.graph · src/faebryk/core/zig/src/graph/graph.zig · src/faebryk/core/zig/src/python/graph/graph_py.zig · src/faebryk/core/zig/gen/graph/graph.pyi · src/faebryk/core/graph.py · src/faebryk/core/node.py · src/atopile/compiler/gentypegraph.py · src/faebryk/core/graph_render.py
内容校验值 -> 0a08c7d8a934
当前原文的自动摘译,尚未人工审校。
相关文件
Python 包装器/重新导出:
src/faebryk/core/graph.pyZig 图核心:src/faebryk/core/zig/src/graph/graph.zigZig → Python 包装器:src/faebryk/core/zig/src/python/graph/graph_py.zig生成的类型存根:src/faebryk/core/zig/gen/graph/graph.pyi家属(呼叫站点)
src/faebryk/core/node.py(FabLL:节点/特征是图形支持的)src/atopile/compiler/gentypegraph.py(编译器通过图形 API 构造类型图/实例)src/faebryk/core/graph_render.py(图形可视化)心智模型
NodeReference/EdgeReference:Zig 中的全局后备存储中的类似值句柄 (UUID)。GraphView:这些引用的成员资格+邻接视图(每个视图竞技场+地图+位集)。BoundNode/BoundEdge:用于遍历助手的“引用+拥有GraphView指针”包装器。核心不变量(请勿违反)
没有直接构造函数:
GraphView()、NodeReference()、EdgeReference()不应该被调用;使用公开的工厂方法。GraphView.create()NodeReference.create(attrs)EdgeReference.create(source=..., target=..., edge_type=..., attrs)显式清理:GraphView.create()在 C 分配器上分配 Zig 边图;它只能由GraphView.destroy()释放。调试
GraphView.__repr__()从 Zig 打印GraphView(id=..., |V|=..., |E|=...)。图包装器有一个压力测试:python -m faebryk.core.graph(运行test_graph_garbage_collection)。