Programer’s manual

Itzï is written principally in Python. The computationally intensive parts of the code are written in Cython.

Source code management

The source code is managed by git and hosted on GitHub. The main repository has only the one branch, the main branch. The best way to contribute is to fork the main repository, create a specific branch for your changes, then create a pull request on github.

Development environment

We use uv to manage the environment and dependencies. Once the itzi repository is cloned and uv installed, you can run itzi with:

uv run itzi

This will create a virtual environment, install all the dependencies listed in the pyproject.toml file, and build the Cython extensions. Now, every change you make to the Python code will be directly reflected when running the tests or uv run itzi .

Cython code

After editing the Cython code, you need to compile it again. You can do so by running the following command in the root directory of the repository:

uv pip install -e .

Profiling

Changed in version 25.7.

Profiling is activated by setting the environment variable ITZI_PROFILE=1. pyinstrument is part of the dev dependencies, so it should be installed when using uv in dev mode. Running itzi in the CLI will write the profiling report to the terminal.

Additionally, the tests cases ea8a, ea8b and tutorial are also profiled and save the results to text files in the form *_profile.txt inside the test_data_temp directory.

Testing

Testing is done with pytest. Due to global variables in GRASS (see issue), the tests must be run in separate processes using pytest-forked.

uv run pytest --forked -v tests/

To estimate the test coverage:

uv run pytest --cov=itzi --forked -v tests/

Select the python version to test against with the –python option. For example uv run –python 3.12 pytest tests/ for python 3.12. This will automatically install the correct python version. Test against the 3 last versions of python.

Coding style

Code formatting and linting is done with ruff. Formatting is checked automatically before each commit with a pre-commit hook. pre-commit hooks should be installed after first cloning the repository by following the instructions on the pre-commit official website.

Documentation

The documentation is written in reStructuredText and is built with Sphinx. It is located in the docs directory. It is automatically built and published on readthedocs. To build the documentation locally, you first need to install sphinx, along with sphinx-argparse and sphinx_rtd_theme. You can then build the documentation locally:

cd docs
sphinx-build . _build

Continuous integration

Tests are automatically run with GitHub Actions. Before committing changes to the workflows, test them locally using act.

Release process

  • Make sure all the tests pass

  • Bump the version number in the pyproject.toml file and the documentation conf.py

  • Write the release notes

  • Update the documentation if necessary

  • Run the tests one last time

  • Create an annotated tag for version number

  • Create the package using the Build CI workflow

  • Test the package locally

  • Push to pypi

  • Write a blog post announcing the version

  • Post a link to the announcement on the user mailing list and social networks