Schnipsel aus dem Zettelkasten


Poetry

Python-Projekte mit Poetry verwalten

Inhalt
  • Poetry ist ein Paket- und Abhängigkeitsmanager für Python-Projekte. Er nutzt automatisch virtualenvs und bietet eine integrierte Testfunktionalität. Poetry will das klassische setup.py ersetzen.
  • Die Installation erfolgt mittels pip: pip install poetry oder über die Paketverwaltung des Betriebssystems.

Ein neues Projekt anlegen

  • Mit poetry new <project> legt Poetry einen Unterordner mit diversen Dateien und Verzeichnissen an:
    <project>
    ├── pyproject.toml
    ├── README.rst
    ├── <project>
    │   └── __init__.py
    └── tests
        ├── __init__.py
        └── test_<project>.py
  • Die Verwendung eines Versionskontrollsystems wie Git oder Mercurial gehört zum guten Ton und eine Initialisierung eines Repositories, bspw. mit hg init <project> bietet sich an dieser Stelle an.
  • Die Datei .toml beschreibt das Projekt und seine Abhängigkeiten genauer:
    [tool.poetry]
    name = "<project>"
    version = "0.1.0"
    description = "Ein tolles Projekt."
    authors = ["John Doe <john.doe@example.com"]

    [tool.poetry.dependencies]
    python = "^3.9"
    click = "^7.1.2"

    [tool.poetry.dev-dependencies]
    pytest = "^5.2"

    [build-system]
    requires = ["poetry-core>=1.0.0"]
    build-backend = "poetry.core.masonry.api"
  • Pakete wie hier click, die das neue Projekt nutzen soll, werden unter [tool.poetry.dependencies] samt ihrer Version aufgeführt. Derartige Abhängigkeiten lassen sich komfortabel mt poetry add click hinzufügen.
  • Eine Versionsangabe besteht aus Major- und Minor-Version, auch ein Patchlevel ist möglich. Die aufgeführten Versionen werden immer dann aktualisiert, wenn die Major-Version (bei click ist das hier 7) nicht verändert wird. Ist diese allerdings 0, dann darf ein Update auf dieselbe Weise nicht die Minor-Version verändern. Weitere Details zur Versionierung finden sich unter https://python-poetry.org/docs/dependency-specification/.
  • Soll ein schon existierendes Projekt in den Genuss der Verwaltung mit Poetry kommen, können mit poetry init <old_project> nachträglich die erforderlichen Dateien ergänzt werden.

Abhängigkeiten installieren und aktualisieren

  • Der Befehl poetry install installiert beim ersten Aufruf alle in <project>.toml aufgeführten Abhängigkeiten und fixiert sie mit ihrer jeweiligen Version in der Datei poetry.lock. Diese Datei sollte auch versioniert werden, denn sie sorgt in Zukunft dafür, dass das Projekt immer mit den passenden Versionen arbeitet.
  • Sollen die Abhängigkeiten aktualisiert werden, erledigt das poetry update.
  • poetry show listet alle Abhängigkeiten samt Version auf. Die Option --latest prüft online, ob neuere Versionen verfügbar sind.

Projekt-Tests ausführen

  • Poetry richtet vor dem Ausführen der Tests eine eine virtualenv-Umgebung inklusive der Abhängigkeiten in den passenden Versionen ein. Darin werden dann die Tests mit poetry run pytest gestartet. Mit poetry env info lassen sich Informationen über das genutzte Betriebssystem und die Python-Version ausgeben.
  • Manuelles Testen oder einfaches Ausprobieren in der virtualenv-Umgebung ist mit poetry shell möglich.
  • poetry env list listet die von Poetry genutzten virtualenv-Umgebungen auf, poetry env info gibt zusätzliche Details aus.

Distribution bauen

  • Sind alle Tests erfolgreich durchgelaufen, ist es Zeit, das Projekt zu veröffentlichen. Mit poetry build erstellt Poetry im Verzeichnis dist ein Quell-Archiv <project>-<version>.tar.gz sowie eine Wheel-Datei <project>-<version>-py3-none-any.whl (je nach Setup kann die Wheel-Datei auch anders aussehen).
  • Diese Dateien können nun auf der eigenen Website oder direkt mit Poetry auf GitHub oder PyPi veröffentlicht werden (siehe poetry publish). Auch private Repositories sind möglich; mehr dazu findet sich unter https://python-poetry.org/docs/repositories/.

Fazit

  • Im Vergleich zur herkömmlichen Einrichtung von Projekten mittels setup.py bietet Poetry mehr Funktionalität und Komfort. Insbesondere die einfache Einrichtung der Abhängigkeiten auch für Tests machen die Entwicklung sehr angenehm.