Manager development environment¶

In this guide, we will setup a development environment and discuss tooling.

The manager is written in Python 3 with the goal of supporting multiple versions of Python (3.8 or newer) available in current Linux distributions. These compatibility requirements also force us not to rely heavily on modern runtime libraries such as Pydantic.

Reproducible development environment¶

Because we want to support multiple versions of Python with one codebase, we develop against the oldest supported version and then check in our CI that it works for newer versions of Python. In your distro, there may be a Python runtime of a different version than the one we are targeting. So we try to isolate everything from the system we are running on.

To start working on the manager, you need to install the following tools:

Python: One of the supported versions. You can use pyenv to install and manage multiple versions of Python without affecting your system. Alternatively, some Linux distributions ship packages for older Python versions as well.
Poetry: We use it to manage our dependencies and virtual environments. Do not install the package via pip, follow instructions in Poetry’s official documentation.

Note that you need the latest version of Poetry. The setup has been tested with Poetry version 1.1.7 because of it’s able to switch between Python versions, it must be installed separately to work correctly.

After installing the above tools, the actual fully-featured development environment is ready to be set up.

Running the manager from source for the first time¶

Clone the Knot Resolver GitLab repository.
In the repository, change to the manager/ directory and perform all of the following tasks in that directory.
Run poetry env use $(which python3.12) to configure Poetry to use a Python interpreter other than the system default.

As mentioned above it is recommended to use pyenv to manage other Python versions. Then poetry needs to be told where to look for that version of Python, e.g.:
```
$ poetry env use ~/.pyenv/versions/3.12.1/bin/python3.12
```
Run poetry install --all-extras to install all dependencies including all optional ones (–all-extras flag), in a newly created virtual environment. All dependencies can be seen in pyproject.toml.
Use ./poe run to run the manager in development mode (Ctrl+C to exit). The manager is started with the configuration located in manager/etc/knot-resolver/config.dev.yaml.

Commands¶

In the previous section, you saw the use of the ./poe command. PoeThePoet is a task runner which we use to simplify invoking common commands.

You can run it by invoking ./poe, or you can install it system-wide via pip install poethepoet and invoke it just by calling poe (without the leading ./). When invoked globally, you don’t have to worry about virtual environments and such, PoeThePoet figures that out for you and commands always run in the appropriate virtual environment.

Or, you can create a symlink to the ./poe script without installing PoeThePoet, e.g. ln -s path_to_the_repository/manager/poe /usr/bin/poe.

To list all the available commands, you can run poe help. The commands are defined in the pyproject.toml file. The most important ones for everyday development are:

poe run to run the manager
poe docs to create HTML documentation
poe test to run unit tests (enforced by our CI)
poe check to run static code analysis (enforced by our CI)
poe format to autoformat the source code
poe kresctl to run the manager’s CLI tool

With this environment, everything else should just work. You can run the same checks that CI runs, all the commands listed below should pass. If something fails and you have done all the steps above, please [open a new issue](https://gitlab.nic.cz/knot/knot-resolver-manager/-/issues/new).

Contributing¶

Before committing, please ensure that both poe check and poe test pass. Those commands are both run on the CI and if they don’t pass, CI fails.

Minimal development environment¶

The only global tools that are strictly required are Python and pip (or other way to install PyPI packages). You can have a look at the pyproject.toml file, manually install all other dependencies that you need and be done with that. All poe commands can be run manually too, see their definition in pyproject.toml. We can’t however guarantee, that there won’t be any errors.

Please note that Python’s development files are also required, since the manager also includes a C module that interacts with it. I.e., for distros that package development files separately, you will typically need to install -dev or -devel packages of your current Python version as well.

Packaging¶

Packaging is handled by apkg cooperating with Poetry. To allow for backwards compatibility with Python tooling not supporting PEP-517, we generate setup.py file with the command poe gen-setuppy, so our project is compatible with setuptools as well.

Testing¶

The manager has two suits of tests - unit tests and packaging tests, all residing in the manager/tests/ directory. The units tests are run by pytest, while the packaging tests are distro specific and are using apkg test.

Code editor¶

Feel free to use any text editor you like. However, we recommend using Visual Studio Code with Pylance extension. That’s what we use to work on the manager and we know that it works really well for us. Just make sure to configure the extension so that it uses Poetry’s virtual environment.

FAQ¶

What all those dev dependencies for?¶

Short answer - mainly for managing other dependencies. By using dependency management systems within the project, anyone can start developing after installing just a few core tools. Everything else will be handled automagically. The main concept behind it is that there should be nothing that can be run only in CI.

Core dependencies which you have to install manually:

pyenv: A tools which allows you to install any version of Python regardless of your system’s default. The version used by default in the project is configured in the file .python-version.

We should be all developing on the same version, because otherwise we might not be able to reproduce each others bug’s.

Written in pure shell, no dependencies on Python. Should therefore work on any Unix-like system.
Poetry: A dependency management system for Python libraries. Normally, all libraries in Python are installed system-wide and dependent on system’s Python version. By using virtual environments managed by Poetry, configured to use a the correct Python version through pyenv, we can specify versions of the dependencies in any way we like.

Follows PEP 518 and uses the pyproject.toml file for all of it’s configuration. Written in Python, therefore it’s problematic if installed system-wide as an ordinary Python package (because it would be unavailable in its own virtual environment).

Automatically managed dependencies:

PoeThePoet: A task management system, or in other words glorified switch statement calling other tools. Used for simplifying interactions with the project.
pytest, pytest-cov: unit testing
pylint, flake8: linting
black: autoformatter (might be removed in the future if not used in practice)

Why Poetry? Why should I learn a new tool?¶

This blog post explains it nicely - https://muttdata.ai/blog/2020/08/21/a-poetic-apology.html.