Contributing¶
Setting up¶
pluxeo uses uv.
Everyday commands¶
make test # the test suite
make lint # ruff, ruff format --check, ty, pyrefly and mypy on src/
make format # format and apply safe fixes
make test-cov # coverage report
uv run nox # tests on every supported Python (3.11 to 3.15)
A change must satisfy every checker make lint runs, not only one of them. Ruff runs with every rule selected; a rule is silenced only with a comment saying why.
Layout¶
src/pluxeo/
__init__.py the public API; everything else is private
_manager.py PluginManager
_spec.py Plugin, PluginSpec, @plugin
_discovery.py discovery sources
_lifecycle.py listeners, generator teardown
_contracts.py contract policy
_dispatch.py Pluggy markers and the inner Pluggy manager
_async.py the async hook caller
_enablement.py enablement policies
_state.py states and exceptions
cli.py pluxeo index
tests/
a_unit/ unit tests, one module per area: test_phaseN_*.py
b_integration/
c_e2e/
docs/ this site
Test modules are named after the build phase that introduced the area they cover (test_phase4_dispatch.py, test_phase11_composability.py); a new test usually belongs in the module of the area it touches.
Rules a change must keep¶
The architecture lists the invariants; the tests enforce them. Two deserve repeating:
- Every instance through its factory. Never instantiate a plugin class directly; call
spec.factory(). A dedicated test checks this on every discovery path. - Hooks live iff loaded and enabled. Any change touching loading, unloading, enabling or errors must keep this true at every step, including while a plugin's cleanup runs.
Out of scope, so please do not add them speculatively: a dependency-injection container, async hook wrappers, file-system watching, multi-version plugins, hooks into build backends.
The documentation¶
The site is built with Zensical from docs/:
cd docs
make serve # local preview, rebuilt on change
make build # the static site, in docs/site/
make diagrams # redraw the SVG diagrams from docs/diagrams/*.typ (needs typst)
Code examples on the guide pages run as written: keep them that way when changing the API.