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 should be marked with a marker indicating the environment required to run the tests. The markers for the integration tests should be used exclusively. Integration tests with no special requirement should be marked with

@pytest.mark.integration

For tests requiring a container runtime environment the following markers are available

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

For tests requiring an Apptainer container runtime and Slurm environment the following marker can be used

@pytest.mark.apptainer_slurm

The following table gives an overview about the commands, which can be used to run the corresponding test suite

Marker

pytest

tox

@pytest.mark.integration

pytest -m "integration"

tox -e integration

@pytest.mark.docker

pytest -m "docker"

tox -e docker

@pytest.mark.apptainer

pytest -m "apptainer"

tox -e apptainer

@pytest.mark.apptainer_slurm

pytest -m "apptainer_slurm"

tox -e apptainer_slurm.

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

    Raises:
        FunctionError: Function raises error in case something happens
    """
    return True