library
- 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.
# Library Module
The `library` module (located in `src/faebryk/library/`) contains the collection of reusable components, traits, and interfaces that form the "standard library" of the hardware design language.
## Quick Start
```python
import faebryk.core.faebrykpy as fbrk
import faebryk.core.graph as graph
import faebryk.library._F as F
g = graph.GraphView.create()
tg = fbrk.TypeGraph.create(g=g)
resistor = F.Resistor.bind_typegraph(tg=tg).create_instance(g=g)
```
## Relevant Files
- **Facade (auto-generated)**: `src/faebryk/library/_F.py`
- Eagerly imports and re-exports library modules/types for the `import faebryk.library._F as F` pattern.
- This file is generated; do not hand-edit it.
- **Generator**: `tools/library/gen_F.py`
- Scans `src/faebryk/library/*.py`, detects whether the file contains a same-named class, and writes `_F.py`.
- Orders exports via a topological sort of `F.<Name>` references to avoid import-order cycles.
- **Components**: `src/faebryk/library/` contains specific component definitions (e.g. `Resistor.py`, `Capacitor.py`, `LED.py`).
- **Traits/Interfaces**: Also contains trait definitions (e.g. `can_bridge.py`, `is_power.py`).
## Dependants (Call Sites)
- **User Code**: atopile projects heavily import from `faebryk.library._F` (aliased as `F`).
- **Compiler**: The compiler maps `ato` built-ins to these classes.
## How to Work With / Develop / Test
### Core Concepts
- **Traits vs Components**: Use Traits for behavior (what it *can do* like `can_bridge`) and Components for physical things (what it *is* like `Resistor`).
- **Export model**: `_F.py` is a generated “barrel” module; importing it is intentionally convenient but can be heavyweight.
### Development Workflow
1. **New Component**: Create a new file `MyComponent.py` in `src/faebryk/library/`. Inherit from `Node` (or a more specific base).
2. **Naming Convention**: Class names should match the file basename (usually).
3. **Regenerate `_F.py`**: run `python tools/library/gen_F.py` and commit the updated `src/faebryk/library/_F.py`.
### Testing
- Library tests live under `test/library/` (including `test/library/nodes/`).
- A good smoke test for new modules is:
- `ato dev test --llm test/library/test_instance_library_modules.py -q`
## Best Practices
- **Atomic Parts**: Mark leaf components (specifically verified part numbers) with the `is_atomic_part` trait.
- **Parameters**: Use `F.Parameters` to define physical properties like `resistance`, `capacitance`, etc.
- **Documentation**: Add docstrings to components explaining their ports and parameters.
Sections and files
Listed in source order.
sections -> Quick Start → Relevant Files → Dependants (Call Sites) → How to Work With / Develop / Test → Core Concepts → Development Workflow
terms -> Facade (auto-generated) · Generator · Components · Traits/Interfaces · User Code · Compiler · Traits vs Components · Export model
files/cmd -> library · src/faebryk/library/ · src/faebryk/library/_F.py · import faebryk.library._F as F · tools/library/gen_F.py · src/faebryk/library/*.py · _F.py · F.<Name>
body sha256 -> c9619f7188a4
Relevant Files
Facade (auto-generated):
src/faebryk/library/_F.pyEagerly imports and re-exports library modules/types for theimport faebryk.library._F as Fpattern. This file is generated; do not hand-edit it. Generator:tools/library/gen_F.pyScanssrc/faebryk/library/*.py, detects whether the file contains a same-named class, and writes_F.py.Dependants (Call Sites)
User Code: atopile projects heavily import from
faebryk.library._F(aliased asF). Compiler: The compiler mapsatobuilt-ins to these classes.Core Concepts
Traits vs Components: Use Traits for behavior (what it can do like
can_bridge) and Components for physical things (what it is likeResistor). Export model:_F.pyis a generated “barrel” module; importing it is intentionally convenient but can be heavyweight.Development Workflow
New Component: Create a new file
MyComponent.pyinsrc/faebryk/library/. Inherit fromNode(or a more specific base). Naming Convention: Class names should match the file basename (usually). Regenerate_F.py: runpython tools/library/gen_F.pyand commit the updatedsrc/faebryk/library/_F.py.Testing
Library tests live under
test/library/(includingtest/library/nodes/). A good smoke test for new modules is:ato dev test --llm test/library/test_instance_library_modules.py -q