Style guide#
We aim to keep the cotainr code base and documentation consistent by following the style guidelines listed here.
We follow the PEP 8 style guide.
All metadata and tool configurations are defined in the pyproject.toml file, except where this is not possible, e.g. for pre-commit and ReadtheDocs.
The Python source code is formatted using Ruff - see the cotainr pyproject.toml file for the Ruff rules we use.
The codebase is linted with pre-commit - see the cotainr .pre-commit-config.yaml file for the pre-commit hooks we use.
All docstrings are formatted according to the numpydoc format.
We reference the python interpreter executable as python3 (not python) when explicitly calling the system python executable and as
sys.executablewhen reinvoking the interpreter as recommended in PEP 394.No (hard) line wrapping is used in restructured text and markdown files placed in the doc/ directory (the cotainr reference documentation files).
When hacking on cotainr, we generally try to:
Error early.
Use self-describing commands and options.
Use comments to explain why something is done, not how.
Include unit and integration tests for new features and bug fixes.
Make it simple.
Specifically, we use the following conventions:
Force keyword only arguments to functions and methods (as defined in PEP 3102).
Use relative imports within the cotainr package when importing functionality from other modules. The imports must be done such that all objects imported are still references (not copies) which allows for monkey patching objects in their definition module in tests.
pre-commit#
If you like, you can use pre-commit to automatically check and format your code using a git pre-commit hook. The pre-commit tool is included in the lint dependency group (which is also part of the dev dependency group) in the cotainr pyproject.toml file. Thus, an easy way to install pre-commit and set up the pre-commit hooks for cotainr using the uv package manager is to run the following commands in the checked out cotainr git repository root directory:
uv sync --group lint
uv run pre-commit install
This will install the pre-commit hooks defined in the .pre-commit-config.yaml. The pre-commit hooks will then automatically run when you run git commit in the repository. The CI/CD workflow uses the same pre-commit configuration for linting and formatting.