Developer Guide

Setting up the development environment

Clone the repository and navigate into it:

git clone git@gitlab.npl.co.uk:eco/tools/eomatch.git
cd ./eomatch

Create a new branch for your contributions:

git checkout -b new-branch-name
git push --set-upstream origin new-branch-name

Install the package with the developer optional dependencies:

pip install -e .[dev]

Install the pre-commit hooks:

pre-commit install

Before you push

Linting and formatting

eomatch uses ruff for linting and formatting (line length 120), enforced by a pre-commit hook. If the hook changes any files the commit is aborted so you can review them; commit again once you are happy. To run it manually:

ruff check --fix .
ruff format .

Type checking

eomatch uses mypy for static type analysis (ignore_missing_imports = True). Run it before pushing:

mypy ./eomatch

Running tests

Tests live in a tests/ folder next to the code they cover (e.g. eomatch/tests/, eomatch/finder/tests/, eomatch/enrich/tests/, eomatch/utils/tests/) and use pytest. Run the full suite with:

pytest

To run a single test file:

pytest eomatch/tests/test_domain.py

To run a single test:

pytest eomatch/tests/test_domain.py::TestMatchup::test_collocation_region

Compiling documentation

eomatch uses sphinx to build its documentation. After editing the docs/ source files, verify that everything compiles correctly:

sphinx-build docs docs/_build -b html

Then open docs/_build/index.html in a browser to review the output. The build should finish without warnings.

Examples in the docs use the IPython directive (IPython.sphinxext.ipython_directive). Examples that run offline are executed at build time with .. ipython:: python. Examples that need network access, credentials or downloaded data are shown with :verbatim: (typed with In [n]: prompts and a hand-written Out[n]:) so the build never depends on them.

When adding a new public class or function:

• List it in docs/content/user/api.rst (or docs/content/developer/internal_api.rst for internal utilities).

• Add a usage example in the relevant user-guide page.

• Make sure every public method has a Sphinx-style docstring with :param: and :return: entries.