Veröffentlichen eines Python-Pakets auf PyPI mit Poetry | Anleitung

# Ein Python-Paket auf PyPI veröffentlichen: Den Prozess mit Poetry automatisieren

Das Veröffentlichen Ihres eigenen Python-Pakets im PyPI-Repository ist ein wesentlicher Schritt für Entwickler, die ihren Code wiederverwenden möchten. Das Tool Poetry vereinfacht diesen Prozess erheblich, indem es Abhängigkeiten verwaltet und Artefakte erstellt. Diese Anleitung beschreibt detailliert die Projektvorbereitung, die Umgebungseinrichtung und die Paketveröffentlichung, einschließlich der Arbeit mit API-Token und optionalen Abhängigkeiten.

Konto einrichten und API-Token generieren

Der erste Schritt ist die Erstellung eines Kontos auf der offiziellen PyPI-Website. Nach der Registrierung generieren Sie ein API-Token für die Authentifizierung beim Veröffentlichen. Im Konto-Dashboard gehen Sie zum Abschnitt API-Tokens und klicken auf API-Token generieren. Geben Sie einen Namen für das Token an und wählen Sie seinen Gültigkeitsbereich aus. Für neue Projekte eignet sich ein kontobezogenes Token (Gesamtes Konto) gut, da Sie noch keine registrierten Pakete haben. Wichtig: Kopieren Sie das generierte Token direkt nach der Erstellung – es wird nicht erneut angezeigt.

Der Erstellungsprozess umfasst:

• Anmelden bei Ihrem PyPI-Konto
• Navigieren zum Abschnitt für die API-Token-Verwaltung
• Angeben des Token-Namens und Gültigkeitsbereichs
• Bestätigen der Erstellung und Sichern des Token-Werts

Poetry verwendet dieses Token für sicheres Veröffentlichen ohne Ihre Anmeldedaten. Lagern Sie es sicher wie ein Passwort.

Projekt mit Poetry initialisieren

Erstellen Sie das Projekt-Root-Verzeichnis und richten Sie eine virtuelle Umgebung ein:

python3 -m venv .venv
source .venv/bin/activate

Installieren Sie Poetry über pip und führen Sie die Initialisierung aus:

pip install poetry
poetry init

Im interaktiven Modus geben Sie die grundlegenden Parameter an: Paketname, Version, Beschreibung, Autor und unterstützte Python-Version. Die wichtigsten Felder in der generierten pyproject.toml-Datei:

• name — eindeutiger Paketname in PyPI (muss zum snake_case-Namen des Code-Verzeichnisses passen)
• version — semantische Version des Pakets
• python — Bereich der unterstützten Interpreter-Versionen
• readme — Pfad zur Beschreibungsdatei
• packages — Verweis auf das Quellcode-Verzeichnis

Nach der Initialisierung erstellen Sie ein Verzeichnis für den Code (konvertieren Sie den name, indem Sie Bindestriche durch Unterstriche ersetzen) und fügen die grundlegende Dateistruktur hinzu.

Projektstruktur und Konfiguration

Eine typische Projektstruktur sieht so aus:

my-package/
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.md
└── my_package/
    ├── __init__.py
    └── core.py

Es ist entscheidend wichtig, dass der Paketname in pyproject.toml exakt zum Namen des Code-Verzeichnisses passt. Zum Beispiel für name = "my-package" muss das Verzeichnis my_package heißen. In der __init__.py-Datei wird empfohlen, die Hauptfunktionen für eine einfache Nutzung zu importieren.

Beispielimplementierung in core.py:

PREPEND_STR = 'prepend_'

def modify_str(string: str) -> str:
    return f'{PREPEND_STR}{string}'

Stellen Sie sicher, dass Sie eine Lizenzdatei (vorzugsweise MIT) und eine README.md mit einer Beschreibung der Funktionalität hinzufügen. Sperren Sie die Abhängigkeiten mit poetry lock vor dem Veröffentlichen.

Paket bauen und veröffentlichen

Bauen Sie vor dem Hochladen ins Repository die Artefakte:

poetry build

Dieser Befehl erzeugt eine Quellverteilung (.tar.gz) und eine Wheel-Datei (.whl) im dist/-Verzeichnis. Konfigurieren Sie als Nächstes Poetry für die Verwendung des API-Tokens:

poetry config pypi-token.pypi pypi-XXXXXXXX

Ersetzen Sie pypi-XXXXXXXX durch Ihr Token. Nun veröffentlichen:

poetry publish

Bei Erfolg erhalten Sie eine Bestätigung des Uploads zu PyPI. Überprüfen Sie die Veröffentlichung durch Suchen auf der PyPI-Seite oder lokale Installation des Pakets:

pip install my-package

Arbeiten mit optionalen Abhängigkeiten

Um optionale Komponenten zu implementieren (installiert via pip install package[extra]), konfigurieren Sie pyproject.toml so:

[tool.poetry.dependencies]
python = "^3.10"
pydantic = {version=">=1.9", optional = true}

[tool.poetry.extras]
pydantic = ["pydantic"]

Hier ist die pydantic-Abhängigkeit als optional mit optional = true markiert, und der extras-Abschnitt erstellt eine pydantic-Gruppe, die diese Bibliothek enthält. Nutzer können die Extras mit pip install my-package[pydantic] installieren.

Wichtige Punkte

• Paketname in pyproject.toml strikt mit dem Code-Verzeichnisnamen abgleichen (Bindestriche → Unterstriche)
• Immer eine Lizenz und eine detaillierte README.md einfügen, um Nutzertrust aufzubauen
• API-Tokens statt Anmeldung/Passwort für sicheres Veröffentlichen verwenden
• Für optionale Abhängigkeiten die Abschnitte dependencies und extras korrekt konfigurieren
• Vor dem Veröffentlichen den Build mit poetry build prüfen

— Editorial Team