Contributing

SymBRiM has been designed to be extended by the community. If you have a bug or a feature request, please open an issue on GitHub. If you would like to contribute, feel free to fork the repository and submit a pull request. To establish an effective development environment, we’ve taken inspiration from Hypermodern Python by Claudio Jolowicz and Setting up Python Projects by Johannes Schmidt. This page provides a brief overview of the various tools used in the development process. For the installation of the development environment, please refer to the Installation page.

Linting

Linting is used to maintain a consistent code style across contributors. We’ve adopted the ruff linter, because it is fast and already supports quite a lot of rules. Quite a lot of the rules have been incorporated, as they support the goal and they are conveniently applied through a pre-commit hook. Type hinting is only used in function signatures, as it also improves the readability and interface. No static type checker, like mypy, is used to enforce and check types due to it resulting in just a lot of extra complications. To run ruff manually use the following (--fix automatically fixes most issues):

ruff . --fix

Testing

The test suite uses pytest with a code coverage of 100%. This ensures that the code is fully tested, which is important to check regressions and to ensure that the code works as expected. If a feature can for some reason not be fully tested, then the lines or functions can be ignored using # pragma: no cover. To run the tests use:

pytest .

When generating a coverage report locally, we recommend using:

pytest --cov --cov-report html

Documentation

The documentation is build using sphinx. As SymBRiM is expected to expand quite a lot we have chosen to use sphinx.ext.autodoc in combination with sphinx.ext.autosummary to generate the entire API reference including its structure from the source code. Therefore, it is important to document classes properly. To build the documentation you can use:

docs/make.bat html