Python-Pakete erstellen

von

Damit Python-Pakete erstellt werden können (z.B. um sie zu pypi.org hochzuladen), bedarf es einer oder mehrerer Konfigurationsdateien. Sie enthalten Informationen zu dem zu verwendenden Build-Backend und Metadaten zum Projekt. Wenn man sich mit diesem Thema beschäftigt, wird man dabei unter anderem auf folgende drei Dateien stoßen:

  • setup.py
  • setup.cfg
  • pyproject.toml

Diese drei Konfigurationsdateien werden in diesem Blogbeitrag erklärt.

Konfigurationsdateien eines Python-Projekts

In einem älteren Artikel zur Struktur eines Python-Projektes bin ich auf die Konfigurationsdateien setup.py und setup.cfg eingegangen. Die Datei setup.cfg enthält alle bezüglich des Projekts erforderlichen Metadaten, während die Datei setup.py, die früher für Metadaten verwendet wurde, sich dann auf zwei Zeilen reduziert. Dabei wird in folgendem Beispiel davon ausgegangen, dass setuptools für das Erstellen von Paketen verwendet werden soll:

import setuptools

setuptools.setup()

Die Datei setup.py ist aber mittlerweile als deprecated gekennzeichnet. Die Zukunft gehört der Konfigurationsdatei pyproject.toml. Sie enthält die Informationen zu dem zu verwendenden Build-Backend, wobei vier zur Verfügung stehen:

  • Hatchling,
  • setuptools,
  • Flit und
  • PDM.

Sofern setuptools für das Erstellen von Python-Paketen verwendet werden soll, muss die Datei pyproject.toml folgende Angaben enthalten:

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

Die Datei setup.py ist dann nicht mehr erforderlich. Für die Metadaten könnte jedoch weiterhin die Datei setup.cfg verwendet werden. Nachfolgendes Beispiel zeigt, wie die Datei setup.cfg aufgebaut ist:

[metadata]
name = my_project
author = 
author-email = 
license =
long_description = file: README.md
url = https://
requires-python = >= 3.12
classifiers =
    License :: OSI Approved :: MIT License
    Operating System :: OS Independent
    Programming Language :: Python :: 3
    Programming Language :: Python :: 3.12
    Programming Language :: Python :: 3.13
    Programming Language :: Python :: Implementation :: CPython

Es ist aber auch möglich, stattdessen die Metadaten in die Datei pyproject.toml aufzunehmen:

[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
  { name="Example Author", email="author@example.com" },
]
description = "A small example package"
readme = "README.md"
requires-python = ">=3.12"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

In diesem Fall kann setup.cfg weggelassen werden. Das Python-Projekt hat dann nur noch eine Konfigurationsdatei: pyproject.toml.

Verteilungspakete erstellen

Sofern alle Voraussetzungen erfüllt sind (pyproject.toml, README.md, Lizenz-Info, etc.), kann ein Verteilungspaket (distribution package) erstellt werden. Dabei handelt es sich um ein Archiv, das zu einem Paket-Index (z.B. pypi.org) hochgeladen und mit pip installiert werden kann.

Voraussetzung ist, dass auf dem System build installiert ist (und setuptools, falls es als Build-Backend verwendet werden soll).

# Linux/macOS
python3 -m pip install --upgrade build

# Windows
py -m pip install --upgrade build

Der Build-Prozess kann dann mit folgender Anweisung gestartet werden:

# Linux/macOS
python3 -m build

# Windows
py -m build

Dies erstellt das Verzeichnis dist, in dem sich die Source-Datei (Endung tar.gz) und die Build-Datei (Endung whl) befindet. Das Programm pip greift für die Installation eines Pakets grundsätzlich auf die whl-Datei zu. Die Source-Datei wird als Fallback verwendet.

Fazit

  • Ein Python-Projekt kann zwei Konfigurationsdateien enthalten: pyproject.toml und setup.cfg.
  • Die Datei setup.py ist heutzutage nicht mehr erforderlich.
  • Sofern alle Informationen (Build-Backend und Metadaten) in eine Datei, also pyproject.toml, aufgenommen werden, kann die Datei setup.cfg wegfallen.
  • Das Bauen der Verteilungspakete erfolgt mit build.
  • Als Ergebnis erhält man einen dist-Ordner mit zwei Dateien (tar.gz. und whl).

Weiterführende Links