Poetry plugin¶

The Poetry plugin can be used for Python projects that use the Poetry build system.

Keys¶

This plugin provides the following unique keys.

poetry-export-extra-args:¶

Type: list of strings

Extra arguments to pass at the end of the poetry export command.

poetry-pip-extra-args:¶

Type: list of strings

Extra arguments to pass to pip install when installing dependencies.

poetry-with:¶

Type: list of strings

Dependency groups to include. By default, only the main dependencies are included.

Environment variables¶

This plugin also sets environment variables in the build environment. User-set environment variables will override these values. Users may also set environment variables to configure Poetry using the build-environment key.

PARTS_PYTHON_INTERPRETER¶

Default value: python3

Either the interpreter binary to search for in PATH or an absolute path to the interpreter (e.g. ${CRAFT_STAGE}/bin/python).

PARTS_PYTHON_VENV_ARGS¶

Default value: (empty string)

Additional arguments passed to python -m venv.

Dependencies¶

Since none of the bases that are available for rocks contain a default Python installation, including a Python interpreter in Rockcraft projects is mandatory. Both the python and the poetry plugins also require the venv module to create the virtual environment where Python packages are installed at build time.

The easiest way to do this is to include the python3-venv package in the stage-packages of the part that uses the Python-based plugin. This will pull in the default Python interpreter for the build-base, like Python 3.10 for Ubuntu 22.04. However, other versions can be used by explicitly declaring them - here’s an example that uses python3.12-venv from the Deadsnakes ppa:

rockcraft.yaml¶

 package-repositories:
   - type: apt
     ppa: deadsnakes/ppa
     priority: always

 parts:
   my-part:
     plugin: <python or poetry>
     source: .
     stage-packages: [python3.12-venv]

How it works¶

During the build step, the plugin performs the following actions:

It creates a virtual environment directly into the ${CRAFT_PART_INSTALL} directory.
It uses poetry export to create a requirements.txt file in the project’s build directory.
It uses pip to install the packages referenced in requirements.txt into the virtual environment, without any additional dependencies.
It uses pip to install the source package without any additional dependencies.
It runs pip check to ensure the virtual environment is consistent.