Pythons pyproject.toml: Ein Überblick

Die gemeinsame Nutzung von Code und die Zusammenarbeit bei Open-Source-Software hat die Softwareentwicklung grundlegend verändert. Sie hat es Entwicklern ermöglicht, mit kleineren Teams kompliziertere Anwendungen unter Verwendung vorhandener Pakete und Bibliotheken zu erstellen.

Im Python-Ökosystem sind die meisten Pakete im Python Package Index (PyPI) registriert. Über den Index können Entwickler ihren Code als Pakete für andere Entwickler freigeben. Um Ihr eigenes Paket zu erstellen und es in PyPI hochzuladen, benötigen Sie eine pyproject.toml Datei. Dieser Artikel ist eine Anleitung, wie das funktioniert.

Was ist pyproject.toml?

Bevor wir uns damit befassen, was diese Datei ist, sollten wir zunächst die Lücke verstehen, die sie zu füllen versucht. Wenn Sie ein Paket auf PyPI hochladen, wird es mit pip installierbar. Wenn Ihr Paket nach dem Hochladen zu PyPI beispielsweise example-package heißt, kann es mit dem folgenden Befehl installiert werden:

pip install example-package

Wenn Sie Pakete im Python Package Index veröffentlichen, laden Sie eine .whl-Datei hoch. Aber wenn Sie Code schreiben, schreiben Sie meistens .py-Dateien. Wie erzeugen Sie also eine .whl-Datei? Sie verwenden ein Build-Tool wie setuptools oder poetry.

Dieses Tool wandelt Ihren Quellcode in eine .whl-Datei um, die Sie hochladen können. Wie bereits erwähnt, gibt es mehrere Tools, die Sie zur Erstellung einer Whl-Datei verwenden können. Um anzugeben, welches Tool Python verwenden soll, schreiben Sie es in die Datei pyproject.toml.

Die Datei pyproject.toml ist also eine Datei, die angibt, wie Ihr Python-Projekt in ein Paket eingebaut werden soll. Darüber hinaus können Sie zusätzliche Informationen angeben, wie z.B. die Metadaten Ihres Pakets, die dann in der Auflistung Ihres Pakets bei PyPI angezeigt werden.

Der Python-Erstellungsprozess

Um das Tool für den Build-Prozess zu starten, verwenden Sie den Befehl,

python -m build

Aber bevor Sie das tun können, müssen Sie es installieren

python -m pip install build

Wenn Sie den Build-Befehl in einem Projekt ausführen, das eine pyproject.toml-Datei enthält, werden neue Dateien und Verzeichnisse angelegt. Dazu gehört der Ordner dist, der zwei Dateien enthält, eine komprimierte Archivdatei namens sdist und eine .whl-Datei, die Sie dann über PyPI verteilen.

Wie generiert man ein Python-Paket?

Damit Sie das soeben Gelernte besser verinnerlichen können, finden Sie hier ein Beispiel für die Erstellung eines Python-Pakets.

#1. Erstellen Sie ein Beispielprojekt

Erstellen Sie zunächst ein einfaches Paket mit der folgenden Ordnerstruktur

example_package/
├─ example_package/
│ ├─ example_module.py
│ ├─ __init__.py
├─ pyproject.toml
├─ setup.cfg
├─ README.md

Das Stammverzeichnis des Projekts heißt example_package. Darin befindet sich unsere gesamte Codebasis. Im Stammverzeichnis des Projekts befinden sich drei Dateien und ein Verzeichnis. Ihr Inhalt wird im Folgenden erklärt:

pyproject.toml

Diese Datei enthält Informationen darüber, welche Build-Tools bei der Erstellung Ihres Projekts verwendet werden sollen. Für dieses einfache Beispiel sind dies die Inhalte:

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

In diesem Fall deklarieren wir setuptools.build_meta als unser Build-Backend. Da setuptools.build_meta jedoch im Paket setuptools enthalten ist, führen wir es zunächst als Anforderung in unserer Liste der Anforderungen auf. Weitere Optionen, die Sie angeben können, werden wir später in diesem Artikel besprechen.

README.md

Enthält Informationen über Ihr Paket. Diese Datei wird als Dokumentation auf der Seite Ihres Pakets auf PyPI angezeigt. Sie können alles in diese Datei schreiben.

setup.cfg

Die Datei setup.cfg enthält Projekt-Metadaten, wie den Namen des Pakets und die aktuelle Version. Fügen Sie zunächst den folgenden Code als Inhalt von setup.cfg hinzu:

<x>[metadata]</x>
name = example-package
version = 1.0.0

beispiel-projekt

In unserem Stammverzeichnis befindet sich ein weiteres Verzeichnis mit demselben Namen. In diesem Verzeichnis befindet sich unser Quellcode. Zu Demonstrationszwecken habe ich zwei Dateien hinzugefügt:

• example_module.py – Diese Datei enthält eine Dummy-Funktion. Sie können das Gleiche auch tun.
• __init__.py – Damit wird das Verzeichnis zu einem Paket, das importiert werden kann. Es kann leer sein.

#2. Führen Sie den Build-Befehl aus

Jetzt können Sie den Build-Befehl im Stammverzeichnis des Projekts ausführen.

python -m build

Wenn Sie das noch nicht getan haben, installieren Sie das Tool wie folgt:

pip install build

Sie sollten eine Ausgabe erhalten, die wie folgt aussieht:

Wie Sie sehen können, sagt Ihnen die letzte Zeile, dass example-package-1.0.0.tar.gz und example-package-1.0.0-py3-none-any-whl gebaut wurden. Wenn Sie den Inhalt Ihres Verzeichnisses mit dem Befehl ls unten auflisten, sollten Sie neue Dateien sehen.

ls

Die Ausgabe sollte wie folgt aussehen:

dist example_package example_package.egg-info pyproject.toml README.md setup.cfg

Wenn Sie den Inhalt Ihres dist-Verzeichnisses auflisten, sollten Sie die .whl-Datei und die tar.gz-Datei finden.

$ ls dist
example_package-1.0.0-py3-none-any.whl
example-package-1.0.0.tar.gz

Inhalt der Datei pyproject.toml

In unserem einfachen Beispiel haben wir nur das Build-System unseres Python-Projekts angegeben. Sie können Ihrer pyproject.toml Datei jedoch weitere Informationen hinzufügen. Dies sind einige der üblichen Optionen.

metadaten

Anstatt die Metadaten in der setup.cfg anzugeben, können Sie sie in Ihre pyproject.toml schreiben. Diese Informationen werden bei der Erstellung eines Eintrags für Ihr Paket im Paketindex verwendet.

Darüber hinaus können Sie die Abhängigkeiten Ihres Pakets und deren Versionen angeben, damit diese bei der Installation Ihres Pakets installiert werden können.

[Projekt]
name = "hello-world"
version = "1.0.0"
description = "Mein erstes Python-Paket"
requires-python = ">=3.8"
keywords = ["python", "first-project"]
authors = [
 {name = "John Doe", email = "john@example.com"},
]
dependencies = [
 "requests",
 "gidgethub[httpx]>4.0.0",
]

tool.<tool_name&gt

Sie können auch tool.<tool_name> verwenden, wobei <tool_name> der Name des Tools ist, um verschiedene Konfigurationsoptionen für die von Ihnen verwendeten Tools bereitzustellen.

Dies ist nur bei Tools möglich, die die Konfiguration mit dieser Methode unterstützen. So können Sie zum Beispiel Konfigurationsoptionen an Black, einen Code-Linter, übergeben.

[tool.black]
line-length = 88
target-version = ["py38", "py39"]

Beispiel-Datei

Um das Gelernte zusammenzufassen, hier ein Beispiel für eine pyproject.toml-Datei:

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

<x>[metadata]</x>
name = "my-project"
version = "1.0.0"
description = "Ein Beispielprojekt"
author = "Ihr Name"
author_email = "your.email@example.com"
license = "MIT"
keywords = ["sample", "project"]

[options]
python_requires = ">=3.6"

[tool.black]
line-length = 88
include = "\\.pyi?$"
exclude = '''
/(
 \.git
 | \.hg
 | \.mypy_cache
 | \.tox
 | \.venv
 | _build
 | buck-out
 | build
 | dist
)/
'''

[tool.blackd]
port = 45484
host = "localhost"

Für weitere Informationen lesen Sie bitte diese Seite.

Vorteile von pyproject.toml

✅ Es bietet eine Standardmethode zur Verwaltung von Abhängigkeiten für Python-Projekte. Die Abhängigkeiten
und andere relevante Metadaten von Projekten können auf deklarative Weise angegeben werden.

✅ Es bietet auch eine Möglichkeit, andere Metadaten in Ihren Projekten anzugeben, wie z.B. die Autoren, die Lizenz und die GitHub-URL, neben anderen hilfreichen Attributen.

✅ Es passt zu verschiedenen Build-Systemen und der Wechsel zwischen Build-Systemen ist einfach.

Letzte Worte

pyproject.toml ist ein nützlicher Standard, der hilft, die Nachteile der Verwendung von setup.py zu vermeiden. Er ist besonders nützlich, wenn Sie Pakete für die Verteilung erstellen. Für die meisten neuen Projekte sollten Sie pyproject.toml anstelle von setup.py verwenden.

Als nächstes erfahren Sie, wie Sie die Python-Version in Windows, Linux und macOS überprüfen können.