facett-py/README.md · nordisk/facett

facett-native

Native Python bindings for facett's component registry — a pyo3 extension built into a wheel with maturin.

This is the headless, direct-call companion to facet-wrapped-web. Where facet-wrapped-web mounts a live egui canvas inside a Streamlit iframe (the interactive embed), this wheel exposes the same crate's pure-Rust registry to Python with no browser, no wasm, and no eframe event loop: enumerate the embeddable components and read each one's initial state directly.

import facett_native as fx

fx.component_count()          # -> 13
fx.component_names()          # -> ['graphnav', 'helix-tube', 'stat-grid', ...]

for c in fx.components():     # [{name, description, title}, ...]
    print(c["name"], "—", c["title"])

state = fx.component_state("stat-grid")   # dict — the component's initial state_json

API

function	returns
`component_count()`	`int` — number of embeddable components
`component_names()`	`list[str]` — the registry names, in order
`components()` / `manifest()`	`list[dict]` — `{name, description, title}` per component
`component_state(name)`	`dict`/`list`, or `None` for an unknown name — the component's initial `state_json`
`version()` / `__version__`	`str` — the facett crate version this wheel was built from

component_state returns exactly the JSON a Streamlit host would read back across the wasm boundary (window.facett_streamlit_state()), delivered here as a native Python object — the same source of truth, without a canvas.

Build

The wheel is not built by pip; it is compiled by maturin from the facett-py Rust crate. From this directory:

maturin build --release          # -> target/wheels/facett_native-*.whl (abi3, cp39+)
maturin develop                  # build + install into the active venv (dev loop)

The crate enables pyo3's abi3-py39 feature, so a single stable-ABI wheel loads on CPython 3.9 and up (including 3.14). The crate is a detached workspace and is excluded from the facett workspace, so cargo build for facett never links libpython — pyo3 is quarantined to this wheel.

Publishing to PyPI is out of scope of the build recipe (build locally only).