Zusammenfassung

Das Modul distutils [1] empfiehlt seit langem die Verwendung des Pakets setuptools [2]. Setuptools hat kürzlich eine vollständige Kopie von distutils integriert und ist nicht mehr von der Standardbibliothek abhängig [3]. Pip ersetzt bereits seit langem heimlich distutils durch setuptools bei der Installation von Paketen, und die Dokumentation von distutils besagt seit 2014 (oder früher), dass es ausgemustert wird. Es ist an der Zeit, es aus der Standardbibliothek zu entfernen.

Motivation

distutils [1] ist eine weitgehend undokumentierte und unverwaltete Sammlung von Dienstprogrammen zur Paketierung und Verteilung von Python-Paketen, einschließlich der Kompilierung nativer Erweiterungsmodule. Es definiert ein Konfigurationsformat, das eine Python-Distribution beschreibt, und stellt die Werkzeuge zur Verfügung, um ein Verzeichnis mit Quellcode in eine Quellcode-Distribution und einige Formen einer Binärdistribution umzuwandeln. Aufgrund seines Platzes in der Standardbibliothek können viele Updates nur mit einer Hauptversion veröffentlicht werden, und Benutzer können sich nicht auf die Verfügbarkeit bestimmter Korrekturen verlassen.

setuptools [2] ist eine besser dokumentierte und gut gepflegte Erweiterung, die auf distutils basiert. Obwohl es eine sehr ähnliche Funktionalität bietet, unterstützt es Benutzer auf früheren Python-Versionen wesentlich besser und kann auf Fehlerberichte schneller reagieren. Eine Reihe von plattformspezifischen Erweiterungen existieren bereits in setuptools, die nicht in distutils aufgenommen wurden, und in der Dokumentation von distutils wird seit langem empfohlen, setuptools zu bevorzugen.

Historisch gesehen hat setuptools distutils durch Unterklassenbildung und Monkeypatching erweitert, hat aber inzwischen eine Kopie des zugrundeliegenden Codes übernommen. [3] Infolgedessen entfällt die vorletzte große Abhängigkeit von distutils, und es besteht keine Notwendigkeit, es in der Standardbibliothek zu behalten.

Die letzte Abhängigkeit von distutils ist CPython selbst, das es zum Erstellen nativer Erweiterungsmodule in der Standardbibliothek verwendet (außer unter Windows). Da es sich um eine Build-Zeitabhängigkeit von CPython handelt, ist es möglich, distutils für diesen speziellen Fall weiterhin zu verwenden, ohne dass es Teil der Standardbibliothek ist.

Die Kennzeichnung als veraltet und die Entfernung machen deutlich, dass Probleme im setuptools-Projekt behoben werden sollten, und reduzieren eine Quelle für Fehlerberichte und unnötige Testwartung. Es wird auch die Entwicklung von alternativen Build-Backends fördern, die dank PEP 517 jetzt einfacher unterstützt werden können.

Spezifikation

In Python 3.10 und 3.11 wird distutils formell als veraltet gekennzeichnet. Alle bekannten Probleme werden zu diesem Zeitpunkt geschlossen. import distutils löst eine Deprecation Warning aus. Neue Probleme, die als Release-blockierend gelten, können weiterhin behoben werden, aber die Unterstützung für neue Werkzeuge oder Plattformen wird nicht hinzugefügt.

Während Python 3.10 und 3.11 können Verwendungen von distutils innerhalb der Standardbibliothek geändert werden, um alternative APIs zu verwenden.

In Python 3.12 wird distutils nicht mehr durch make install oder eine der First-Party-Distributionen installiert. Drittanbieter sollten distutils nicht mehr in ihren Bundles oder Repositories aufnehmen.

Dieses PEP macht keine Vorgaben zur Migration der Teile des CPython-Build-Prozesses, die derzeit distutils verwenden. Abhängig von Beiträgen kann diese Migration jederzeit erfolgen.

Nachdem die Entwicklung von Python 3.12 gestartet ist und der CPython-Build-Prozess nicht mehr auf die Standardbibliothek-Kopie von distutils angewiesen ist, wird das gesamte Verzeichnis Lib/distutils und die Datei Lib/test/test_distutils.py aus dem Repository entfernt.

Andere Verweise auf distutils werden bereinigt. Ab der Erstveröffentlichung von Python 3.9 haben die folgenden Module Referenzen im Code oder in Kommentaren

• Lib/ctypes/util.py
• Lib/site.py
• Lib/sysconfig.py
• Lib/_aix_support.py
• Lib/_bootsubprocess.py
• Lib/_osx_support.py
• Modules/_decimal/tests/formathelper.py

Die folgenden Tools in CPython verweisen ebenfalls auf distutils. Beachten Sie, dass keines dieser Tools mit CPython installiert wird

• PC/layout (Referenzen werden entfernt)
• Tools/msi (Referenzen werden entfernt)
• Tools/peg_generator (wird an ein anderes Build-Tool angepasst)
• Tools/test2to3 (Beispielprojekt wird entfernt)

Da der distutils-Code bereits in setuptools enthalten ist, ist es nicht notwendig, ihn in irgendeiner anderen Form erneut zu veröffentlichen. Wer Zugriff auf die Funktionalität benötigt, sollte setuptools oder ein alternatives Build-Backend verwenden.

Abwärtskompatibilität

Code, der distutils importiert, funktioniert ab Python 3.12 nicht mehr.

Der vorgeschlagene Migrationspfad besteht darin, die entsprechenden (wenn auch nicht identischen) Importe aus setuptools zu verwenden (siehe [5]) oder zu einem alternativen Build-Backend zu migrieren (siehe PEP 517).

Es existiert bereits Code in setuptools, um setup.py-Dateien, die distutils verwenden, transparent auf ihre Äquivalente umzustellen. Daher ist bekannt, dass die meisten funktionierenden Build-Skripte mit setuptools funktionieren. Solche Skripte müssen möglicherweise ihre Importanweisungen aktualisieren. Spezifische Migrationshinweise finden Sie in der Dokumentation von setuptools. [5]

Einige Projekte verwenden alternative Patch-Sets über distutils, insbesondere numpy.distutils. [6] Projekte, von denen wir wissen, dass sie dies tun, wurden informiert.

Viele Build-Skripte verwenden benutzerdefinierte Befehle oder eng umrissene Patches. Da diese Pakete bereits davon betroffen sind, dass setuptools distutils überschreibt, erwarten wir minimale Störungen durch die Entfernung von distutils. Skripte müssen möglicherweise weiterhin aktualisiert werden, um den Import von distutils zu vermeiden.

Referenzimplementierung

Setuptools Version 48 enthält die vollständige Kopie von distutils und ist daher nicht mehr von der Kopie der Standardbibliothek abhängig. Die meisten Implementierungsprobleme, mit denen sie konfrontiert waren, sind auf die fortgesetzte Existenz von distutils in der Standardbibliothek zurückzuführen, und die Entfernung wird die Stabilität ihrer Implementierung verbessern.

Es gibt noch keine Referenzimplementierung für die Entfernung von distutils aus der Standardbibliothek, noch gibt es eine Implementierung für die nativen Modul-Builds von CPython, ohne auf die Standardbibliothek-Kopie von distutils angewiesen zu sein.

Migrationshinweise

Für diese Module oder Typen ist setuptools die beste Ersetzung

• distutils.ccompiler
• distutils.cmd.Command
• distutils.command
• distutils.config
• distutils.core.Distribution
• distutils.errors

Für diese Module oder Typen verwenden Sie die standarddefinierten Pakete der Python Packaging Authority

• distutils.version — verwenden Sie das Paket packaging

Für diese Module oder Funktionen verwenden Sie das angezeigte Modul der Standardbibliothek

• distutils.fancy_getopt — verwenden Sie das Modul argparse
• distutils.spawn.find_executable — verwenden Sie die Funktion shutil.which
• distutils.spawn.spawn — verwenden Sie die Funktion subprocess.run
• distutils.sysconfig — verwenden Sie das Modul sysconfig
• distutils.util.get_platform — verwenden Sie das Modul platform

Für diese Funktionen und alle anderen, die hier nicht erwähnt werden, müssen Sie die Funktionalität selbst neu implementieren. Die Legacy-Dokumentation finden Sie unter https://docs.pythonlang.de/3.9/distutils/apiref.html

• distutils.dir_util.create_tree
• distutils.util.change_root
• distutils.util.strtobool

Abgelehnte Ideen

Referenzen

Urheberrecht

Dieses Dokument wird in die Public Domain oder unter die CC0-1.0-Universal-Lizenz gestellt, je nachdem, welche Lizenz permissiver ist.