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 best way to contribute is to fork the main repository, make your modifications and then create a pull request on github. The repository has two branches:

  • master than contain the current released version.

  • dev where the main development takes place.

The code should be tested in dev before being merged to master for release. Any larger, possibly breaking changes should be done in a feature branch from dev.

Development environment

We use PDM to manage the environment and dependencies. Once the repository is cloned, you can create a virtual environment and install itzi in editable mode alongside the dependencies with:

pdm install

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

The default dependency resolver of PDM might fails. If so, install uv and set pdm to use it:

pdm config use_uv true

Cython code

The install script should automatically compile the Cython code. However, if you want to compile it manually, you can do so by running the following command in the root directory of the repository:

cython -3 src/itzi/flow.pyx
pdm install

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.

pdm run pytest --forked -v

To estimate the test coverage:

pdm run pytest --cov=itzi --forked -v

Select the python version to test against with pdm use. Test against the 3 last versions of python. In april 2025, that would be 3.11, 3.12 and 3.13.

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. Then you can 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

Once a potential feature branch is merged into dev:

  • Make sure all the tests pass

  • Merge dev into master

  • 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 and push to pypi

  • Write a blog post announcing the version

  • Post a link to the announcement on the user mailing list