Setting Up PDM

PDM allows us to manage installed packages across versions to ensure when we run our scripts we run them with the correct package and the correct version. To initalize pdm follow the steps below.

Installation

PDM should be installed as described in the Installation instructions.

Initialization

If the project has existing pyproject.toml and pdm.lock files, simply run

pdm sync

and a virtual environment will be created. Dependencies will be automatically installed into the .venv/ directory.

Otherwise, the project should be initialized by running

pdm init

This will ask a series of questions, where the defaults are usually safe, and produce a file called pyproject.toml.

IMPORTANT: When selecting the python interpreter, select the installation location rather than a virtual environment path. On the CAML cluster this will look something like /opt/anaconda3/bin/python

IMPORTANT: Ensure PDM sets up a virtual environment for packages to be installed in. This will be the .venv/ directory.

If properly initialized the following files will appear in the project root directory:

  1. pyproject.toml - contains project metadata and dependencies
  2. pdm.lock - contains the resolved result for dependencies and subdependencies
  3. .pdm.toml - contains the python interpreter path and package installation location
  4. .venv/ - contains installed packaged libraries and interpreter

pyproject.toml

Add the name, version, and description fields to the pyproject.toml file. This will ensure the documentation is build correctly.

.gitignore

To prevent conflicts when using git versioning, add the .pdm.toml file and .venv/ directory to your project’s .gitignore

Adding Packages

Packages can be added in the same fasion as pip and conda by running:

pdm add <package_name>

Running Packages

Installed packages can be run br prepending pdm run as follows:

pdm run <command_name>

Jupyter Lab Kernel

When developing in Jupyter Lab, the kernel should point to the PDM environment so installed packages are recognized. This is done as follows:

python -m ipykernel install --user --name=<virtual_env_name>

Where virtual_env_name is the name of the firtual environment pdm points to.

If PDM automatically generated a virtual environment (recommended) the name will be {project_name}-{python version}.

For example, the venv name for this project is frameworks-getting-started-3.9.

This can always be checked by running from the project root:

cat .pdm.toml

To check the project python interpreter. Or by running from the project root:

source .venv/bin/activate

To view the name of the virtual environment activated.

Pulling From Github

When pulling from Github it is crucial to ensure local package versions are up to date. To do this run:

pdm sync

This will update pdm.lock from pyproject.toml and install packages as needed.