OpenReactor: Development
Setting up
Section titled “Setting up”You need uv and just. openreactor supports Python 3.11 and later.
git clone https://github.com/uwo-fast/openreactor.gitcd openreactorjust setup # create the environment from uv.lockjust check # format check, lint, type-checkjust test # run the testsezo-driver installs as a wheel on x86_64 and aarch64 Linux. Elsewhere it builds from source, which needs a C compiler.
Recipes
Section titled “Recipes”just --list shows every recipe:
| Recipe | What it does |
|---|---|
just setup |
Install the locked dependencies. Run uv lock after you edit pyproject.toml. |
just fmt |
Format the code, and apply lint fixes. |
just fmt-check |
Check the formatting without changing anything. |
just lint |
Run ruff. |
just typecheck |
Run pyright. |
just check |
Run fmt-check, lint and typecheck, as CI does. |
just test |
Run pytest. |
just run ARGS |
Run openreactor, for example just run check-config examples/openreactor.toml. |
just vendor |
Download the vendored browser files and record their hashes. |
just build |
Build the sdist and the wheel into dist/. |
just clean |
Remove the environment, and the build and tool caches. |
How the code fits together
Section titled “How the code fits together”flowchart TD browser["Browser"] -->|"pages and htmx"| ui["ui.py"] client["Script"] -->|"/api/v1"| web["web.py"] ui --> service["service.py"] web --> service service -->|"commands"| controller["controller.py<br/>100 ms tick"] cli["cli.py<br/>read, run, ezo cal"] --> controller controller --> rlht["rlht.py<br/>RLHT slices"] controller --> dcmt["dcmt.py<br/>DCMT slices"] controller --> ezo["ezo.py<br/>EZO circuits"] service -->|"starts"| runner["runner.py<br/>profile runs"] controller -->|"polls each tick"| runner runner -->|"setpoints"| rlht runner -->|"duties"| dcmt runner --> profile["profile.py<br/>profile files"] service --> profile cli -->|"profile validate"| profile rlht -->|"crumbs-i2c"| bus[("I2C bus")] dcmt -->|"crumbs-i2c"| bus ezo -->|"ezo-driver"| bus controller -->|"readings and events"| recorder["storage.py<br/>Recorder"] recorder --> db[("SQLite")] service -->|"list and export, read-only"| db cli -->|"runs and export, read-only"| db- Once it is running,
controller.pyis the only code that touches the bus: every device operation runs on its tick, so other code sends it commands and gets aFutureback. Inservethe tick runs on a thread of its own; in the CLI it runs on the main thread. The circuits and slices are opened and checked before the controller starts, and closed after it stops. serverunsweb.pyandui.pyoverservice.py. The middleware insecurity.pysees every request first, anderrors.pyturns the errors an action can raise into HTTP statuses.profile.pyparses and checks a profile. To run one,service.pyadds aProfileRunnerfromrunner.pyto the controller’s polled devices, so it sends the profile’s setpoints and duties on the controller’s thread.read,runandezo calbuild a controller incli.pyand use it directly, without the service.- While a run records, the controller’s thread is the database’s only
writer, through the
Recorderit publishes to. lock.pykeeps a secondserve,read,runorezo calfrom opening the bus while one already has it.
The tests run against fake devices, so they need no hardware. They cannot show how the hardware behaves, so the hardware checks in dev/bench.md are run by hand before a release.
CI runs just check and just test on Python 3.11 and 3.13 for every pull
request and every push to main.
Pre-commit hooks
Section titled “Pre-commit hooks”The pre-commit hooks run gitleaks, whitespace and YAML checks, and ruff. To install them:
pre-commit installThe hooks skip src/openreactor/static/vendor/, so the vendored files stay
exactly as downloaded.
Dependencies
Section titled “Dependencies”Python dependencies are declared in pyproject.toml, pinned in uv.lock,
and updated by Dependabot. They are never vendored.
Vendored browser files
Section titled “Vendored browser files”The browser UI must work on a lab network with no internet, so the few
third-party browser files it needs ship inside the package, under
src/openreactor/static/vendor/.
vendor.toml lists every file: its package, exact version, licence, the URL it came from, and its SHA-256. The UI’s About page lists the same packages, read from that manifest. Each package’s licence file sits beside it.
Follow these rules:
- Never edit a vendored file. openreactor’s own styles and scripts go in
src/openreactor/static/app.cssandapp.js, which load after the vendored ones.tests/test_vendored.pyfails if any file stops matching its recorded hash. - Update a file by bumping its version. Change
versionin the manifest, runjust vendor, and commit the downloaded files with the new hashes it records. The diff then shows exactly which files changed. Read the package’s release notes before merging. - If a patch ever becomes unavoidable, keep it as a
.patchfile beside the manifest, applied byscripts/vendor.pyafter each download, and record the reason in this section. The script does not apply patches yet. - Stop vendoring once the UI needs a build step, such as TypeScript or bundling, or more than a handful of libraries. A JavaScript package manager with a lockfile is then the better tool. Three prebuilt files do not justify one.
Dependabot cannot see these files, so nothing proposes their new releases. Check them when you work on the UI, and always when a security advisory names one of them.
Releasing
Section titled “Releasing”The release workflow publishes to PyPI with Trusted Publishing, so no API token is stored.
- Run the hardware checks in dev/bench.md, and record the results.
- Set the version in
pyproject.toml. - Push a tag
vX.Y.Zthat matches the version inpyproject.toml.
The workflow then:
- checks that the tag matches the version, and stops if it does not;
- builds the sdist and the wheel, and a
constraints.txtfor reproducible installs; - publishes to PyPI from the
pypienvironment, where a required reviewer approves each upload; - creates the GitHub release with the built files and
constraints.txt. A version witha,borrcin it is marked as a pre-release.
To try the same build without releasing, run the workflow by hand on main.
It then publishes to TestPyPI instead.
Fixes on 1.x
Section titled “Fixes on 1.x”The 1.x branch takes
fixes for reported bugs only. GitHub closes an issue from Closes #N only on
a merge into main, so an issue fixed in 1.x is closed by hand.
