Development¶
anywidget-instruments-automotive is built, tested and released the way anywidget-instruments is, on the front end of which it builds.
Layout¶
| Path | Content |
|---|---|
src/anywidget_instruments_automotive/schema/ |
Trait contract: one JSON Schema per widget, extending the schemas of anywidget-instruments by their $id, and units.schema.json, the unit names by quantity |
js/src/core/ |
view.ts (base view, deriving from that of anywidget-instruments), units.ts (unit systems and conversion), state.ts (missing, stale and invalid values) |
js/src/widgets/ |
One view per widget family; telltales.ts holds the tell-tale functions, colours and symbols |
js/src/index.ts |
The AFM module: _kind selects the view |
js/src/generated/, src/anywidget_instruments_automotive/static/ |
Generated by npm run build: never edited, never committed |
js/test/ |
vitest tests (jsdom), the widgets mounted from plain trait dictionaries as a host with no kernel sets them |
src/anywidget_instruments_automotive/ |
The Python host binding: classes that set traits, nothing more |
tests/ |
pytest tests, and parity/*.json, the cases shared by the front end and every host binding |
js/preview/index.html |
Every widget from plain trait dictionaries; the source of the documentation images |
e2e/ |
Playwright tests: examples/web/ with no kernel; the marimo cluster example, and e2e/notebooks/ in JupyterLab and Notebook 7, with a Python kernel |
examples/ |
A web page with no kernel, a KaimonSlate.jl notebook |
Commands¶
The front end depends on anywidget-instruments at a pinned commit (package.json); the
Python binding needs the same commit, which is not on the package index yet.
npm install && npm run build # contract + bundle
npm run lint && npm run typecheck # eslint, tsc
npm test # vitest
npm run check:reproducible # byte-identical rebuild
npm run images # docs/img/<widget>-light.png and -dark.png (DOC-005)
npm run test:e2e # Playwright: a page with no kernel, marimo, JupyterLab, Notebook 7
# (needs pip install -e . marimo jupyterlab notebook)
pip install "anywidget-instruments @ git+https://github.com/AnywidgetInstruments/anywidget-instruments@<commit of package.json>"
pip install -e ".[dev]"
pytest && ruff check . && ruff format --check . && mypy src
mkdocs serve # this site
npm run images uses the Chromium of Playwright; set PLAYWRIGHT_CHROMIUM to use
another. The Docs workflow runs it before building the site, so that the pictures of
the widgets are always those of the code being published.
The trait contract¶
Every trait of every widget is declared once, in the JSON Schemas of
src/anywidget_instruments_automotive/schema/. npm run gen (part of the build) flattens them,
with the schemas of anywidget-instruments they extend, into:
js/src/generated/contract.ts, the TypeScript types and runtime specs the views read their traits through;static/contract.json, shipped in the wheel for hosts in any language, with the unit names the front end accepts (UNIT-017).
tests/test_contract.py fails when a Python class diverges from the contract, tsc
when a view does. A host writes traits and only traits: a value in input_unit, a unit
name from the contract. The front end converts, rounds and decides what is shown; a
trait its schema rejects is shown as INVALID, never replaced by a guess (HOST-004).
Adding a widget¶
- Write its schema, deriving from
automotive.schema.json(orquantity.schema.jsonfor a physical quantity), with a_kindstarting withawa-. - Write its view in
js/src/widgets/, deriving fromAutomotiveView, and register the kind injs/src/index.ts; tests injs/test/. - Write its Python class, deriving from
AutomotiveWidget, and export it. - Add it to
js/preview/index.htmlas adata-shotsection, runnpm run images, and document it in the catalog. - Update the requirements status.