graph
- Repo stars 3,367
- License MIT
- Author repo atopile
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @atopile · MIT
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js · Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 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`
Sections and files
Listed in source order.
sections -> Quick Start → Relevant Files → Dependants (Call Sites) → How to Work With / Develop / Test → Mental Model → Core Invariants (do not violate)
terms -> No direct constructors · Explicit cleanup · Attribute limits · Edge type width · Self node exists
files/cmd -> 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
body sha256 -> 0a08c7d8a934
Relevant Files
Python wrapper/re-export:
src/faebryk/core/graph.pyZig graph core:src/faebryk/core/zig/src/graph/graph.zigZig → Python wrappers:src/faebryk/core/zig/src/python/graph/graph_py.zigGenerated type stubs:src/faebryk/core/zig/gen/graph/graph.pyiDependants (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)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 byGraphView.destroy().Debugging
GraphView.__repr__()printsGraphView(id=..., |V|=..., |E|=...)from Zig. Graph wrapper has a stress test:python -m faebryk.core.graph(runstest_graph_garbage_collection).