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 and Naming Conventions

The project follows the PEP0008 naming conventions for functions and variables. The Ruff linter is used to ensure proper code formatting. The documentation is based on Sphinx. 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