Skip to content

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

  1. Write its schema, deriving from automotive.schema.json (or quantity.schema.json for a physical quantity), with a _kind starting with awa-.
  2. Write its view in js/src/widgets/, deriving from AutomotiveView, and register the kind in js/src/index.ts; tests in js/test/.
  3. Write its Python class, deriving from AutomotiveWidget, and export it.
  4. Add it to js/preview/index.html as a data-shot section, run npm run images, and document it in the catalog.
  5. Update the requirements status.