Developer guide#

The project follows the standard ESRF Ewoks applications designes.

Local environment#

Create a virtual environment and install the development extras:

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e ".[dev]"

This brings the test extra together with the linters and formatters used by the CI.

Run the test suite#

pytest

Unit tests live under src/ewokstomo/tests. Some tests rely on ESRF datasets stored in src/ewokstomo/tests/data; keep fixtures small so that they remain version-control friendly.

Linting and formatting#

  • ruff check . – static analysis and style hints.

  • ruff format . – code formatting.

  • bandit -r . – basic security checks.

CI pipelines mirror these tools; run them locally before submitting a merge request to reduce turnaround time.

Documentation#

The Sphinx documentation lives under doc. Regenerate the HTML locally with:

pip install -e ".[doc]"
sphinx-build -b html doc doc/_build/html

The index page follows the structure used by the Ewoks application family. When you introduce a new task follow the input and output Pydantic models.

Coding conventions#

  • Prefer explicit typing; type hints are surfaced in the generated API docs.

  • Keep task inputs/outputs stable for downstream workflows. When a breaking change is required, update all bundled workflow JSON files and record the change in the changelog (for ESRF tasks, apply the changes to Blissoda).

  • Tests should focus on behaviour (expected outputs, error handling) rather than internal implementation details. Try to test the task, its methods and a complete workflow to increate robustness.