Development#

Prerequisites:

  • uv for package management and virtual environments.

  • direnv (recommended) for automatic environment activation.

  • make for running development tasks.

Dependencies and their versions are specified in pyproject.toml (with dependency groups for dev, lint, tests and docs) and locked in uv.lock. Lockfile updates are automated via GitHub Actions and Renovate.

Setting up a development environment with direnv#

The project includes an .envrc file that automatically creates a virtual environment (honoring .python-version), activates it and syncs all dependencies:

direnv allow
make init  # install pre-commit hooks

Setting up a development environment manually#

uv venv
uv sync --locked --all-groups --all-extras
uv run pre-commit install

Available Make targets#

Run make help to see all available targets. Key commands:

make lint       # run pre-commit on all files
make test       # run pytest with coverage
make cov        # combine and report coverage
make type       # run mypy type checking
make xdoc       # run xdoctest
make test-all   # run all of the above
make docs       # build Sphinx documentation
make docs-serve # serve docs locally

If pre-commit fails during a push, stage changes, amend the commit, and push again.

Building docs#

make docs
make docs-serve

sphinx-autoapi automatically discovers and documents the API from src/. No manual sphinx-apidoc run is needed.

Bump and releasing#

Version bumping uses git-cliff for changelog generation and uv version for version management:

make bump   # bump version, update changelog, commit and tag
make ch     # update CHANGELOG.md only

make bump will refuse to run on a dirty working tree. After bumping, push the commit and tag:

git push && git push --tags

Release to PyPI is automated via GitHub Actions on tag push.

To keep a clean development history, use branches and PRs:

gh pr create --fill
gh pr merge --squash --delete-branch [-t "fix|ci|feat: msg"]

Configuration files#

Configuration files:

  • pre-commit configured in .pre-commit-config.yaml;

  • ruff (linting and formatting) configured in pyproject.toml;

  • pydoclint configured in pyproject.toml;

  • typos configured in pyproject.toml;

  • coverage configured in pyproject.toml;

  • mypy configured in pyproject.toml;

  • git-cliff configured in cliff.toml;

  • yamlfmt configured in .yamlfmt.yml;

  • taplo (TOML formatting) configured in .taplo.toml;

  • mdformat configured in .mdformat.toml.