Managing python dependencies

CantusDB uses poetry to manage python dependencies. Poetry is used both to install relevant dependencies inside the django application container and can be used to install dependencies in a virtual environment for use during development.

Installing poetry

To install poetry for local environment management, follow the instruction in the poetry documentation. Installing "With the Official Installer" is probably the easiest option for most developers.

Installing python packages

Poetry will create a virtual environment for CantusDB and install python dependencies in that environment. Note that poetry will try to find a compatible version of python on your local system, so you'll separately need to make sure you've done this (pyenv is a useful tool for managing multiple python versions on a single system).

1. Navigate to the repository's root directory.
2. Run poetry install (see note below about installing optional dependency groups). If there already exists a virtual environment for the project and you have modified the poetry.lock file (by adding or removing a dependency), add the --sync flag.

CantusDB dependencies are divided into 3 groups:

• required dependencies -- these are listed in the main, non-optional section of the pyproject.toml. These are required everywhere the application will run and in development environments (for typing and linting).
• debug dependencies -- an optional group containing dependencies needed both inside and outside of the django container for testing and debugging.
• dev dependencies -- an optional group containing dependencies needed outside of the django container during development for code formatting and various development utilities (e.g. type checking).

To install dependencies in any optional group, run the above commands with a --with flag, and a comma-separated list of groups you would like to install. For example, to install dependencies in all three groups, run poetry install --with debug,dev.

Activating the virtual environment

To activate the virtual environment on the command line, run poetry shell from somewhere in the project repository. This will give you access to a shell in the CantusDB virtual environment. To deactivate the environment, run exit. You can also run a command in the environment without activating a shell by running poetry run [command to run].

The virtual environment can also be made accessible to VSCode so that any python in the VSCode project is run in the virtual environment. On a Mac, type Shift + Command + P to open the Editor Commands box. Search for and select "Python: Select Interpreter", and then select the poetry virtual environment associated with the project.

Adding or removing dependencies

To add, remove, or regroup dependencies, you can either use poetry add and poetry remove (and the --group flag to add or remove from specific groups) or you can directly edit the pyproject.toml file. Note that after you change the pyproject.toml file you will want to run poetry lock to update poetry.lock. Commit both the changed pyproject.toml file and the poetry.lock file to the repository. To update your virtual environment with these changes, run poetry install --sync, along with an --with flags for optional dependency groups (see "Installing Python Packages" above).