Developer notes#

Environment setup#

You need poetry in order to setup the development environment. Once it is installed, simply run

poetry install
poetry run pre-commit install

which will create a virtual environment with the required development dependencies. It also installs pre-commit hooks, which runs some code quality tools before each commit.

You can then enter the virtual environment with one of the following commands:

eval $(poetry env activate)              # For Bash/Zsh/Csh
eval (poetry env activate)               # For Fish
Invoke-Expression (poetry env activate)  # For Powershell

Tests#

Phileas includes different tests, which are located in the test package. You can run the test suite for your current Python version with

python -m unittest --buffer --verbose

You can run the test suite for all the supported Python versions with

tox

Dependencies#

Supported Python versions#

Phileas only supports currently maintained Python versions. For now, it starts at version 3.10, and stops at version 3.13.

Adding dependencies#

To add a new dependency to the project, you must:

  • Use poetry add to update the pyproject.toml file with your new requirement.

  • Update poetry.lock with poetry lock.

  • This might break the pre-commit type checker. In this case, update .pre-commit.config.yaml with the required additional_dependencies.

  • Update /doc/source/getting_started/installation.md accordingly.

  • Finally, commit all these files. Do not forget to include poetry.lock.

Updating dependencies#

When you update dependencies, you should also update the pre-commit type checker additional_dependencies accordingly.

Type checking#

Phileas relies on mypy for type checking. It is called at different steps:

  • you can call it manually whenever you want;

  • the installed pre-commit hooks automatically run it before each commit;

  • tox invokes it.

ruamel.yaml is used for YAML parsing. Due to this unsolved issue and this related one, you are likely to encounter the error:

error: Skipping analyzing "ruamel": module is installed, but missing library stubs or py.typed marker  [import-untyped]

This can be fixed by using the --no-incremental flag. However, this increases the verification time. This flag is enabled in the tox configuration, however it is not in the pre-commit configuration. Rather, we recommend

  • manually checking the pre-commit output, and ensure that the only error is due to the ruamel.yaml issue;

  • skip verification with the --no-verify flag of git commit.

Rust integration#

Phileas uses maturin to run Rust code from Python. The project is described in /Cargo.toml, the source files are stored in /src/, and the Python bindings are available in the phileas._rust module. You should declare typing stubs for the exposed Rust functions in /phileas/_rust.pyi.

Upon modifying the Rust project, you should recompile it before using the Python code that uses it. This can be done with

poetry run maturin develop

which installs the up-to-date _rust module in the development virtual environment. Alternatively, you can enable a Python import hook that will make sure that the latest Rust code version is used, whenever you start a Python interpreter. You can do it with

poetry run python -m maturin_import_hook site install

However, note that it will induce a delay at each interpreter start. Thus, it might be a good idea to uninstall the hook when working on pure Python code, with

poetry run python -m maturin_import_hook site uninstall

Performance benchmark#

A performance benchmark is available by calling python -m phileas benchmark. It compares the iteration speed of different iteration trees. When implementing a new node or leaf, it is advised to add a corresponding test.

CI#

tox is used to run code quality, coverage and tests for different Python versions. You can simply invoke it with

tox

The coverage report is then available in /htmlcov.

Documentation#

The documentation is generated with sphinx. You can build the HTML pages with

sphinx-build doc/source/ doc/build/

It is then accessible in /doc/build/index.html. Alternatively, it is convenient to use sphinx-autobuild, which automatically updates the documentation, and exposes it on a local server:

sphinx-autobuild doc/source/ doc/build/

The documentation coverage can be obtained with

sphinx-build -M coverage doc/source/ doc/coverage/

It is then accessible in /doc/coverage/.