Development

We welcome any contributions for improving or further developing this package.

However, please excuse that we are limited in time for development and support.

Some things to keep in mind when adding code…

Install

A few extra libraries are needed for development:

pip install .[dev]

Alternatively, you may use the requirement files requirements_dev.txt or environment_dev.yml.

Import Conventions

The following import conventions are used throughout Locan source code and documentation:

  • import numpy as np

  • import pandas as pd

  • import matplotlib as mpl

  • import matplotlib.pyplot as plt

  • import scipy as sp

  • import open3d as o3d

  • import networkx as nx

  • import boost_histogram as bh

This is enforced through ruff following specifications in pyproject.toml.

Unit tests

For testing we use pytest.

A minimal test suite is provided in src/locan/tests. The extended test suite is provided in tests.

For unit testing we supply test data as data files located in tests/test_data.

Configurations are kept in pyproject.toml.

Coverage

For measuring code coverage in testing we use coverage.py.

Configurations are kept in pyproject.toml.

Code checks

We use black for formating and ruff for code linting.

Configurations are kept in pyproject.toml.

We use mypy for type checking.

Configurations are kept in pyproject.toml.

Versioning

We use SemVer for versioning. For all versions available, see the releases in this repository.

To remember:

  • The package makes use of third party packages that are only used by a few routines.

    These optional packages are treated as extra_dependencies. Import of optional packages is tried in the constants module and a _has_package variable is defined. In each module that makes use of an optional import a conditional import is carried out

    if _has_package: import package

    In addition any user-accessible function that makes use of the optional package raises an import error if the optional package is not available.

    Test functions that require optional dependencies should be marked with:

    @pytest.mark.skipif(not _has_package,reason="requires optional package")

  • The length of code and docstring lines should be kept to 88 and 75 characters, respectively.

  • Use notation n_something for number_of_something.

  • Provide commit messages with subject in imperative style (see Chris Beams, How to Write a Git Commit Message). If possible follow the specifications for conventional commits.