Migrate from the Charm plugin to the Poetry plugin

Many charms use Poetry to manage their Python projects. For these charms, Charmcraft has a Poetry plugin. Migrating from the Charm plugin provides some benefits, such as no longer having to maintain a requirements.txt file. If the charm to be migrated does not currently use poetry, refer to the Poetry documentation for instructions on how to use poetry for a Python project.

Update charmcraft.yaml

The first step is to update charmcraft.yaml to include the correct parts definition. Depending on the history of a specific charm, it may not have an explicitly-included parts section determining how to build the charm. In this case, a parts section can be created as follows:

parts:
  my-charm:  # This can be named anything you want
    plugin: poetry
    source: .

Select compatible versions of pip and poetry

The Poetry plugin requires at least pip 22.3, released in October 2022. If the charm’s base uses an older version of pip, a newer version can be installed in the build environment using a dependency part. Likewise, a charm may require a newer version of Poetry than is available in the distribution’s repositories. The following parts section can be used in place of the section above to upgrade pip and Poetry for charms that build on Ubuntu 22.04 or earlier:

parts:
  poetry-deps:
    plugin: nil
    build-packages:
      - curl
    override-build: |
      /usr/bin/python3 -m pip install pip==24.2
      curl -sSL https://install.python-poetry.org | python3 -
      ln -sf $HOME/.local/bin/poetry /usr/local/bin/poetry
  my-charm:  # This can be named anything you want
    after: [poetry-deps]
    plugin: poetry
    source: .

Add optional dependency groups

If the charm has dependency groups that should be included when creating the virtual environment, the poetry-with key can be used to include those groups when creating the virtual environment.

Note

This is useful and encouraged, though not mandatory, for keeping track of library dependencies, as covered in the next section. For an example, see postgresql-operator.

Include charm library dependencies

Unlike the Charm plugin, the Poetry plugin does not install the dependencies for included charmlibs. If any of the charm libraries used have PYDEPS, these will need to be added to the charm’s dependencies, potentially as their own dependency group.

To find these dependencies, check each library file for its PYDEPS. A command that can find these is:

find lib -name "*.py" -exec awk '/PYDEPS = \[/,/\]/' {} +

If run from the base directory of a charm, this will show all the PYDEPS declarations from all loaded charm libs.

Include extra files

A Poetry plugin only includes the contents of the src and lib directories as well as the generated virtual environment. If other files were previously included from the main directory, they can be included again using the Dump plugin:

parts:
  my-charm:  # This can be named anything you want
    plugin: poetry
    source: .
  version-file:
    plugin: dump
    source: .
    stage:
      - charm_version