Zusammenfassung

Dieses PEP beschreibt ein Standard-Namensschema für eine Quellverteilung (Source Distribution), auch bekannt als sdist. Eine sdist unterscheidet sich von einer beliebigen Archivdatei, die Quellcode von Python-Paketen enthält, und kann dazu verwendet werden, Informationen über die Verteilung an Paketierungswerkzeuge zu übermitteln.

Eine hier spezifizierte Standard-sdist ist eine gzip-komprimierte Tar-Datei mit einem speziell formatierten Dateinamen und der üblichen .tar.gz-Erweiterung. Dieses PEP spezifiziert nicht den Inhalt des Tarballs, da dies in anderen Spezifikationen behandelt wird.

Motivation

Eine sdist ist eine Python-Paketverteilung, die den „Quellcode“ des Python-Pakets enthält und einen Build-Schritt erfordert, um bei der Installation in ein Wheel umgewandelt zu werden. Dieses Format wird oft als unbuilt Gegenstück zu einem PEP 427 Wheel betrachtet und erhält in verschiedenen Teilen des Packaging-Ökosystems besondere Behandlung.

Der Inhalt einer sdist ist in PEP 517 und PEP 643 spezifiziert, aber derzeit ist der Dateiname der sdist unvollständig spezifiziert. Das bedeutet, dass Konsumenten des Formats die sdist herunterladen und verarbeiten müssen, um den Namen und die Version der enthaltenen Verteilung zu bestätigen.

Installationsprogramme verlassen sich derzeit auf Heuristiken, um den Namen und/oder die Version aus dem Dateinamen abzuleiten und so den Installationsprozess zu unterstützen. pip beispielsweise parst den Dateinamen einer sdist aus einem PEP 503 Index, um den Projektnamen und die Version der Verteilung für die Abhängigkeitsauflösung zu erhalten. Aber aufgrund des Mangels an Spezifikation hat das Installationsprogramm keine Garantie für die Korrektheit der abgeleiteten Daten und muss sie irgendwann durch lokales Erstellen der Verteilungsmetadaten verifizieren.

Dieser Build-Schritt ist für eine bestimmte Art von Operationen umständlich, wenn der Benutzer nicht erwartet, dass der Build-Prozess stattfindet. pypa/pip#8387 beschreibt ein Beispiel. Der Befehl pip download --no-deps --no-binary=numpy numpy soll nur eine sdist für numpy herunterladen, da wir nicht nach Abhängigkeiten suchen müssen und sowohl der Name als auch die Version durch Untersuchung des heruntergeladenen Dateinamens verfügbar sind. pip kann jedoch nicht davon ausgehen, dass das heruntergeladene Archiv der Konvention entspricht, und muss die Metadaten erstellen und überprüfen. Für ein PEP 518 Projekt bedeutet dies, den Hook prepare_metadata_for_build_wheel auszuführen, der in PEP 517 spezifiziert ist, was zu erheblichem Mehraufwand führt.

Begründung

Durch die Schaffung eines speziellen Namensschemas für das sdist-Format befreit dieses PEP Werkzeuge von der zeitraubenden Überprüfung der Metadaten, wenn sie nur die im Dateinamen verfügbaren Metadaten benötigen.

Dieses PEP dient auch als formale Spezifikation für die seit langem bestehende Konvention zur Benennung von sdist-Dateien, die von aktuellen sdist-Implementierungen verwendet wird. Der Dateiname enthält den Namen und die Version der Verteilung, um Werkzeugen die Identifizierung einer Verteilung zu erleichtern, ohne die Datei herunterladen, entpacken und eine kostspielige Metadatengenerierung zur Introspektion durchführen zu müssen, wenn alle benötigten Informationen im Dateinamen verfügbar sind.

Spezifikation

Der Name einer sdist sollte {distribution}-{version}.tar.gz lauten.

• distribution ist der Name der Verteilung, wie in PEP 345 definiert und wie in der Wheel-Spezifikation beschrieben normalisiert, z. B. 'pip', 'flit_core'.
• version ist die Version der Verteilung, wie in PEP 440 definiert, z. B. 20.2, und gemäß den Regeln in diesem PEP normalisiert.

Eine sdist muss ein gzip-komprimiertes Tar-Archiv im pax-Format sein, das vom Standard-Bibliotheksmodul tarfile mit dem Öffnungsflag 'r:gz' extrahiert werden kann.

Code, der eine sdist-Datei erzeugt, MUSS der Datei einen Namen geben, der dieser Spezifikation entspricht. Die Spezifikation des build_sdist-Hooks aus PEP 517 wird erweitert, um diese Benennungskonvention zu verlangen.

Code, der sdist-Dateien verarbeitet, KANN den Verteilungsnamen und die Version durch einfaches Parsen des Dateinamens bestimmen und ist nicht verpflichtet, diese Informationen durch Generieren oder Lesen der Metadaten aus dem sdist-Inhalt zu verifizieren.

Konforme sdist-Dateien können durch das Vorhandensein der .tar.gz-Erweiterung und eines *einzigen* Bindestrichs im Dateinamen erkannt werden. Beachten Sie, dass einige Legacy-Dateien ebenfalls diese Kriterien erfüllen können, dies wird jedoch voraussichtlich kein Problem darstellen. Weitere Details finden Sie im Abschnitt „Rückwärtskompatibilität“ dieses Dokuments.

Abwärtskompatibilität

Das neue Dateinamensschema ist eine Teilmenge der aktuellen informellen Benennungskonvention für sdist-Dateien. Werkzeuge, die Dateien erstellen oder veröffentlichen, die diesem Standard entsprechen, sind also für ältere Werkzeuge lesbar, die nur die vorherigen Benennungskonventionen verstehen.

Werkzeuge, die sdist-Dateinamen verarbeiten, können technisch nicht feststellen, ob eine Datei den neuen Standard oder eine Legacy-Form verwendet. Eine Überprüfung der Dateinamen auf PyPI ergab jedoch, dass 37 % der Dateien offensichtlich Legacy sind (da sie mehrere oder keine Bindestriche enthalten) und von den übrigen gibt das Parsen gemäß diesem PEP in allen bis auf 0,004 % der Fälle das richtige Ergebnis.

Derzeit sollten Werkzeuge, die sdists verarbeiten, den aus dem Dateinamen geparsten Namen und die Version als vorläufig behandeln, wenn sie vollständig korrekt sein sollen, und sie durch Herunterladen der Datei und Generieren der tatsächlichen Metadaten (oder Lesen davon, wenn die sdist mit PEP 643 konform ist) verifizieren. Werkzeuge, die diese Spezifikation unterstützen, können den Namen und die Version aus dem Dateinamen als endgültig behandeln. Theoretisch könnte dies zu Fehlern führen, wenn ein Legacy-Dateiname fälschlicherweise als diesem PEP entsprechend angenommen wird, aber in der Praxis scheint die Wahrscheinlichkeit dafür verschwindend gering zu sein.

Abgelehnte Ideen

Offene Fragen

Der Inhalt einer sdist muss ein einzelnes Top-Level-Verzeichnis namens {name}-{version} enthalten. Derzeit sind keine Normalisierungsregeln für die Komponenten dieses Namens erforderlich. Sollte dieses PEP verlangen, dass die gleichen Normalisierungsregeln wie für den Dateinamen angewendet werden? Beachten Sie, dass es wahrscheinlich ist, dass Werkzeuge die beiden Namen mit demselben Code erstellen, sodass die Normalisierung wahrscheinlich natürlich erfolgt, auch wenn sie nicht explizit erforderlich ist.

Urheberrecht

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