Zusammenfassung

Während distutils / setuptools uns weit gebracht haben, leiden sie unter drei ernsten Problemen: (a) ihnen fehlen wichtige Funktionen wie nutzbare Deklaration von Build-Abhängigkeiten, Autokonfiguration und sogar grundlegende ergonomische Annehmlichkeiten wie DRY-konformes Versionsnummernmanagement, und (b) ihre Erweiterung ist schwierig, sodass, obwohl es verschiedene Lösungen für die oben genannten Probleme gibt, diese oft eigenartig, zerbrechlich und teuer im Unterhalt sind, und dennoch (c) ist es sehr schwierig, etwas anderes zu verwenden, da distutils/setuptools die Standard-Schnittstelle für die Installation von Paketen bereitstellen, die sowohl von Benutzern als auch von Installationstools wie pip erwartet wird.

Frühere Bemühungen (z. B. distutils2 oder setuptools selbst) haben versucht, Probleme (a) und/oder (b) zu lösen. Dieser Vorschlag zielt darauf ab, (c) zu lösen.

Das Ziel dieses PEP ist es, distutils-sig aus dem Geschäft der Gatekeeper für Python-Build-Systeme herauszuholen. Wenn Sie distutils verwenden möchten, großartig; wenn Sie etwas anderes verwenden möchten, sollte das auf standardisierten Wegen einfach möglich sein. Die Schwierigkeit der Interaktion mit distutils bedeutet, dass es derzeit nicht viele solche Systeme gibt, aber um eine Vorstellung davon zu geben, was wir uns vorstellen, siehe flit oder bento. Glücklicherweise haben Wheels viele der harten Probleme hier gelöst – z. B. ist es nicht mehr notwendig, dass ein Build-System auch über jede mögliche Installationskonfiguration Bescheid weiß – sodass praktisch alles, was wir wirklich von einem Build-System brauchen, darin besteht, dass es eine Möglichkeit gibt, Standard-konforme Wheels und sdists auszugeben.

Wir schlagen daher eine neue, relativ minimale Schnittstelle für Installationstools wie pip vor, um mit Paketquellcode-Verzeichnissen und Source-Distributionen zu interagieren.

Terminologie und Ziele

Ein Quellcode-Verzeichnis ist so etwas wie ein VCS-Checkout. Wir benötigen eine Standard-Schnittstelle für die Installation aus diesem Format, um Verwendungszwecke wie pip install some-directory/ zu unterstützen.

Eine Source-Distribution ist ein statischer Schnappschuss, der eine bestimmte Version eines Quellcodes darstellt, wie z. B. lxml-3.4.4.tar.gz. Source-Distributionen dienen vielen Zwecken: Sie bilden einen archivierten Nachweis von Releases, sie bieten einen extrem einfachen De-facto-Standard für Tools, die große Codekorpora aufnehmen und verarbeiten wollen, möglicherweise in vielen Sprachen geschrieben (z. B. Code-Suche), sie fungieren als Eingabe für nachgelagerte Verpackungssysteme wie Debian/Fedora/Conda/..., und so weiter. Im Python-Ökosystem spielen sie zusätzlich eine besonders wichtige Rolle, da Verpackungstools wie pip Source-Distributionen verwenden können, um Binärabhängigkeiten zu erfüllen, z. B. wenn es eine Distribution foo.whl gibt, die eine Abhängigkeit von bar deklariert, dann müssen wir den Fall unterstützen, dass pip install bar oder pip install foo automatisch die sdist für bar findet, herunterlädt, baut und das resultierende Paket installiert.

Source-Distributionen werden auch kurz als sdists bezeichnet.

Ein Build-Frontend ist ein Werkzeug, das Benutzer ausführen können, das beliebige Quellcode-Verzeichnisse oder Source-Distributionen entgegennimmt und daraus Wheels baut. Das eigentliche Bauen wird vom Build-Backend jedes Quellcode-Verzeichnisses übernommen. In einem Befehl wie pip wheel some-directory/ agiert pip als Build-Frontend.

Ein Integrations-Frontend ist ein Werkzeug, das Benutzer ausführen können, das eine Reihe von Paket-Anforderungen entgegennimmt (z. B. eine requirements.txt-Datei) und versucht, eine funktionierende Umgebung zur Erfüllung dieser Anforderungen zu aktualisieren. Dies kann das Finden, Bauen und Installieren einer Kombination von Wheels und sdists erfordern. In einem Befehl wie pip install lxml==2.4.0 agiert pip als Integrations-Frontend.

Quellcode-Verzeichnisse

Es gibt ein bestehendes, legacy Quellcode-Verzeichnis-Format, das setup.py beinhaltet. Wir versuchen nicht, es weiter zu spezifizieren; seine De-facto-Spezifikation ist im Quellcode und in der Dokumentation von distutils, setuptools, pip und anderen Tools kodiert. Wir werden es als setup.py-Stil bezeichnen.

Hier definieren wir einen neuen Stil von Quellcode-Verzeichnissen, der auf der Datei pyproject.toml basiert, die in PEP 518 definiert ist, und erweitern die Tabelle [build-system] in dieser Datei um einen zusätzlichen Schlüssel, build-backend. Hier ist ein Beispiel, wie es aussehen würde

[build-system]
# Defined by PEP 518:
requires = ["flit"]
# Defined by this PEP:
build-backend = "flit.api:main"

build-backend ist ein String, der ein Python-Objekt benennt, das zum Ausführen des Builds verwendet wird (siehe unten für Details). Dies wird im gleichen modul:objekt-Format wie ein setuptools Entry Point formatiert. Wenn der String beispielsweise "flit.api:main" lautet, wie im obigen Beispiel, wird dieses Objekt durch Ausführen des Äquivalents von gefunden

import flit.api
backend = flit.api.main

Es ist auch legal, den Teil :objekt wegzulassen, z. B.

build-backend = "flit.api"

was so funktioniert wie

import flit.api
backend = flit.api

Formell sollte der String diese Grammatik erfüllen

identifier = (letter | '_') (letter | '_' | digit)*
module_path = identifier ('.' identifier)*
object_path = identifier ('.' identifier)*
entry_point = module_path (':' object_path)?

Und wir importieren modulpfad und schauen dann nach modulpfad.objektpfad (oder einfach modulpfad, wenn objektpfad fehlt).

Beim Importieren des Modulpfades schauen wir nicht im Verzeichnis, das das Quellcode-Verzeichnis enthält, es sei denn, dies wäre sowieso auf sys.path: (z. B. weil es in PYTHONPATH angegeben ist). Obwohl Python in einigen Situationen automatisch das Arbeitsverzeichnis zu sys.path hinzufügt, sollte der Code zur Auflösung des Backends hiervon nicht betroffen sein.

Wenn die Datei pyproject.toml fehlt oder der Schlüssel build-backend fehlt, verwendet das Quellcode-Verzeichnis diese Spezifikation nicht, und Tools sollten auf das Legacy-Verhalten zurückfallen, setup.py auszuführen (entweder direkt oder durch implizites Aufrufen des Backends setuptools.build_meta:__legacy__).

Wo der Schlüssel build-backend existiert, hat dieser Vorrang und das Quellcode-Verzeichnis folgt dem Format und den Konventionen des angegebenen Backends (somit ist kein setup.py erforderlich, es sei denn, das Backend benötigt es). Projekte möchten möglicherweise weiterhin ein setup.py für die Kompatibilität mit Tools, die diese Spezifikation nicht verwenden, beibehalten.

Dieses PEP definiert auch einen Schlüssel backend-path zur Verwendung in pyproject.toml, siehe den Abschnitt „Build-Backends im Verzeichnis“ unten. Dieser Schlüssel würde wie folgt verwendet

[build-system]
# Defined by PEP 518:
requires = ["flit"]
# Defined by this PEP:
build-backend = "local_backend"
backend-path = ["backend"]

Build-Backend-Interface

Vom Build-Backend-Objekt werden Attribute erwartet, die einige oder alle der folgenden Hooks bereitstellen. Das gemeinsame Argument config_settings wird nach den einzelnen Hooks beschrieben.

def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
    ...

def build_sdist(sdist_directory, config_settings=None):
    ...

def get_requires_for_build_wheel(config_settings=None):
    ...

def get_requires_for_build_wheel(config_settings):
    return ["wheel >= 0.25", "setuptools"]

def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None):
    ...

def get_requires_for_build_sdist(config_settings=None):
    ...

config_settings

pip install                                           \
  --package-config CC=gcc                             \
  --global-option="--some-global-option"              \
  --build-option="--build-option1"                    \
  --build-option="--build-option2"

{
 "CC": "gcc",
 "--global-option": ["--some-global-option"],
 "--build-option": ["--build-option1", "--build-option2"],
}

Source-Distributionen

Wir setzen das Legacy-Sdist-Format fort und fügen einige neue Einschränkungen hinzu. Dieses Format ist weitgehend undefiniert, kommt aber im Grunde darauf hinaus: eine Datei namens {NAME}-{VERSION}.{EXT}, die in ein buildbares Quellcode-Verzeichnis namens {NAME}-{VERSION}/ entpackt wird. Traditionell enthielten diese immer setup.py-Stil Quellcode-Verzeichnisse; wir erlauben jetzt, dass sie auch pyproject.toml-Stil Quellcode-Verzeichnisse enthalten.

Integrations-Frontends erfordern, dass eine sdist namens {NAME}-{VERSION}.{EXT} eine wheel namens {NAME}-{VERSION}-{COMPAT-INFO}.whl generiert.

Die neuen Einschränkungen für sdists, die von PEP 517-Backends gebaut werden, sind

• Sie werden komprimierte Tar-Archive sein, mit der Erweiterung .tar.gz. Zip-Archive oder andere Kompressionsformate für Tarballs sind derzeit nicht erlaubt.
• Tar-Archive müssen im modernen POSIX.1-2001 pax-Tar-Format erstellt werden, das UTF-8 für Dateinamen verwendet.
• Das in einer sdist enthaltene Quellcode-Verzeichnis wird voraussichtlich die Datei pyproject.toml enthalten.

Evolutionäre Hinweise

Ein Ziel hier ist es, die Konvertierung von Alt-Style-sdists in Neu-Style-sdists so einfach wie möglich zu gestalten. (Dies ist z. B. eine Motivation für die Unterstützung dynamischer Build-Anforderungen.) Das Ideal wäre, dass es eine einzelne statische pyproject.toml gäbe, die in jeden „Version 0“-VCS-Checkout eingefügt werden könnte, um ihn in den neuen Glanz zu konvertieren. Dies ist wahrscheinlich nicht zu 100 % möglich, aber wir können ihm nahe kommen, und es ist wichtig zu verfolgen, wie nahe wir kommen… daher dieser Abschnitt.

Ein grober Plan wäre: Ein Build-System-Paket erstellen (setuptools_pypackage oder wie auch immer) das weiß, wie man mit der von uns entwickelten Hook-Sprache spricht, und diese in Aufrufe von setup.py umwandelt. Dies wird wahrscheinlich eine Art von Haken oder Monkeypatching für setuptools erfordern, um eine Möglichkeit bereitzustellen, das setup_requires= Argument bei Bedarf zu extrahieren, und eine neue Version des sdist-Befehls bereitzustellen, die das neue Format generiert. Dies scheint alles machbar und für einen großen Teil der Pakete ausreichend zu sein (obwohl wir ein solches System natürlich prototypisieren wollen, bevor wir hier etwas abschließen). (Alternativ könnten diese Änderungen an setuptools selbst vorgenommen werden, anstatt in ein separates Paket zu gelangen.)

Es bleiben jedoch zwei Hindernisse, die bedeuten, dass wir Pakete wahrscheinlich nicht automatisch in das neue Format aktualisieren können

1. Derzeit gibt es Pakete, die darauf bestehen, dass bestimmte Pakete in ihrer Umgebung verfügbar sind, bevor setup.py ausgeführt wird. Das bedeutet, wenn wir uns entscheiden, Build-Skripte in einer isolierten virtuellen Umgebung auszuführen, müssen Projekte prüfen, ob sie dies tun, und wenn ja, müssen sie beim Upgrade auf das neue System explizit diese Abhängigkeiten deklarieren (entweder über setup_requires= oder über statische Deklaration in pyproject.toml).
2. Derzeit gibt es Pakete, die keine konsistenten Metadaten deklarieren (z. B. egg_info und bdist_wheel könnten unterschiedliche install_requires= erhalten). Beim Upgrade auf das neue System müssen Projekte prüfen, ob dies auf sie zutrifft, und wenn ja, müssen sie damit aufhören.

Abgelehnte Optionen

• Wir diskutierten die Erstellung von Wheel- und sdist-Hooks, die entpackte Verzeichnisse mit denselben Inhalten wie ihre jeweiligen Archive erstellen. In einigen Fällen könnte dies die Notwendigkeit vermeiden, ein Archiv zu packen und zu entpacken, aber das scheint eine voreilige Optimierung zu sein. Es ist vorteilhaft für Tools, mit Archiven als kanonischen Austauschformaten zu arbeiten (insbesondere für Wheels, wo das Archivformat bereits standardisiert ist). Eine genaue Kontrolle der Archivgenerierung ist für reproduzierbare Builds wichtig. Und es ist nicht klar, dass Aufgaben, die eine entpackte Distribution erfordern, häufiger vorkommen als solche, die ein Archiv erfordern.
• Wir erwogen einen zusätzlichen Hook, um Dateien vor dem Aufruf von build_wheel in ein Build-Verzeichnis zu kopieren. Bei der Betrachtung bestehender Build-Systeme stellten wir fest, dass die Übergabe eines Build-Verzeichnisses an build_wheel für viele Tools sinnvoller war als das präventive Kopieren von Dateien in ein Build-Verzeichnis.
• Die Idee, build_wheel ein Build-Verzeichnis zu übergeben, wurde dann ebenfalls als unnötige Komplikation angesehen. Build-Tools können ein temporäres Verzeichnis oder ein Cache-Verzeichnis verwenden, um Zwischendateien während des Builds zu speichern. Wenn Bedarf besteht, könnte in Zukunft ein vom Frontend gesteuertes Cache-Verzeichnis hinzugefügt werden.
• Für build_sdist, um einen Fehler aus einem erwarteten Grund zu signalisieren, wurden verschiedene Optionen sehr ausführlich diskutiert, einschließlich des Auslösens von NotImplementedError und der Rückgabe von entweder NotImplemented oder None. Bitte versuchen Sie nicht, diese Diskussion erneut zu eröffnen, es sei denn, es gibt einen *äußerst* guten Grund, da wir sie ziemlich leid sind.
• Das Importieren des Backends aus Dateien im Quellcode wäre konsistenter mit der Art und Weise, wie Python-Importe oft funktionieren. Das Zulassen davon verhindert jedoch verwirrende Fehler durch Namenskollisionen von Modulen. Die erste Version dieses PEP enthielt keine Möglichkeit, Backends aus Dateien im Quellcode zu importieren, aber der Schlüssel backend-path wurde in der nächsten Revision hinzugefügt, um Projekten die Wahl dieses Verhaltens zu ermöglichen, falls erforderlich.

Zusammenfassung der Änderungen an PEP 517

Die folgenden Änderungen wurden an diesem PEP vorgenommen, nachdem die erste Referenzimplementierung in pip 19.0 veröffentlicht wurde.

• Zyklen in den Build-Anforderungen wurden explizit verboten.
• Unterstützung für In-Tree-Backends und Self-Hosting von Backends wurde durch die Einführung des Schlüssels backend-path in der Tabelle [build-system] hinzugefügt.
• Es wurde klargestellt, dass das Backend setuptools.build_meta:__legacy__ PEP 517 eine akzeptable Alternative zur direkten Ausführung von setup.py für Quellcodebäume ist, die build-backend nicht explizit angeben.

Anhang A: Vergleich mit PEP 516

PEP 516 ist ein konkurrierender Vorschlag zur Spezifikation einer Build-System-Schnittstelle, der nun zugunsten dieses PEP abgelehnt wurde. Der Hauptunterschied besteht darin, dass unser Build-Backend über eine Python-Hook-basierte Schnittstelle definiert wird und nicht über eine Befehlszeilenschnittstelle.

Dieser Anhang dokumentiert die Argumente, die für dieses PEP gegenüber PEP 516 vorgebracht wurden.

Wir erwarten *nicht*, dass die Angabe von Python-Hooks anstelle von Befehlszeilenschnittstellen allein die Komplexität des Aufrufs des Backends reduziert, da Build-Frontends Hooks ohnehin in einem Kindprozess ausführen wollen – dies ist wichtig, um das Build-Frontend selbst vom Backend-Code zu isolieren und die Ausführungsumgebung der Build-Backends besser zu kontrollieren. Unter beiden Vorschlägen muss es also Code in pip geben, um einen Subprozess zu starten und mit einer Art Befehlszeilen-/IPC-Schnittstelle zu kommunizieren, und es muss Code im Subprozess geben, der diese Befehlszeilenargumente parsen und die eigentliche Build-Backend-Implementierung aufrufen kann. Dieses Diagramm gilt also für alle Vorschläge gleichermaßen.

+-----------+          +---------------+           +----------------+
| frontend  | -spawn-> | child cmdline | -Python-> |    backend     |
|   (pip)   |          |   interface   |           | implementation |
+-----------+          +---------------+           +----------------+

Der Hauptunterschied zwischen den beiden Ansätzen ist, wie diese Schnittstellengrenzen auf die Projektstruktur abgebildet werden.

.-= This PEP =-.

+-----------+          +---------------+    |      +----------------+
| frontend  | -spawn-> | child cmdline | -Python-> |    backend     |
|   (pip)   |          |   interface   |    |      | implementation |
+-----------+          +---------------+    |      +----------------+
                                            |
|______________________________________|    |
   Owned by pip, updated in lockstep        |
                                            |
                                            |
                                 PEP-defined interface boundary
                               Changes here require distutils-sig


.-= Alternative =-.

+-----------+    |     +---------------+           +----------------+
| frontend  | -spawn-> | child cmdline | -Python-> |    backend     |
|   (pip)   |    |     |   interface   |           | implementation |
+-----------+    |     +---------------+           +----------------+
                 |
                 |     |____________________________________________|
                 |      Owned by build backend, updated in lockstep
                 |
    PEP-defined interface boundary
  Changes here require distutils-sig

Durch die Verlagerung der PEP-definierten Schnittstellengrenze in Python-Code gewinnen wir drei wichtige Vorteile.

Erstens, da es wahrscheinlich nur eine kleine Anzahl von Build-Frontends geben wird (pip und... vielleicht ein paar andere?), während es wahrscheinlich einen langen Schwanz von benutzerdefinierten Build-Backends geben wird (da diese von jedem Paket separat gewählt werden, um ihren spezifischen Build-Anforderungen zu entsprechen), sehen die eigentlichen Diagramme wahrscheinlich eher so aus:

.-= This PEP =-.

+-----------+          +---------------+           +----------------+
| frontend  | -spawn-> | child cmdline | -Python+> |    backend     |
|   (pip)   |          |   interface   |        |  | implementation |
+-----------+          +---------------+        |  +----------------+
                                                |
                                                |  +----------------+
                                                +> |    backend     |
                                                |  | implementation |
                                                |  +----------------+
                                                :
                                                :

.-= Alternative =-.

+-----------+          +---------------+           +----------------+
| frontend  | -spawn+> | child cmdline | -Python-> |    backend     |
|   (pip)   |       |  |   interface   |           | implementation |
+-----------+       |  +---------------+           +----------------+
                    |
                    |  +---------------+           +----------------+
                    +> | child cmdline | -Python-> |    backend     |
                    |  |   interface   |           | implementation |
                    |  +---------------+           +----------------+
                    :
                    :

Das heißt, dieses PEP führt zu weniger Gesamtcode im gesamten Ökosystem. Und insbesondere reduziert es die Eintrittsbarriere für die Erstellung eines neuen Build-Systems. Dies ist zum Beispiel ein vollständiges, funktionierendes Build-Backend:

# mypackage_custom_build_backend.py
import os.path
import pathlib
import shutil
import tarfile

SDIST_NAME = "mypackage-0.1"
SDIST_FILENAME = SDIST_NAME + ".tar.gz"
WHEEL_FILENAME = "mypackage-0.1-py2.py3-none-any.whl"

#################
# sdist creation
#################

def _exclude_hidden_and_special_files(archive_entry):
    """Tarfile filter to exclude hidden and special files from the archive"""
    if archive_entry.isfile() or archive_entry.isdir():
        if not os.path.basename(archive_entry.name).startswith("."):
            return archive_entry

def _make_sdist(sdist_dir):
    """Make an sdist and return both the Python object and its filename"""
    sdist_path = pathlib.Path(sdist_dir) / SDIST_FILENAME
    sdist = tarfile.open(sdist_path, "w:gz", format=tarfile.PAX_FORMAT)
    # Tar up the whole directory, minus hidden and special files
    sdist.add(os.getcwd(), arcname=SDIST_NAME,
              filter=_exclude_hidden_and_special_files)
    return sdist, SDIST_FILENAME

def build_sdist(sdist_dir, config_settings):
    """PEP 517 sdist creation hook"""
    sdist, sdist_filename = _make_sdist(sdist_dir)
    return sdist_filename

#################
# wheel creation
#################

def get_requires_for_build_wheel(config_settings):
    """PEP 517 wheel building dependency definition hook"""
    # As a simple static requirement, this could also just be
    # listed in the project's build system dependencies instead
    return ["wheel"]

def build_wheel(wheel_directory,
                metadata_directory=None, config_settings=None):
    """PEP 517 wheel creation hook"""
    from wheel.archive import archive_wheelfile
    path = os.path.join(wheel_directory, WHEEL_FILENAME)
    archive_wheelfile(path, "src/")
    return WHEEL_FILENAME

Natürlich ist dies ein *schreckliches* Build-Backend: Es erfordert, dass der Benutzer die Wheel-Metadaten manuell in src/mypackage-0.1.dist-info/ eingerichtet hat; wenn sich die Versionsnummer ändert, muss sie an mehreren Stellen manuell aktualisiert werden... aber es funktioniert, und weitere Funktionen könnten inkrementell hinzugefügt werden. Viel Erfahrung zeigt, dass große erfolgreiche Projekte oft als schnelle Hacks entstehen (z. B. Linux – „nur ein Hobby, wird nicht groß und professionell“; IPython/Jupyter – die $PYTHONSTARTUP-Datei eines Doktoranden), daher ist es wichtig, die Eintrittsbarriere zu minimieren, wenn unser Ziel darin besteht, das Wachstum eines lebendigen Ökosystems guter Build-Tools zu fördern.

Zweitens, da Python eine einfachere und gleichzeitig reichhaltigere Struktur zur Beschreibung von Schnittstellen bietet, entfernen wir unnötige Komplexität aus der Spezifikation – und Spezifikationen sind der schlimmste Ort für Komplexität, da die Änderung von Spezifikationen mühsame Konsensbildung über viele Stakeholder hinweg erfordert. Im Ansatz mit der Befehlszeilenschnittstelle müssen wir ad-hoc-Wege finden, um verschiedene Arten von Eingaben auf eine einzige lineare Befehlszeile abzubilden (z. B. wie vermeiden wir Kollisionen zwischen benutzerdefinierten Konfigurationsargumenten und PEP-definierten Argumenten? Wie geben wir optionale Argumente an? Bei der Arbeit mit einer Python-Schnittstelle haben diese Fragen einfache, offensichtliche Antworten). Beim Starten und Verwalten von Subprozessen gibt es viele knifflige Details, die richtig gemacht werden müssen, subtile plattformübergreifende Unterschiede, und einige der offensichtlichsten Ansätze – z. B. die Verwendung von stdout zur Rückgabe von Daten für die build_requires-Operation – können unerwartete Fallstricke erzeugen (z. B. was passiert, wenn die Berechnung der Build-Anforderungen das Starten einiger Kindprozesse erfordert und diese Kinder gelegentlich eine Fehlermeldung auf stdout ausgeben? Offensichtlich kann ein sorgfältiger Autor von Build-Backends dieses Problem vermeiden, aber der offensichtlichste Weg zur Definition einer Python-Schnittstelle eliminiert diese Möglichkeit vollständig, da der Hook-Rückgabewert klar abgegrenzt ist).

Im Allgemeinen bedeutet die Notwendigkeit, Build-Backends in ihren eigenen Prozess zu isolieren, dass wir die IPC-Komplexität nicht vollständig entfernen können – aber indem wir beide Seiten des IPC-Kanals unter die Kontrolle eines einzigen Projekts stellen, machen wir es viel billiger, Fehler in der IPC-Schnittstelle zu beheben, als wenn die Behebung von Fehlern koordinierte Zustimmung und koordinierte Änderungen im gesamten Ökosystem erfordert.

Drittens und am wichtigsten ist, dass der Python-Hook-Ansatz uns viel mächtigere Optionen für die Weiterentwicklung dieser Spezifikation in der Zukunft bietet.

Um konkret zu werden, stellen Sie sich vor, wir fügen nächstes Jahr einen neuen Hook build_sdist_from_vcs hinzu, der eine Alternative zum aktuellen Hook build_sdist bietet, bei der das Frontend für die Übergabe von Versionskontroll-Tracking-Metadaten an Backends verantwortlich ist (einschließlich der Angabe, wann alle auf der Festplatte befindlichen Dateien verfolgt werden), anstatt dass einzelne Backends diese Informationen selbst abfragen müssen. Um den Übergang zu bewältigen, möchten wir, dass Build-Frontends build_sdist_from_vcs transparent verwenden können, wenn es verfügbar ist, und andernfalls auf build_sdist zurückfallen; und wir möchten, dass Build-Backends beide Methoden definieren können, um mit alten und neuen Build-Frontends kompatibel zu sein.

Darüber hinaus sollte unser Mechanismus zwei weitere Ziele erfüllen: (a) Wenn neue Versionen von z. B. pip und flit beide aktualisiert werden, um die neue Schnittstelle zu unterstützen, dann sollte dies ausreichen, damit sie verwendet werden kann; insbesondere sollte es *nicht* notwendig sein, dass jedes Projekt, das flit *verwendet*, seine individuelle pyproject.toml-Datei aktualisiert. (b) Wir wollen keine zusätzlichen Prozesse starten, nur um diese Verhandlung durchzuführen, da Prozessstarts bei der Bereitstellung großer Multi-Package-Stacks auf einigen Plattformen (Windows) leicht zu einem Engpass werden können.

In der hier beschriebenen Schnittstelle sind all diese Ziele leicht zu erreichen. Da pip den Code steuert, der im Kindprozess ausgeführt wird, kann es diesen leicht so schreiben, dass er etwas wie folgt tut:

command, backend, args = parse_command_line_args(...)
if command == "build_sdist":
   if hasattr(backend, "build_sdist_from_vcs"):
       backend.build_sdist_from_vcs(...)
   elif hasattr(backend, "build_sdist"):
       backend.build_sdist(...)
   else:
       # error handling

In der Alternative, bei der die öffentliche Schnittstellengrenze am Subprozessaufruf platziert wird, ist dies nicht möglich – entweder müssen wir einen zusätzlichen Prozess starten, nur um abzufragen, welche Schnittstellen unterstützt werden (wie in einer früheren Version von PEP 516 enthalten, einer Alternative dazu), oder wir verzichten ganz auf die automatische Aushandlung (wie in der aktuellen Version dieses PEP), was bedeutet, dass jede Änderung an der Schnittstelle N einzelne Pakete erfordert, ihre pyproject.toml-Dateien aktualisieren müssen, bevor eine Änderung in Kraft treten kann, und dass Änderungen notwendigerweise auf neue Releases beschränkt sein werden.

Eine spezifische Konsequenz davon ist, dass wir in diesem PEP den Befehl prepare_metadata_for_build_wheel optional machen können. In unserem Design kann dies leicht von Build-Frontends gehandhabt werden, die Code in ihrem Subprozess-Runner platzieren können, wie z. B.:

def dump_wheel_metadata(backend, working_dir):
    """Dumps wheel metadata to working directory.

       Returns absolute path to resulting metadata directory
    """
    if hasattr(backend, "prepare_metadata_for_build_wheel"):
        subdir = backend.prepare_metadata_for_build_wheel(working_dir)
    else:
        wheel_fname = backend.build_wheel(working_dir)
        already_built = os.path.join(working_dir, "ALREADY_BUILT_WHEEL")
        with open(already_built, "w") as f:
            f.write(wheel_fname)
        subdir = unzip_metadata(os.path.join(working_dir, wheel_fname))
    return os.path.join(working_dir, subdir)

def ensure_wheel_is_built(backend, output_dir, working_dir, metadata_dir):
    """Ensures built wheel is available in output directory

       Returns absolute path to resulting wheel file
    """
    already_built = os.path.join(working_dir, "ALREADY_BUILT_WHEEL")
    if os.path.exists(already_built):
        with open(already_built, "r") as f:
            wheel_fname = f.read().strip()
        working_path = os.path.join(working_dir, wheel_fname)
        final_path = os.path.join(output_dir, wheel_fname)
        os.rename(working_path, final_path)
        os.remove(already_built)
    else:
        wheel_fname = backend.build_wheel(output_dir, metadata_dir=metadata_dir)
    return os.path.join(output_dir, wheel_fname)

und somit eine völlig einheitliche Schnittstelle für den Rest des Frontends bereitstellen, ohne zusätzliche Subprozessaufrufe, keine doppelten Builds usw. Aber offensichtlich ist dies die Art von Code, die man nur als Teil einer privaten, inner-projektbezogenen Schnittstelle schreiben möchte (z. B. erfordert das gegebene Beispiel, dass das Arbeitsverzeichnis zwischen den beiden Aufrufen geteilt wird, aber nicht mit anderen Wheel-Builds, und dass der Rückgabewert der Metadaten-Hilfsfunktion an den Wheel-Bau-Aufruf zurückgegeben wird).

(Und natürlich ist das optionale Machen des metadata-Befehls ein Teil der Senkung der Eintrittsbarriere für die Entwicklung neuer Backends, wie oben erwähnt.)

Urheberrecht

Dieses Dokument wurde gemeinfrei erklärt.