Verteilungspaket erstellen¶

Verteilungspakete (engl.: Distribution Packages sind Archive, die in einen Paket-Index wie z.B. pypi.org hochgeladen und mit pip installiert werden können.

Tipp

cusy Seminar: Fortgeschrittenes Python

Struktur¶

Ein minimales Distribution Package kann z.B. so aussehen:

dataprep
├── pyproject.toml
└── src
    └── dataprep
        ├── __init__.py
        └── loaders.py

`pyproject.toml`¶

PEP 517 und PEP 518 brachten erweiterbare Build-Backends, isolierte Builds und pyproject.toml im TOML-Format.

pyproject.toml teilt u.a. pip und build mit, welches Backend-Werkzeug verwendet werden soll, um Distributionspakete für euer Projekt zu erstellen. Ihr könnt aus einer Reihe von Backends wählen, wobei dieses Tutorial standardmäßig hatchling verwendet.

Eine minimale und dennoch funktionale dataprep/pyproject.toml-Datei sieht dann z.B. so aus:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

build-system

definiert einen Abschnitt, der das Build-System beschreibt

requires

definiert eine Liste von Abhängigkeiten, die installiert sein müssen, damit das Build-System funktioniert, in unserem Fall hatchling.

Bemerkung

Versionsnummern von Abhängigkeiten sollten üblicherweise jedoch nicht hier festgeschrieben werden sondern in der requirements.txt-Datei.

build-backend

identifiziert den Einstiegspunkt für das Build-Backend-Objekt als gepunkteten Pfad. Das hatchling-Backend-Objekt ist unter hatchling.build verfügbar.

Bemerkung

Für Python-Pakete, die binäre Erweiterungen mit Cython, C-, C++-, Fortran- oder Rust enthalten, ist das hatchling-Backend jedoch nicht geeignet. Hier sollte eines der folgenden Backends verwendet werden:

Doch damit nicht genug – es gibt noch weitere Backends:

Siehe auch

pypackaging-native

Bemerkung

With validate-pyproject you can check your pyproject.toml file.

Metadaten¶

In pyproject.toml könnt ihr auch Metadaten zu eurem Paket angeben, wie z.B.:

[project]
name = "dataprep"
version = "0.1.0"
authors = [
  { name="Veit Schiele", email="veit@cusy.io" },
]
description = "A small dataprep package"
readme = "README.rst"
requires-python = ">=3.7"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: BSD License",
    "Operating System :: OS Independent",
]
dependencies = [
    "pandas",
]

[project.urls]
"Homepage" = "https://github.com/veit/dataprep"
"Bug Tracker" = "https://github.com/veit/dataprep/issues"

name

ist der Distributionsname eures Pakets. Dies kann ein beliebiger Name sein, solange er nur Buchstaben, Zahlen, ., _ und - enthält. Er sollte auch nicht bereits auf dem Python Package Index (PyPI) vergeben sein.

version

ist die Version des Pakets.

In unserem Beispiel ist die Versionsnummer statisch gesetzt worden. Es gibt jedoch auch die Möglichkeit, die Version dynamisch anzugeben, z.B. durch eine Datei:

[project]
...
dynamic = ["version"]

[tool.hatch.version]
path = "src/dataprep/__about__.py"

Das Standardmuster sucht nach einer Variablen namens __version__ oder VERSION, die die Version enthält, optional mit dem vorangestellten Kleinbuchstaben v. Dabei basiert das Standardschema auf PEP 440.

Wenn dies nicht der Art entspricht, wie ihr Versionen speichern wollt, könnt ihr mit der Option pattern auch einen anderen regulären Ausdruck definieren.

Siehe auch

Es gibt jedoch noch weitere Versionsschema-Plugins, wie z.B. hatch-semver für Semantic Versioning.

Mit dem Version-Source-Plugin hatch-vcs könnt ihr auch Git-Tags verwenden:

[build-system]
requires = ["hatchling", "hatch-vcs"]
...
[tool.hatch.version]
source = "vcs"
raw-options = { local_scheme = "no-local-version" }

Auch das setuptools-Backend erlaubt dynamische Versionierung:

[build-system]
requires = ["setuptools>=61.0", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[project]
...
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "dataprep.VERSION"}

Tipp

Wenn die Version in mehreren Textdateien steht, kann sich die Verwendung von Bump My Version empfehlen.

Die Konfigurationsdatei .bumpversion.toml kann z.B. so aussehen:

[tool.bumpversion]
current_version = "0.1.0"
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
serialize = ["{major}.{minor}.{patch}"]
search = "{current_version}"
replace = "{new_version}"
regex = false
ignore_missing_version = false
tag = false
sign_tags = false
tag_name = "v{new_version}"
tag_message = "Bump version: {current_version} → {new_version}"
allow_dirty = false
commit = false
message = "Bump version: {current_version} → {new_version}"
commit_args = ""

[[tool.bumpversion.files]]
filename = "src/dataprep/__init__.py"

[[tool.bumpversion.files]]
filename = "docs/conf.py"

Siehe auch

Configuring setuptools using pyproject.toml files: Dynamic Metadata

authors

wird verwendet, um die Autoren des Pakets anhand ihrer Namen und E-Mail-Adressen zu identifizieren.

Ihr könnt auch maintainers im selben Format auflisten.

description

ist eine kurze Zusammenfassung des Pakets, die aus einem Satz besteht.

readme

ist ein Pfad zu einer Datei, die eine detaillierte Beschreibung des Pakets enthält. Diese wird auf der Paketdetailseite auf Python Package Index (PyPI) angezeigt. In diesem Fall wird die Beschreibung aus README.rst geladen.

requires-python

gibt die Versionen von Python an, die von eurem Projekt unterstützt werden. Dabei werden Installationsprogramme wie pip ältere Versionen von Paketen durchsuchen, bis sie eines finden, das eine passende Python-Version hat.

classifiers

gibt dem Python Package Index (PyPI) und pip einige zusätzliche Metadaten über euer Paket. In diesem Fall ist das Paket nur mit Python 3 kompatibel, steht unter der BSD-Lizenz und ist OS-unabhängig. Ihr solltet immer zumindest die Versionen von Python angeben, unter denen euer Paket läuft, unter welcher Lizenz euer Paket verfügbar ist und auf welchen Betriebssystemen euer Paket läuft. Eine vollständige Liste der Klassifizierer findet ihr unter https://pypi.org/classifiers/.

Außerdem haben sie eine nützliche Zusatzfunktion: Um zu verhindern, dass ein Paket zu PyPI hochgeladen wird, verwendet den speziellen Klassifizierer "Private :: Do Not Upload". PyPI wird immer Pakete ablehnen, deren Klassifizierer mit "Private ::" beginnt.

dependencies

gibt die Abhängigkeiten für euer Paket in einem Array an.

Siehe auch

PEP 631

urls

lässt euch eine beliebige Anzahl von zusätzlichen Links auflisten, die auf dem Python Package Index (PyPI) angezeigt werden. Im Allgemeinen könnte dies zum Quellcode, zur Dokumentation, zu Aufgabenverwaltungen usw. führen.

Siehe auch

Optionale Abhängigkeiten¶

project.optional-dependencies: erlaubt euch, optionale Abhängigkeiten für euer Paket anzugeben. Dabei könnt ihr auch zwischen verschiedenen Sets unterscheiden:

[project.optional-dependencies]
tests = [
    "coverage[toml]",
    "pytest>=6.0",
]
docs = [
    "furo",
    "sphinxext-opengraph",
    "sphinx-copybutton",
    "sphinx_inline_tabs"
]

Auch rekursive optionale Abhängigkeiten sind mit pip ≥ 21.2 möglich. So könnt ihr beispielsweise für dev neben pre-commit auch alle Abhängigkeiten aus docs und test übernehmen:

dev = [
    "dataprep[tests, docs]",
    "pre-commit"
]

Ihr könnt diese optionalen Abhängigkeiten installieren, z.B. mit:

Linux/macOS

$ cd /PATH/TO/YOUR/DISTRIBUTION_PACKAGE
$ python3 -m venv .venv
$ . .venv/bin/activate
$ python -m pip install --upgrade pip
$ python -m pip install -e '.[dev]'

Windows

> cd C:\PATH\TO\YOUR\DISTRIBUTION_PACKAGE
> python3 -m venv .venv
> .venv\Scripts\activate.bat
> python -m pip install --upgrade pip
> python -m pip install -e '.[dev]'

`src`-Package¶

Wenn ihr ein neues Paket erstellt, solltet ihr kein flaches sondern das src-Layout verwenden, das auch in Packaging Python Projects der PyPA empfohlen wird. Ein wesentlicher Vorteil dieses Layouts ist, dass Tests mit der installierten Version eures Pakets und nicht mit den Dateien in eurem Arbeitsverzeichnis ausgeführt werden.

Siehe auch

Hynek Schlawack: Testing & Packaging

Bemerkung

In Python ≥ 3.11 kann mit PYTHONSAFEPATH sichergestellt werden, dass die installierten Pakete zuerst verwendet werden.

dataprep

ist das Verzeichnis, das die Python-Dateien enthält. Der Name sollte mit dem Projektnamen übereinstimmen um die Konfiguration zu vereinfachen und für diejenigen, die das Paket installieren, besser erkennbar zu sein.

__init__.py

ist erforderlich, um das Verzeichnis als Paket zu importieren. Dies erlaubt euch folgende Importe:

import dataprep.loaders

oder

from dataprep import loaders

Obwohl __init__.py-Dateien oft leer sind, können sie auch Code enthalten.

Siehe auch

Packages

loaders.py

ist ein Beispiel für ein Modul innerhalb des Pakets, das die Logik (Funktionen, Klassen, Konstanten, etc.) eures Pakets enthalten könnte.

Andere Dateien¶

`CONTRIBUTORS.rst`¶

Siehe auch

All contributors

`LICENSE`¶

Ausführliche Informationen hierzu findet ihr im Abschnitt Lizenzieren.

`README.rst`¶

Diese Datei teilt denjenigen, die sich für das Paket interessieren, in kurzer Form mit, wie sie es nutzen können.

Siehe auch

Wenn ihr das Dokument in reStructuredText schreibt, könnt ihr die Inhalte auch als ausführliche Beschreibung in euer Paket übernehmen:

[project]
readme = "README.rst"

Zudem könnt ihr sie dann auch in eure Sphinx-Dokumentation mit .. include:: ../../README.rst übernehmen.

`CHANGELOG.rst`¶

Siehe auch

Historische oder für binäre Erweiterungen benötigte Dateien¶

Bevor die mit PEP 518 eingeführte pyproject.toml-Datei zum Standard wurde, benötigte setuptools setup.py, setup.cfg und MANIFEST.in. Heute werden die Dateien jedoch bestenfalls noch für binäre Erweiterungen benötigt.

Wenn ihr diese Dateien in euren Paketen ersetzen wollt, könnt ihr dies mit hatch new --init oder ini2toml.

`setup.py`¶

Eine minimale und dennoch funktionale dataprep/setup.py kann z.B. so aussehen:

from Cython.Build import cythonize
from setuptools import find_packages, setup

setup(
    ext_modules=cythonize("src/dataprep/cymean.pyx"),
)

package_dir verweist auf das Verzeichnis src, in dem sich ein oder mehrere Pakete befinden können. Anschließend könnt ihr mit setuptools’s find_packages() alle Pakete in diesem Verzeichnis finden.

Bemerkung

find_packages() ohne src/-Verzeichnis würde alle Verzeichnisse mit einer __init__.py-Datei paketieren, also auch tests/-Verzeichnisse.

`setup.cfg`¶

Diese Datei wird nicht mehr benötigt, zumindest nicht für die Paketierung. wheel sammelt heutzutage alle erforderlichen Lizenzdateien automatisch und setuptools kann mit dem options-Keyword-Argument universelle wheel-Pakete bauen, z.B. dataprep-0.1.0-py3-none-any.whl.

`MANIFEST.in`¶

Die Datei enthält alle Dateien und Verzeichnisse, die nicht bereits mit packages oder py_module erfasst werden. Sie kann z.B. so aussehen: dataprep/MANIFEST.in:

include LICENSE *.rst *.toml *.yml *.yaml *.ini
graft src
recursive-exclude __pycache__ *.py[cod]

Weitere Anweisungen in Manifest.in findet ihr in MANIFEST.in commands.

Bemerkung

Häufig wird die Aktualisierung der Manifest.in-Datei vergessen. Um dies zu vermeiden, könnt ihr check-manifest in einem Git pre-commit Hook verwenden.

Bemerkung

Wenn Dateien und Verzeichnisse aus MANIFEST.in auch installiert werden sollen, z.B. wenn es sich um laufzeitrelevante Daten handelt, könnt ihr dies mit include_package_data=True in eurem setup()-Aufruf angeben.

Paketstruktur erstellen¶

Mit uv init --package MYPACK lässt sich einfach eine initiale Dateistruktur für Pakete erstellen:

$ uv init --package mypack
$  tree mypack -a
mypack
├── .git
│   └── ...
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
└── src
    └── mypack
        └── __init__.py

mypack/pyproject.toml

Die Datei pyproject.toml enthält einen scripts-Einstiegspunkt mypack:main:

mypack/pyproject.toml¶

[project]
name = "mypack"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
    { name = "Veit Schiele", email = "veit@cusy.io" }
]
requires-python = ">=3.13"
dependencies = []

[project.scripts]
mypack = "mypack:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

mypack/src/mypack/__init__.py

Das Modul definiert eine CLI-Funktion main():

mypack/src/mypack/__init__.py¶

def main() -> None:
    print("Hello from mypack!")

Sie kann mit uv run aufgerufen werden:

$ uv run mypack
Hello from mypack!

Bemerkung

Ggf. erstellt uv run eine virtuelle Python-Umgebung im Ordner .venv bevor main() ausgeführt wird.

Build¶

Der nächste Schritt besteht darin, Distributionspakete für das Paket zu erstellen. Dies sind Archive, die in den Python Package Index (PyPI) hochgeladen und von pip installiert werden können.

Führt nun den Befehl in demselben Verzeichnis aus, in dem sich pyproject.toml befindet:

Linux/macOS

$ uv build
Building source distribution...
Building wheel from source distribution...
  Successfully built dist/mypack-0.1.0.tar.gz and dist/mypack-0.1.0-py3-none-any.whl

Windows

> uv build
Building source distribution...
Building wheel from source distribution...
  Successfully built dist/mypack-0.1.0.tar.gz and dist/mypack-0.1.0-py3-none-any.whl

dist/mypack-0.1.0-py3-none-any.whl

ist eine Build-Distribution. pip installiert bevorzugt Build-Distributionen und greift lediglich auf die Source-Distributionen zurück, wenn keine passende Build-Distribution vorhanden ist. Ihr solltet immer eine Source-Distribution hochladen und Build-Distributionen für die Plattformen bereitstellen, mit denen euer Projekt kompatibel ist. In diesem Fall ist unser Beispiel-Paket mit Python auf jeder Plattform kompatibel, so dass nur eine Build-Distribution benötigt wird:

mypack: ist der normalisierte Paketname
0.1.0: ist die Version des Distrubitionspakets
py3: gibt die Python-Version und ggf. die C-ABI an
none: gibt an, ob das Wheel-Paket für jedes oder nur spezifische OS geeignet ist
any: any eignet sich für jede Prozessorarchitektur, x86_64 hingegen nur für Chips mit dem x86-Befehlssatz und einer 64-Bit-Architektur

mypack-0.1.0.tar.gz

ist eine Source Distribution.

Siehe auch

Die Referenz für die Dateinamen findet ihr in PEP 427.

Weitere Infos zu Source-Distributionen erhaltet ihr in Core metadata specifications und PyPA specifications.

Testen¶

Anschließend könnt ihr die Wheel-Datei überprüfen mit:

$ uv add check-wheel-contents
Resolved 17 packages in 8ms
   Built mypack @ file:///Users/veit/sandbox/mypack
Prepared 1 package in 442ms
Uninstalled 1 package in 0.89ms
Installed 10 packages in 5ms
 + annotated-types==0.7.0
 + attrs==24.2.0
 + check-wheel-contents==0.6.0
 + click==8.1.7
 ~ mypack==0.1.0 (from file:///Users/veit/sandbox/mypack)
 + packaging==24.1
 + pydantic==2.9.2
 + pydantic-core==2.23.4
 + typing-extensions==4.12.2
 + wheel-filename==1.4.1
$ uv run check-wheel-contents dist/*.whl
dist/dataprep-0.1.0-py3-none-any.whl: OK

Alternativ könnt ihr das Paket auch in einem neuen Projekt installieren, z.B. in myapp:

$ uv init --app myapp
$ cd myapp
$ uv add ../mypack/dist/mypack-0.1.0-py3-none-any.whl
Resolved 8 packages in 130ms
Installed 1 package in 3ms
 + mypack==0.1.0 (from file:///Users/veit/sandbox/mypack/dist/mypack-0.1.0-py3-none-any.whl)

Anschließend könnt ihr mypack mit uv run aufrufen können:

$ uv run mypack
Hello from mypack!

Bemerkung

Es gibt immer noch viele Anleitungen, die einen Schritt zum Aufruf der setup.py enthalten, z.B. python setup.py sdist. Dies wird jedoch heutzutage von Teilen der Python Packaging Authority (PyPA) als Anti-Pattern angesehen.

Checks¶

Wenn ihr ein Paket für eine Aufgabenverwaltung erstellen wollt, das die Aufgaben in eine Datenbank schreibt und über ein Python-API und eine Befehlszeilenschnittstelle (CLI bereitstellt, wie würdet ihr die Dateien strukturieren?
Überlegt euch, wie ihr die oben genannten Aufgaben erledigen wollt. Welche Bibliotheken und Module fallen euch ein, die diese Aufgabe erfüllen könnten? Skizziert den Code für die Module der Python-API, der Befehlszeilenschnittstelle und der Datenbankanbindung.

Verteilungspaket erstellen¶

Struktur¶

pyproject.toml¶

Metadaten¶

Optionale Abhängigkeiten¶

src-Package¶

Andere Dateien¶

CONTRIBUTORS.rst¶

LICENSE¶

README.rst¶

CHANGELOG.rst¶

Historische oder für binäre Erweiterungen benötigte Dateien¶

setup.py¶

setup.cfg¶

MANIFEST.in¶

Paketstruktur erstellen¶

Build¶

Testen¶

Checks¶

`pyproject.toml`¶

`src`-Package¶

`CONTRIBUTORS.rst`¶

`LICENSE`¶

`README.rst`¶

`CHANGELOG.rst`¶

`setup.py`¶

`setup.cfg`¶

`MANIFEST.in`¶