Development Guide

Ready to contribute to the project? Here is how to set up a local development environment.

Initial Setup

  1. Fork the cda-tum/mqt-predictor repository on GitHub (see https://docs.github.com/en/get-started/quickstart/fork-a-repo).

  2. Clone your fork locally

    $ git clone git@github.com:your_name_here/mqt-predictor

  3. Change into the project directory

    $ cd mqt-predictor

  4. Create a branch for local development

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. (Optional, highly recommended) Set up a virtual environment

    $ python3 -m venv venv
$ source venv/bin/activate

    Note

    If you are using Windows, you can use the following command instead:

    $ python3 -m venv venv
$ venv\Scripts\activate.bat

    Ensure that pip, setuptools, and wheel are up to date:

    (venv) $ pip install --upgrade pip setuptools wheel

  6. (Optional) Install pre-commit to automatically run a set of checks before each commit.

    (venv) $ pipx install pre-commit
(venv) $ pre-commit install

    If you use macOS, then pre-commit is in brew, use brew install pre-commit.

Building the Python module

The recommended way of building the Python module is to perform an editable install using pip.

(venv) $ pip install -e .

The --editable flag ensures that changes in the Python code are instantly available without re-running the command.

Running Python Tests

The Python part of the code base is tested by unit tests using the pytest framework. The corresponding test files can be found in the tests/ directory.

(venv) $ pip install -e ".[test]"
(venv) $ pytest

This installs all dependencies necessary to run the tests in an isolated environment, builds the Python package, and then runs the tests.

Python Code Formatting and Linting

The Python code is formatted and linted using a collection of pre-commit hooks. This collection includes:

  • ruff – an extremely fast Python linter and formatter, written in Rust.

  • mypy – a static type checker for Python code

You can install the hooks manually by running pre-commit install in the project root directory. The hooks will then be executed automatically when committing changes.

(venv) $ pre-commit run -a