Contributor guidelines

Developer prerequisites

pre-commit

Refer to pre-commit for installation instructions.

TL;DR:

curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv
uv tool install pre-commit  # Install pre-commit
pre-commit install  # Install pre-commit hooks

Installing pre-commit will ensure you adhere to the project code quality standards.

Code standards

ruff and doc8 will be automatically triggered by pre-commit.

ruff is configured to do the job of black and isort as well, so all the standards apply.

Still, if you want to run checks manually:

make pre-commit

Requirements

Requirements are compiled using uv.

make compile-requirements
make compile-requirements_upgrade

Virtual environment

You are advised to work in virtual environment.

TL;DR:

make create-venv
make install

Documentation

Check documentation.

Testing

Note

Python code snippets in the documentation are tested using pytest-codeblock.

Check testing.

If you introduce changes or fixes, make sure to test them locally using all supported environments. For that use tox.

tox

For quick testing in current environment only:

make test

In any case, GitHub Actions will catch potential errors, but using tox speeds things up.

Pull requests

You can contribute to the project by making a pull request.

For example:

To fix documentation typos.
To improve documentation (for instance, to add new recipe or fix an existing recipe that doesn’t seem to work).
To introduce a new feature (for instance, add support for a non-supported file type).

Good to know:

Test suite makes extensive use of parametrization. Make sure you have added your changes in the right place.

General list to go through:

Does your change require documentation update?
Does your change require update to tests?
Did you test both Latin and Unicode characters?
Does your change rely on third-party cloud based service? If so, please make sure it’s added to tests that should be retried a couple of times. Example: @pytest.mark.flaky(reruns=5).

When fixing bugs (in addition to the general list):

Make sure to add regression tests.

When adding a new feature (in addition to the general list):

Check the licenses of added dependencies carefully and make sure to list them in prerequisites.
Make sure to update the documentation (check whether the installation, features, recipes and quick start require changes).

Questions

Questions can be asked on GitHub discussions.

Issues

For reporting a bug or filing a feature request use GitHub issues.

Do not report security issues on GitHub. Check the support section.