Developers Guide

Set-up the development environment

Pip based environment

$ python3 -m venv --prompt venv .venv
$ source .venv/bin/activate
(venv) $ python3 -m pip install -r requirements-dev-txt

Conda based environment

$ conda create -c conda-forge -n bpack \
    --file requirements-dev.txt python=3

Debian/Ubuntu

$ sudo apt install python3-bitstruct python3-bitarray \
    python3-pytest python3-pytest-cov \
    python3-sphinx python3-sphinx-rtd-theme

Testing the code

Basic testing

$ python3 -m pytest

It is also recommended to use the -W=error option.

Advanced testing

Tox (>4) is used to run a comprehensive test suite on multiple Python version. It also checks formatting, coverage and ensures that the documentation builds properly.

$ tox run

Test coverage

$ python3 -m pytest --cov --cov-report=html --cov-report=term bpack

Check code style and formatting

The code style and formatting shall be checked with flake8 as follows:

$ python3 -m flake8 --statistics --count bpack

Moreover, also the correct formatting of “docstrings” shall be checked, using pydocstyle this time:

$ python3 -m pydocstyle --count bpack

A more strict check of formatting can be done using black:

$ python3 -m black --check bpack

Finally the ordering of imports can be checked with isort as follows:

$ python3 -m isort --check bpack

Please note that all the relevant configuration for the above mentioned tools are in the pyproject.toml file.

Build the documentation

$ make -C docs html

Test code snippets in the documentation

$ make -C docs doctest

Check documentation spelling

$ make -C docs spelling

Update the API documentation

$ rm -rf docs/api
$ sphinx-apidoc --module-first --separate --no-toc \
    --doc-project "bpack API" -o docs/api \
    --templatedir docs/_templates/apidoc \
    bpack bpack/tests