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 mtpoetry 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 Dateipoetry.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. Mitpoetry 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 Verzeichnisdist
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.