User Guide¶

pyproject.toml file and dependency management¶

If your project doesn’t have a pyproject.toml file, simply copy the one from the template and update file according to your project.

For managing dependencies, Poetry is the recommended tool for our team. Hence, install Poetry to setup the development virtual environment. Poetry supports optional dependency groups which help manage dependencies for different parts of development such as documentation, testing, etc. The core dependencies are installed using the command:

python3 -m poetry install

Additional dependency groups can be installed using the --with flag. For example:

python3 -m poetry install --with docs,test

mypy configuration options

By default, the mypy configuration in the pyproject.toml disallows subclassing the Any type - allow_subclassing_any = false. In cases where the type checker is not able to determine the types of objects in some external library (e.g. PyTorch), it will treat them as Any and raise errors. If your codebase has many of such cases, you can set allow_subclassing_any = true in the mypy configuration or remove it entirely to use the default value (which is true). For example, in a PyTorch project, subclassing nn.Module will raise errors if allow_subclassing_any is set to false.

pre-commit¶

You can use pre-commit to run pre-commit hooks (code checks, liniting, etc.) when you run git commit and commit your code. Simply copy the .pre-commit-config.yaml file to the root of the repository and install the test dependencies which installs pre-commit. Then run:

pre-commit install

If you prefer to not enforce using pre-commit every time you run git commit, you will have to run pre-commit run --all-files from the command line before you commit your code.

hook configuration

Some of the pre-commit hooks use supported hooks from the web.

For some others, they are locally installed and hence use the python virtual environment locally. If language is set to python, each time the hook is installed, a separate python virtual environment is created and you can specify dependencies needed using additional_dependencies.

If language is set to system, the activated python virtual environment is used and and hence you have to ensure that the required dependencies and their versions are correctly installed.

  - repo: local
    hooks:
    - id: pytest
      name: pytest
      entry: python3 -m pytest -m "not integration_test"
      language: python/system # set according to your project needs

typos

The typos pre-commit hook is used to check for common spelling mistakes in the codebase. While useful, it may require some configuration to ignore certain words or phrases that are not typos. You can configure the typos hook in the pyproject.toml file. In a large codebase, it may be useful to disable the typos hook and only run it occasionally on the entire codebase.

pre-commit ci¶

Instead of fixing pre-commit errors manually, a CI to fix them as well as update pre-commit hooks periodically can be enabled for your repository. Please check pre-commit.ci and add your repository. The configuration for pre-commit.ci can be added to the .pre-commit-config.yaml file.

documentation¶

If your project doesn’t have documentation, copy the directory named docs to the root directory of your repository. The provided source files use Furo, a clean and customisable Sphinx documentation theme.

In order to build the documentation, install the documentation dependencies as mentioned in the previous section, navigate to the docs folder and run the command:

make html

You can configure the documentation by updating the docs/source/conf.py. The markdown files in docs/source can be updated to reflect the project’s documentation.

github actions¶

The template consists of some github action continuous integration workflows that you can add to your repository.

The available workflows are:

code checks: Static code analysis, code formatting and unit tests
documentation: Project documentation including example API reference
integration tests: Integration tests
publish: Publishing python package to PyPI. Create a PYPI_API_TOKEN and add it to the repository’s actions secret variables in order to publish PyPI packages when new software releases are created on Github.

The test workflows also compute coverage and upload code coverage metrics to codecov.io. Create a CODECOV_TOKEN and add it to the repository’s actions secret variables.