Contribution Guide

The package uses hatch as build backend. To build the source distribution (sdist) and the python wheel run

hatch build

For a developer install via pip in editable mode:

git clone git@codebase.helmholtz.cloud:fwdc/python.git
pip install --editable python[dev]

Static Code Analysis (Linting)

To run the static code checks install pre-commit and activate the git hooks

pre-commit install

The dictionary with words excluded for spell checking is located in .gitlab/config/ignore_words.txt.

Unit Testing

Unit tests can either be executed via pytest within a virtual environment or your system python environment or for multiple python version (to check compatibility) via tox.

To execute the unit tests run pytest without any option or select a specific test with pytest -k <test>. To capture the output written to stdout use pytest -s and for more verbose output pytest -vv.

For running all tests for each supported python version run the tests with the tox command. All unit tests are executed and a coverage report will be generated.

Integration Testing

Integration tests are also available and should be marked with

@pytest.mark.integration

If an integration test requires a container runtime environment, further markers are available

@pytest.mark.apptainer
@pytest.mark.docker

To execute the all integration tests run pytest -m "integration" or tox -e integration,integration-docker,integration-apptainer. To execute only integration tests without container runtime run pytest -m "integration and not apptainer and not docker" or tox -e integration. To execute the container runtime integration tests run pytest -m "integration and <docker|apptainer>" or tox -e integration-docker or tox -e integration-apptainer.

Documentation

To build the documentation run

sphinx-apidoc --no-toc -f -o docs multiphasepy
sphinx-build -b html docs docs/_build

documentation is done according to Google Python Style Guide and for type hinting use PEP0484. An example is given below

def func(arg1: int, arg2: str) -> bool:
    """Summary line.

    Extended description of function.

    Args:
        arg1: Description of arg1
        arg2: Description of arg2

    Returns:
        Description of return value

    """
    return True