Contributing

Development Environment

Development of this project is done using the supported Python version most recently released. Note that tests are run against all supported versions of Python; see: Testing & Coverage for additional information.

This project uses uv to manage dependencies. With your fork cloned to your local machine, you can install the project and its dependencies to create a development environment using:

$ uv venv
$ uv sync --all-extras --dev

A pre-commit configuration is also provided to create a pre-commit hook so linting errors aren't committed:

$ pre-commit install

mypy is also used by this project to provide static type checking. It can be invoked using:

$ mypy .

Note that mypy is not included as a pre-commit hook.

Testing and Coverage

A pytest suite is provided, with coverage reporting from pytest-cov. A tox configuration is provided to test across all supported versions of Python. Testing will be skipped locally for Python versions that cannot be found; all supported versions are tested in CI.

$ tox

Details on missing coverage, including in the test suite, is provided in the report to allow the user to generate additional tests for full coverage. Full code coverage is expected for the majority of code contributed to this project. Some exceptions are expected, primarily around code whose functionality relies on either user input or the presence of external drives; these interactions are currently not mocked, though this may change in the future.

Documentation

MkDocs

Library documentation is written using MkDocs and mkdocstrings and contained in the ./docs/ directory. Unless otherwise agreed upon, documentation should be provided for all public interfaces. In progress documentation can be viewed using mkdocs serve, and a tox tonfiguration is also provided to render the static HTML to the ./site/ directory for previewing if desired:

$ tox -e mkdocs

cog

The project README contains some dynamic content generated by cog. The included tox configuration will also these sections, and you can also invoke manually using:

$ tox -e cog