Unterstützende Definitionen

Die Schlüsselwörter „MUSS“, „DARF NICHT“, „ERFORDERLICH“, „SOLL“, „SOLL NICHT“, „EMPFOHLEN“, „KANN“ und „OPTIONAL“ in diesem Dokument sind wie in RFC 2119 beschrieben zu interpretieren.

„Projekte“ sind Softwarekomponenten, die zur Integration bereitgestellt werden. Zu den Projekten gehören Python-Bibliotheken, Frameworks, Skripte, Plugins, Anwendungen, Datensammlungen oder andere Ressourcen und verschiedene Kombinationen davon. Öffentliche Python-Projekte werden typischerweise im Python Package Index registriert.

„Releases“ sind eindeutig identifizierte Momentaufnahmen eines Projekts.

„Distributionspakete“ sind die verpackten Dateien, die zur Veröffentlichung und Verteilung eines Releases verwendet werden.

Je nach Kontext kann sich „Paket“ entweder auf eine Distribution oder auf ein importierbares Python-Modul beziehen, das ein Attribut __path__ hat und daher auch importierbare Submodule haben kann.

„Quellcode-Archiv“ und „VCS-Checkout“ beziehen sich beide auf den rohen Quellcode für einen Release, bevor ein sdist oder ein binäres Archiv erstellt wird.

Ein „sdist“ ist ein Veröffentlichungsformat, das die Distributionsmetadaten und alle Quelldateien bereitstellt, die für die Erstellung eines binären Archivs für die Distribution unerlässlich sind. Die Erstellung eines binären Archivs aus einem sdist erfordert, dass die entsprechenden Build-Tools auf dem System verfügbar sind.

„Binäre Archive“ erfordern nur, dass vorkompilierte Dateien an die richtige Stelle auf dem Zielsystem verschoben werden. Da Python eine dynamisch gebundene plattformübergreifende Sprache ist, enthalten viele sogenannte „binäre“ Archive nur reinen Python-Quellcode.

„Mitwirkende“ sind Einzelpersonen und Organisationen, die zusammenarbeiten, um eine Softwarekomponente zu entwickeln.

„Publisher“ sind Einzelpersonen und Organisationen, die Softwarekomponenten zur Integration bereitstellen (typischerweise durch Hochladen von Distributionen auf einen Indexserver)

„Integratoren“ sind Einzelpersonen und Organisationen, die veröffentlichte Distributionen als Komponenten einer Anwendung oder eines größeren Systems integrieren.

„Build-Tools“ sind automatisierte Tools, die auf Entwicklungssystemen ausgeführt werden und Quellcode- und Binärdistributionsarchive erstellen. Build-Tools können auch von Integrationswerkzeugen aufgerufen werden, um Software zu erstellen, die als sdists anstelle von vorkompilierten Binärarchiven verteilt wird.

„Indexserver“ sind aktive Distributionsregister, die Versions- und Abhängigkeitsmetadaten veröffentlichen und Einschränkungen für die zulässigen Metadaten auferlegen.

„Öffentliche Indexserver“ sind Indexserver, die Distributionen-Uploads von nicht vertrauenswürdigen Drittanbietern zulassen. Der Python Package Index ist ein öffentlicher Indexserver.

„Veröffentlichungswerkzeuge“ sind automatisierte Werkzeuge, die auf Entwicklungssystemen ausgeführt werden und Quellcode- und Binärdistributionsarchive auf Indexserver hochladen.

„Integrationswerkzeuge“ sind automatisierte Werkzeuge, die Metadaten und Distributionsarchive von einem Indexserver oder einer anderen designierten Quelle konsumieren und sie in irgendeiner Weise nutzen, z. B. indem sie sie installieren oder in ein plattformspezifisches Paketformat konvertieren.

„Installationswerkzeuge“ sind Integrationswerkzeuge, die speziell für die Ausführung auf Bereitstellungszielen bestimmt sind, Quellcode- und Binärdistributionsarchive von einem Indexserver oder einem anderen designierten Speicherort konsumieren und sie auf dem Zielsystem bereitstellen.

„Automatisierte Werkzeuge“ ist ein Sammelbegriff für Build-Tools, Indexserver, Veröffentlichungswerkzeuge, Integrationswerkzeuge und jede andere Software, die Distributionsversions- und Abhängigkeitsmetadaten erstellt oder konsumiert.

„Legacy-Metadaten“ bezieht sich auf frühere Versionen dieser Metadatenspezifikation sowie auf die unterstützenden Metadatendateiformate, die vom setuptools Projekt definiert wurden.

„Distro“ wird als bevorzugter Begriff für Linux-Distributionen verwendet, um Verwechslungen mit der Python-spezifischen Verwendung des Begriffs „Distributionspaket“ zu vermeiden.

„Qualifizierter Name“ ist ein punktierter Python-Bezeichner. Für importierte Module und Pakete ist der qualifizierte Name als Attribut __name__ verfügbar, während er für Funktionen und Klassen als Attribut __qualname__ verfügbar ist.

Ein „vollständig qualifizierter Name“ lokalisiert ein Objekt eindeutig im Python-Modul-Namensraum. Für importierte Module und Pakete ist er identisch mit dem qualifizierten Namen. Für andere Python-Objekte besteht der vollständig qualifizierte Name aus dem qualifizierten Namen des enthaltenden Moduls oder Pakets, einem Doppelpunkt (:) und dem qualifizierten Namen des Objekts relativ zum enthaltenden Modul oder Paket.

Ein „präfixierter Name“ beginnt mit einem qualifizierten Namen, ist aber nicht unbedingt ein qualifizierter Name – er kann zusätzliche punktgetrennte Segmente enthalten, die keine gültigen Bezeichner sind.

Integration und Bereitstellung von Distributionen

Der Hauptzweck der Distributionsmetadaten ist die Unterstützung der Integration und Bereitstellung von Distributionen als Teil größerer Anwendungen und Systeme.

Integration und Bereitstellung können wiederum in weitere Unterschritte unterteilt werden.

• Build: Der Build-Schritt ist der Prozess, bei dem ein VCS-Checkout, ein Quellcode-Archiv oder ein sdist in ein binäres Archiv umgewandelt wird. Abhängigkeiten müssen verfügbar sein, um die Distribution zu bauen und ein binäres Archiv davon zu erstellen (einschließlich aller Dokumentation, die auf Zielsystemen installiert wird).
• Installation: Der Installationsschritt beinhaltet das Übertragen der Distribution und aller ihrer Laufzeitabhängigkeiten auf das Zielsystem. In diesem Schritt kann die Distribution bereits auf dem System vorhanden sein (beim Upgrade oder Neuinstallieren) oder es kann sich um eine komplett neue Installation handeln.
• Laufzeit: Dies ist die normale Verwendung einer Distribution, nachdem sie auf dem Zielsystem installiert wurde.

Diese drei Schritte können alle direkt auf dem Zielsystem durchgeführt werden. Alternativ kann der Build-Schritt durch die Verwendung von binären Archiven, die vom Publisher der Distribution bereitgestellt werden, oder durch die Erstellung der binären Archive auf einem separaten System vor der Bereitstellung getrennt werden. Der Vorteil des letzteren Ansatzes ist, dass die auf den Bereitstellungstargets zu installierenden Abhängigkeiten minimiert werden (da die Build-Abhängigkeiten nur auf den Build-Systemen benötigt werden).

Die veröffentlichten Metadaten für Distributionspakete SOLLTEN Integratoren mit Hilfe von Build- und Integrationswerkzeugen ermöglichen,

• den ursprünglichen Quellcode zu erhalten, der zur Erstellung einer Distribution verwendet wurde
• die Abhängigkeiten (falls vorhanden) zu identifizieren und abzurufen, die zur Verwendung einer Distribution erforderlich sind
• die Abhängigkeiten (falls vorhanden) zu identifizieren und abzurufen, die zum Erstellen einer Distribution aus dem Quellcode erforderlich sind
• die Abhängigkeiten (falls vorhanden) zu identifizieren und abzurufen, die zum Ausführen der Testsuite einer Distribution erforderlich sind

Entwicklung und Veröffentlichung von Distributionen

Der sekundäre Zweck der Distributionsmetadaten ist die Unterstützung der effektiven Zusammenarbeit zwischen Software-Mitwirkenden und Publishern während der Entwicklungsphase.

Die veröffentlichten Metadaten für Distributionen SOLLTEN Mitwirkenden und Publishern mit Hilfe von Build- und Veröffentlichungswerkzeugen ermöglichen,

• alle Aktivitäten durchzuführen, die zur effektiven Integration und Bereitstellung der Distribution erforderlich sind
• die zusätzlichen Abhängigkeiten zu identifizieren und abzurufen, die zur Entwicklung und Veröffentlichung der Distribution erforderlich sind
• die Abhängigkeiten (falls vorhanden) anzugeben, die zur Verwendung der Distribution erforderlich sind
• die Abhängigkeiten (falls vorhanden) anzugeben, die zum Erstellen der Distribution aus dem Quellcode erforderlich sind
• die Abhängigkeiten (falls vorhanden) anzugeben, die zum Ausführen der Testsuite der Distribution erforderlich sind
• die zusätzlichen Abhängigkeiten (falls vorhanden) anzugeben, die zur Entwicklung und Veröffentlichung der Distribution erforderlich sind

Metadatendateien

Die in dieser PEP definierten Informationen werden für einige Anwendungsfälle in pysdist.json-Dateien serialisiert. Dies sind Dateien, die UTF-8-kodierte JSON-Metadaten enthalten.

Jede Metadatendatei besteht aus einer einzelnen serialisierten Zuordnung mit Feldern, wie in dieser PEP beschrieben. Bei der Serialisierung von Metadaten sollten automatisierte Werkzeuge die Schlüssel und Listenelemente lexikalisch sortieren, um die Überprüfung von Änderungen zu vereinfachen.

Es werden voraussichtlich drei Standardpositionen für diese Metadatendateien geben

• als Datei {distribution}-{version}.dist-info/pysdist.json in einem sdist-Quellcode-Distributionsarchiv
• als Datei {distribution}-{version}.dist-info/pysdist.json in einem wheel-Binärdistributionsarchiv
• als Datei {distribution}-{version}.dist-info/pysdist.json in einer lokalen Python-Installationsdatenbank

Diese Datei wird voraussichtlich in allen drei Positionen identisch sein – sie wird beim Erstellen eines Quellcode-Archivs oder eines Binärarchivs aus einem Quellbaum generiert und dann bei der Installation oder beim Erstellen eines Binärarchivs aus einem Quellcode-Archiv unverändert beibehalten.

Beachten Sie, dass diese Metadatendateien auch dann verarbeitet werden können, wenn die Version des enthaltenden Speicherorts zu niedrig ist, um anzuzeigen, dass sie gültig sind. Insbesondere nicht versionierte sdist-Archive, nicht versionierte Verzeichnisse von Installationsdatenbanken und Version 1.0 der wheel-Spezifikation können weiterhin pysdist.json-Dateien bereitstellen.

Andere an der Python-Distribution beteiligte Werkzeuge können dieses Format ebenfalls verwenden.

Beachten Sie, dass diese Metadatendateien von Build-Tools basierend auf anderen Eingabeformaten (wie setup.py und pyproject.toml) generiert werden und nicht direkt als Dateneingabeformat verwendet werden. Das Generieren der Metadaten als Teil des Veröffentlichungsprozesses hilft auch bei der Handhabung versionsspezifischer Felder (einschließlich der Quellcode-URL und des Versionsfelds selbst).

Zur Rückwärtskompatibilität mit älteren Installationswerkzeugen können Metadaten 2.0-Dateien neben Legacy-Metadaten verteilt werden.

Indexserver können zulassen, dass Distributionen hochgeladen werden, und Installationswerkzeuge können zulassen, dass Distributionen nur mit Legacy-Metadaten installiert werden.

Automatisierte Werkzeuge können versuchen, Legacy-Metadaten automatisch in das in dieser PEP beschriebene Format zu übersetzen. Ratschläge zur effektiven Durchführung sind in Anhang A zu finden.

Metadatenvalidierung

Eine jsonschema-Beschreibung der Distributionsmetadaten ist verfügbar.

Dieses Schema behandelt derzeit nicht die Validierung einiger komplexerer String-Felder (sondern behandelt sie als undurchsichtige Strings).

Sofern nicht anders angegeben, müssen alle URL-Felder in den Metadaten mit RFC 3986 übereinstimmen.

Metadatenversion

Version des Dateiformats; "2.0" ist der einzig gültige Wert.

Automatisierte Werkzeuge, die Metadaten konsumieren, sollten warnen, wenn metadata_version höher ist als die höchste von ihnen unterstützte Version, und müssen fehlschlagen, wenn metadata_version eine größere Hauptversion hat als die höchste von ihnen unterstützte Version (wie in PEP 440 beschrieben, ist die Hauptversion der Wert vor dem ersten Punkt).

Für breitere Kompatibilität können Build-Tools Distribution-Metadaten unter Verwendung der niedrigsten Metadatenversion erstellen, die alle benötigten Felder enthält.

Beispiel

"metadata_version": "2.0"

Generator

Name (und optionale Version) des Programms, das die Datei generiert hat, falls vorhanden. Eine manuell erstellte Datei würde dieses Feld weglassen.

Beispiele

"generator": "flit"
"generator": "setuptools (34.3.1)"

Name

Der Name der Distribution, wie in PEP 508 definiert.

Da Distributionsnamen Teil von URLs, Dateinamen und Kommandozeilenparametern sind und auch mit anderen Paketierungssystemen interoperieren müssen, sind die zulässigen Zeichen beschränkt auf

• ASCII-Buchstaben ([a-zA-Z])
• ASCII-Ziffern ([0-9])
• Unterstriche (_)
• Bindestriche (-)
• Punkte (.)

Distributionsnamen müssen mit einem ASCII-Buchstaben oder einer Ziffer beginnen und enden.

Automatisierte Werkzeuge müssen nicht konforme Namen ablehnen. Ein regulärer Ausdruck zur Erzwingung dieser Einschränkungen (wenn er mit re.IGNORECASE ausgeführt wird) ist

^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$

Alle Vergleiche von Distributionsnamen müssen case-insensitiv sein und müssen Bindestriche und Unterstriche als äquivalent betrachten.

Indexserver können „verwechselbare“ Zeichen (wie von der Unicode-Konvention in TR39: Unicode Security Mechanisms definiert) als äquivalent betrachten.

Indexserver, die beliebige Distributionsnamenregistrierungen von nicht vertrauenswürdigen Quellen zulassen, sollten bei der Registrierung neuer Distributionen verwechselbare Zeichen als äquivalent betrachten (und sie daher als Duplikate ablehnen).

Integrationswerkzeuge dürfen eine verwechselbare alternative Schreibweise nicht stillschweigend als Übereinstimmung mit einem angeforderten Distributionsnamen akzeptieren.

Zum Zeitpunkt der Niederschrift sind die als verwechselbar eingestuften Zeichen im ASCII-Teil der Unicode-Konvention

• 1 (Ziffer Eins), l (Kleinbuchstabe l) und I (Großbuchstabe I)
• 0 (Ziffer Null) und O (Großbuchstabe O)

Beispiel

"name": "ComfyChair"

Version

Der öffentliche oder lokale Versionsidentifikator der Distribution, wie in PEP 440 definiert. Versionsidentifikatoren sind für die Verwendung durch automatisierte Werkzeuge konzipiert und unterstützen eine Vielzahl flexibler Versionsspezifikationsmechanismen (siehe PEP 440 für Details).

Versionsidentifikatoren müssen dem in PEP 440 definierten Format entsprechen.

Versionsidentifikatoren müssen innerhalb jedes Projekts eindeutig sein.

Indexserver können Einschränkungen für die Verwendung lokaler Versionsidentifikatoren auferlegen, wie in PEP 440 beschrieben.

Beispiel

"version": "1.0a2"

Zusammenfassung

Eine kurze Zusammenfassung dessen, was die Distribution tut.

Dieses Feld sollte weniger als 512 Zeichen enthalten und muss weniger als 2048 enthalten.

Dieses Feld sollte keine Zeilenumbrüche enthalten.

Eine vollständigere Beschreibung sollte als separate Datei im sdist für die Distribution enthalten sein. Informationen hierzu finden Sie in der Erweiterung python-details in PEP 459.

Beispiel

"summary": "A module that is more fiendish than soft cushions."

Quellcode-Labels

Quellkennzeichnungen sind Textzeichenfolgen mit minimal definierten Semantiken. Sie dienen dazu, den ursprünglichen Quellcode eindeutig zu identifizieren, selbst wenn ein Integrator zusätzliche lokale Modifikationen an einer bestimmten Distribution vorgenommen hat.

Um sicherzustellen, dass Quellkennzeichnungen einfach als Teil von Dateinamen und URLs verwendet werden können und um Formatierungsinkonsistenzen bei hexadezimalen Hash-Darstellungen zu vermeiden, MÜSSEN sie auf die folgenden erlaubten Zeichen beschränkt sein

• Kleinbuchstaben des ASCII-Zeichensatzes ([a-z])
• ASCII-Ziffern ([0-9])
• Unterstriche (_)
• Bindestriche (-)
• Punkte (.)
• Pluszeichen (+)

Quellkennzeichnungen MÜSSEN mit einem ASCII-Buchstaben oder einer Ziffer beginnen und enden.

Ein regulärer Ausdruck zur Durchsetzung dieser Einschränkungen (wenn ausgeführt mit re.IGNORECASE) lautet

^([A-Z0-9]|[A-Z0-9][A-Z0-9._-+]*[A-Z0-9])$

Eine Quellkennzeichnung für ein Projekt darf keine definierten Versionen für dieses Projekt abgleichen. Diese Einschränkung stellt sicher, dass es keine Mehrdeutigkeit zwischen Versionskennungen und Quellkennzeichnungen gibt.

Beispiele

"source_label": "1.0.0-alpha.1"

"source_label": "1.3.7+build.11.e0f985a"

"source_label": "v1.8.1.301.ga0df26f"

"source_label": "2013.02.17.dev123"

Quellcode-URL

Eine Zeichenfolge, die eine vollständige URL enthält, von der die Quelle für diese spezifische Version der Distribution heruntergeladen werden kann.

Quell-URLs MÜSSEN innerhalb jedes Projekts eindeutig sein. Das bedeutet, dass die URL nicht etwas wie "https://github.com/pypa/pip/archive/main.zip" sein darf, sondern stattdessen "https://github.com/pypa/pip/archive/1.3.1.zip" sein muss.

Die Quell-URL MUSS entweder ein Quellarchiv oder ein Tag oder ein bestimmter Commit in einem Online-Versionskontrollsystem referenzieren, das die Erstellung eines geeigneten VCS-Checkouts ermöglicht. Dies ist in erster Linie für Integratoren gedacht, die die Distribution aus der ursprünglichen Quellform neu erstellen möchten.

Alle Quell-URL-Referenzen SOLLTEN einen sicheren Transportmechanismus (wie https) angeben UND einen erwarteten Hash-Wert in der URL zur Verifizierung enthalten. Wenn eine Quell-URL ohne Hash-Informationen, mit Hash-Informationen, die das Tool nicht versteht, oder mit einem ausgewählten Hash-Algorithmus, den das Tool als zu schwach zum Vertrauen einstuft, angegeben wird, SOLLTEN automatisierte Tools zumindest eine Warnung ausgeben und KÖNNEN sich weigern, sich auf die URL zu verlassen. Wenn eine solche Quell-URL auch einen unsicheren Transport verwendet, SOLLTEN automatisierte Tools sich nicht auf die URL verlassen.

Für Quellarchivreferenzen kann ein erwarteter Hash-Wert angegeben werden, indem ein Eintrag <hash-algorithm>=<expected-hash> als Teil des URL-Fragments enthalten ist.

Ab 2017 wird empfohlen, 'sha256'-Hashes für Quell-URLs zu verwenden, da dieser Hash noch nicht anfällig für die Erzeugung bösartiger Kollisionen ist und gleichzeitig auf Client-Systemen weit verbreitet ist.

Für Versionskontrollreferenzen SOLLTE das Schema VCS+protocol verwendet werden, um sowohl das Versionskontrollsystem als auch den sicheren Transport zu identifizieren, und ein Versionskontrollsystem mit hashbasierten Commit-Identifikatoren SOLLTE verwendet werden. Automatisierte Tools KÖNNEN Warnungen über fehlende Hashes für Versionskontrollsysteme auslassen, die keine hashbasierten Commit-Identifikatoren bereitstellen.

Um Versionskontrollsysteme zu handhaben, die keine Commit- oder Tag-Referenzen direkt in der URL unterstützen, können diese Informationen am Ende der URL mit der Notation @<commit-hash> oder @<tag>#<commit-hash> angehängt werden.

Beispiel

"source_url": "https://github.com/pypa/pip/archive/1.3.1.zip#sha256=2dc6b5a470a1bde68946f263f1af1515a2574a150a30d6ce02c6ff742fcc0db8
"source_url": "git+https://github.com/pypa/pip.git@1.3.1#7921be1537eac1e97bc40179a57f0349c2aee67d"
"source_url": "git+https://github.com/pypa/pip.git@7921be1537eac1e97bc40179a57f0349c2aee67d"

Zuordnung von Abhängigkeiten zu Entwicklungs- und Distributionsaktivitäten

Die verschiedenen Kategorien von Abhängigkeiten basieren auf den verschiedenen oben identifizierten Distributions- und Entwicklungsaktivitäten und bestimmen, welche Abhängigkeiten für die angegebenen Aktivitäten installiert werden sollten

• Erforderliche Laufzeitabhängigkeiten
  • bedingungslose Abhängigkeiten
• Erforderliche Build-Abhängigkeiten
  • das build-Extra
  • das dev-Extra
  • Wenn die Testsuite der Distribution als Teil des Build-Prozesses ausgeführt wird, installieren Sie auch die bedingungslosen Abhängigkeiten und das test-Extra
• Erforderliche Entwicklungs- und Publikationsabhängigkeiten
  • bedingungslose Abhängigkeiten
  • das test-Extra
  • das build-Extra
  • das doc-Extra
  • das dev-Extra

Die in Extras (optionale Abhängigkeiten) beschriebene Notation SOLLTE verwendet werden, um genau zu bestimmen, was für verschiedene Operationen installiert wird.

Installationstools SOLLTEN einen Fehler melden, wenn Abhängigkeiten nicht erfüllt werden können, MÜSSEN zumindest eine Warnung ausgeben und KÖNNEN dem Benutzer erlauben, die Installation trotzdem zu erzwingen.

Siehe Anhang B für einen Überblick über die Zuordnung dieser Abhängigkeiten zu einer RPM-Spec-Datei.

Extras

Eine Liste optionaler Abhängigkeitssätze, die zur Definition bedingter Abhängigkeiten in Abhängigkeitsfeldern verwendet werden können. Siehe Extras (optionale Abhängigkeiten) für Details.

Die Namen von Extras MÜSSEN denselben Einschränkungen unterliegen wie Distributionsnamen.

Die folgenden Extra-Namen sind standardmäßig verfügbar und DÜRFEN nicht explizit in diesem Feld deklariert werden

• all
• alldev
• build
• dev
• doc
• test

Beispiel

"extras": ["warmup", "tea"]

Abhängigkeiten

Eine Liste von Release-Anforderungen, die benötigt werden, um diese Release tatsächlich auszuführen.

Öffentliche Indexserver KÖNNEN strenge Versionsabgleichsklauseln oder direkte Referenzen in diesem Feld verbieten.

Beispiel

"dependencies":
  {
    "requires": ["SciPy", "PasteDeploy", "zope.interface > 3.5.0"]
  },
  {
    "requires": ["pywin32 > 1.0"],
    "environment": "sys_platform == 'win32'"
  },
  {
    "requires": ["SoftCushions"],
    "extra": "warmup"
  }
]

Obwohl viele Abhängigkeiten benötigt werden, um eine Projekt-Release überhaupt zu nutzen, sind andere nur auf bestimmten Plattformen oder nur dann erforderlich, wenn bestimmte optionale Features der Release benötigt werden.

Um dies zu handhaben, sind Release-Abhängigkeitsspezifizierer Zuordnungen mit den folgenden Unterfeldern

• requires: eine Liste von Anforderungen, die zur Erfüllung der Abhängigkeit benötigt werden
• extra: der Name einer Gruppe optionaler Abhängigkeiten, die angefordert und zusammen installiert werden. Siehe Extras (optionale Abhängigkeiten) für Details
• environment: eine Umgebungsmarkierung, die die Umgebung definiert, die diese Abhängigkeiten benötigt. Die Syntax und Fähigkeiten von Umgebungsmarkierungen sind in PEP 508 definiert.

Einzelne Einträge in den requires-Listen sind Zeichenfolgen, die das in PEP 508 definierte Abhängigkeitsdeklarationsformat verwenden, mit der Ausnahme, dass keine Umgebungsmarkierungen in den einzelnen Abhängigkeitsdeklarationen enthalten sein dürfen und stattdessen im separaten Feld environment bereitgestellt werden.

requires ist das einzige erforderliche Unterfeld. Wenn es das einzige Unterfeld ist, werden die Abhängigkeiten als *bedingt* bezeichnet. Wenn extra oder environment angegeben ist, sind die Abhängigkeiten *bedingt*.

Alle drei Felder können angegeben werden, was bedeutet, dass die Abhängigkeiten nur benötigt werden, wenn das benannte Extra in einer bestimmten Umgebung angefordert wird.

Automatisierte Tools MÜSSEN verwandte Abhängigkeitsspezifizierer (die mit gemeinsamen Werten für extra und environment) zu einem einzigen Spezifizierer kombinieren, der mehrere Anforderungen auflistet, wenn Metadaten serialisiert werden.

Trotz dieser erforderlichen Normalisierung KANN derselbe Extra-Name oder dieselbe Umgebungsmarkierung in mehreren bedingten Abhängigkeiten erscheinen. Dies kann beispielsweise der Fall sein, wenn ein Extra selbst nur einige seiner Abhängigkeiten in bestimmten Umgebungen benötigt. Nur die Kombination von Extras und Umgebungsmarkierungen muss in einer Liste von Abhängigkeitsspezifizierern eindeutig sein.

Abgesehen von den sechs Standard-Extra-Kategorien müssen alle von einem Abhängigkeitsspezifizierer referenzierten Extras im Feld Extras für diese Distribution benannt werden. Dies hilft, Tippfehler zu vermeiden und macht es auch einfach, die verfügbaren Extras zu identifizieren, ohne die vollständige Menge der Abhängigkeiten durchsuchen zu müssen.

Um eine Extra-Definition als Teil eines anderen Extras wiederzuverwenden, KÖNNEN Projekt-Releases Abhängigkeiten von sich selbst deklarieren. Um in diesen Fällen eine Endlosschleife zu vermeiden, MÜSSEN automatisierte Tools Abhängigkeiten eines Projekts auf sich selbst speziell behandeln.

Erweiterungsversionierung

Erweiterungen MÜSSEN versioniert sein, unter Verwendung des Schlüssels extension_version. Wenn dieser Schlüssel jedoch weggelassen wird, ist die implizite Version 1.0.

Automatisierte Tools, die Erweiterungsmetadaten verbrauchen, SOLLTEN eine Warnung ausgeben, wenn extension_version höher ist als die höchste von ihnen unterstützte Version, und MÜSSEN fehlschlagen, wenn extension_version eine höhere Hauptversion hat als die höchste von ihnen unterstützte Version (wie in PEP 440 beschrieben, ist die Hauptversion der Wert vor dem ersten Punkt).

Für breitere Kompatibilität KÖNNEN Build-Tools wählen, Erweiterungsmetadaten unter Verwendung der niedrigsten Metadatenversion zu produzieren, die alle benötigten Felder enthält.

Behandlung erforderlicher Erweiterungen

Ein Projekt kann die korrekte Handhabung einiger Erweiterungen als wesentlich für die korrekte Installation der Software betrachten. Dies wird angezeigt, indem das Feld installer_must_handle auf true gesetzt wird. Das Setzen auf false oder das Weglassen ganz bedeutet, dass die Verarbeitung der Erweiterung bei der Installation der Distribution von den Entwicklern nicht als zwingend angesehen wird.

Installationstools MÜSSEN fehlschlagen, wenn installer_must_handle für eine Erweiterung auf true gesetzt ist und das Tool keine Fähigkeit hat, diese spezielle Erweiterung zu verarbeiten (entweder direkt oder über ein Tool-spezifisches Plugin-System).

Wenn ein Installationstool auf eine erforderliche Erweiterung stößt, die es nicht versteht, wenn es versucht, aus einem Wheel-Archiv zu installieren, KANN es versuchen, aus dem Quellcode zu installieren, anstatt vollständig fehzuschlagen.

Semantik der Metadatenversion

Die Semantik von Haupt- und Nebenversionsinkrementen ist nun spezifiziert und folgt demselben Modell wie die Semantik der Formatversionen, die für das Wheel-Format in PEP 427 spezifiziert sind: Nebenversionsinkremente müssen sich vernünftig verhalten, wenn sie von einem Tool verarbeitet werden, das nur frühere Metadatenversionen mit derselben Hauptversion versteht, während Hauptversionsinkremente Änderungen enthalten können, die mit bestehenden Tools nicht kompatibel sind.

Die Hauptversionsnummer der Spezifikation wurde entsprechend erhöht, da die Interpretation der Metadaten von PEP 426 offensichtlich nicht gemäß früheren Metadatenspezifikationen interpretiert werden kann.

Immer wenn die Hauptversionsnummer der Spezifikation erhöht wird, wird erwartet, dass die Bereitstellung einige Zeit dauern wird, da entweder die Metadaten verbrauchenden Tools aktualisiert werden müssen, bevor andere Tools sicher mit der Produktion des neuen Formats beginnen können, oder die sdist- und Wheel-Formate zusammen mit der Definition der Installationsdatenbank aktualisiert werden müssen, um die Bereitstellung mehrerer Versionen der Metadaten parallel zu unterstützen.

Bestehende Tools werden dieser Richtlinie erst folgen, wenn sie zur Unterstützung des neuen Metadatenstandards aktualisiert wurden, sodass die neuen Semantiken erstmals für einen hypothetischen Übergang von 2.x zu 3.0 wirksam werden. Für den Übergang von 1.x zu 2.x werden wir den Ansatz verwenden, bei dem Tools die bestehenden ergänzenden Dateien (wie z. B. entry_points.txt) zusätzlich zu allen Äquivalenten, die unter Verwendung der neuen Features des Standardmetadatenformats (einschließlich des formalen Erweiterungsmechanismus) spezifiziert wurden, weiterhin produzieren.

Umstellung auf ein JSON-kompatibles Format

Das alte "Schlüssel:Wert"-Format wurde immer einschränkender, mit verschiedenen Komplexitäten wie Parsern, die wissen mussten, welche Felder mehrmals vorkommen durften, welche Felder die Umgebungsmarkierungssyntax unterstützten (mit einem optionalen ";" zur Trennung des Werts von der Markierung) und schließlich sogar die Option, beliebiges JSON in bestimmte Unterfelder einzubetten.

Das alte Serialisierungsformat war auch nicht für eine einfache Konvertierung in Standard-Python-Datenstrukturen für die Verwendung in neuen Install-Hook-APIs oder in zukünftigen Erweiterungen der Runtime-Importer-APIs zur Bereitstellung von Informationen für die Aufnahme in die Installationsdatenbank geeignet.

Daher haben wir den Schritt unternommen, zu einem JSON-kompatiblen Metadatenformat zu wechseln. Dies funktioniert besser für APIs und ist für Tools wesentlich einfacher, korrekt zu parsen und zu generieren. Die Änderung des Namens der Metadatendatei erleichtert auch die parallele Verteilung von 1.x- und 2.x-Metadaten, was mehrere Aspekte der Migration zum neuen Metadatenformat erheblich vereinfacht.

Die spezifische Wahl von pydist.json als bevorzugter Dateiname bezieht sich auf die Tatsache, dass die in diesen Dateien beschriebenen Metadaten für die Distribution als Ganzes gelten und nicht für einen bestimmten Build. Zukünftig können zusätzliche Metadatenformate definiert werden, um Informationen zu speichern, die erst nach dem Erstellen einer Binärdistribution für eine bestimmte Zielumgebung ermittelt werden können.

Änderung des Versionsschemas

Siehe PEP 440 für eine detaillierte Begründung der verschiedenen Änderungen am Versionierungsschema.

Quellcode-Labels

Die neue Unterstützung für Quellkennzeichnungen soll verdeutlichen, dass die Einschränkungen für öffentliche Versionsbezeichner in erster Linie dazu dienen, die Erstellung zuverlässiger automatisierter Abhängigkeitsanalysewerkzeuge zu unterstützen. Projekte können intern beliebige Versionierungsschemata verwenden, solange sie in der Lage sind, diese in etwas zu übersetzen, das die Abhängigkeitsanalysewerkzeuge verstehen.

Quellkennzeichnungen erleichtern auch die Aufzeichnung spezifischer Details einer Version, wie z. B. eines Hash- oder Tag-Namens, der die Rekonstruktion des Releases aus dem Projektversionskontrollsystem ermöglicht.

Unterstützung für optionale Abhängigkeiten für Distributionen

Das neue Extrasystem ermöglicht es Distributionen, optionales Verhalten zu deklarieren und die Abhängigkeitsfelder zu verwenden, um anzuzeigen, wann bestimmte Abhängigkeiten nur zur Unterstützung dieses Verhaltens benötigt werden. Es leitet sich vom äquivalenten System ab, das bereits als Teil von setuptools weit verbreitet ist, und ermöglicht es, diesen Aspekt der Legacy- setuptools-Metadaten im neuen Metadatenformat genau darzustellen.

Die Erweiterungen der Extrasyntax im Vergleich zu setuptools sind darauf ausgelegt, die verschiedenen möglichen Kombinationen von Abhängigkeiten einfacher auszudrücken, insbesondere diejenigen, die mit Build-Systemen (mit optionaler Unterstützung für die Ausführung der Testsuite) und Entwicklungssystemen verbunden sind.

Unterstützung für verschiedene Arten von semantischen Abhängigkeiten

Die Trennung der fünf verschiedenen Arten von Abhängigkeiten durch das Extrasystem ermöglicht es einem Projekt, optional anzugeben, ob eine Abhängigkeit speziell zur Entwicklung, zum Bauen, Testen oder zur Nutzung der Distribution benötigt wird.

Der Vorteil der Unterstützung dieser Unterscheidungen in den Upstream-Python-spezifischen Metadaten besteht darin, dass Projekte, auch wenn sie sich selbst nicht um diese Unterscheidungen kümmern, empfänglicher für Patches von nachgelagerten Redistributoren sein könnten, die die Felder entsprechend trennen. Im Laufe der Zeit sollte dies eine wesentlich größere Kontrolle darüber ermöglichen, wo und wann bestimmte Abhängigkeiten installiert werden.

Unterstützung für Metadatenerweiterungen

Das neue Erweiterungssystem ermöglicht es effektiv, Abschnitte des Metadaten-Namespace an andere Projekte zu delegieren, während ein standardmäßiges Gesamtformat für Metadaten beibehalten wird, um die Verarbeitung durch Distributionswerkzeuge zu erleichtern, die eine bestimmte Erweiterung nicht unterstützen.

Es funktioniert auch gut in Kombination mit dem neuen build-Extra, um einer Distribution zu ermöglichen, sich auf Tools zu verlassen, die wissen, wie sie mit der gewählten Erweiterung umgehen sollen, und dem neuen Extrasystem im Allgemeinen, um die Unterstützung für bestimmte Erweiterungen als optionale Features bereitzustellen.

Mögliche zukünftige Verwendungen für Erweiterungen umfassen die Deklaration von Plugins für andere Projekte und Hinweise für die automatische Konvertierung in Linux-Systempakete.

Die Möglichkeit, eine Erweiterung als erforderlich zu deklarieren, ist hauptsächlich dazu gedacht, die Definition der Metadaten-Hooks-Erweiterung bis zu einem Zeitpunkt nach der anfänglichen Einführung der Metadaten 2.0-Spezifikation zu verschieben. Wenn eine Release einen postinstall-Hook benötigt, um die Installation erfolgreich abzuschließen, dann sollten frühere Versionen von Tools auf die Installation aus dem Quellcode zurückgreifen, anstatt aus einer Wheel-Datei zu installieren und dann den erwarteten Postinstall-Hook nicht ausführen zu können.

Standarderweiterungen

Einige der vom Legacy-Metadaten-System bereitgestellten Informationen wurden in Standarderweiterungen verschoben, die in PEP 459 definiert sind.

Dies ermöglicht die Veröffentlichung der Kern-Abhängigkeitsmetadaten in einem leichter verständlichen Format, noch bevor die vollständigen Details dieser Erweiterungen geklärt sind.

Verbesserte Handhabung von Projektobsoleszenz, Umbenennungen und Fusionen

Frühere Entwürfe dieser PEP enthielten neue Felder Provides und Obsoleted-By für robustere automatisierte Benachrichtigungen und Verfolgung von Projektobsoleszenz, Umbenennungen und Fusionen.

Dies ist keine wesentliche Funktion eines Abhängigkeitsmanagementsystems und wurde auf unbestimmte Zeit als mögliche zukünftige Metadaten-Erweiterung verschoben.

MIME-Typ-Registrierung

Zu einem späteren Zeitpunkt nach der Annahme der PEP könnten wir die folgende MIME-Typ-Registrierungsanforderung bei IANA einreichen

• application/vnd.python.pydist+json

Es ist sogar möglich, dass wir einfach den Namensraum vnd.python unter der Schirmherrschaft der PSF registrieren können, anstatt die einzelnen Unterformate registrieren zu müssen.

String-Methoden in Umgebungsmarkern

Die Unterstützung von mindestens den String-Methoden ".startswith" und ".endswith" in Umgebungsmarkierungen würde es ermöglichen, einige Bedingungen natürlicher zu formulieren. Zum Beispiel ist "sys.platform.startswith('win')" eine etwas intuitivere Art, Windows-spezifische Abhängigkeiten zu markieren, da "'win' in sys.platform" aufgrund von cygwin falsch ist und die Tatsache, dass 64-Bit-Windows immer noch als win32 angezeigt wird, mehr als ein wenig seltsam ist.

Separate Listen für bedingte und unbedingte Abhängigkeiten

Frühere Versionen dieser PEP verwendeten getrennte Listen für bedingte und bedingungslose Abhängigkeiten. Dies erwies sich als umständlich für die Handhabung in automatisierten Tools und durch seine Entfernung wurde auch die PEP und das Metadatenschema erheblich verkürzt, was darauf hindeutet, dass es tatsächlich schwieriger zu erklären war.

Separate Listen für semantische Abhängigkeiten

Frühere Versionen dieser PEP verwendeten separate Felder anstelle des Extrasystems für Test-, Build-, Dokumentations- und Entwicklungsabhängigkeiten. Dies erwies sich als umständlich für die Handhabung in automatisierten Tools und durch seine Entfernung wurde auch die PEP und das Metadatenschema erheblich verkürzt, was darauf hindeutet, dass es tatsächlich schwieriger zu erklären war.

Einführung von Reibung für übermäßig präzise Abhängigkeitserklärungen

Frühere Versionen dieses PEP versuchten, unangemessene Verwendungen von übermäßig strengen Abhängigkeitsdeklarationen in veröffentlichten Releases zu erschweren. Die Diskussion auf distutils-sig kam zu dem Schluss, dass dies kein ausreichend ernstes Problem war, um es direkt auf der Ebene der Interoperabilitätsspezifikation anzugehen, und wenn es in Zukunft zu einem Problem wird, wäre es besser, es an dem Punkt anzugehen, an dem Projekte auf dem öffentlichen Python Package Index hochgeladen werden.

Untersagen von Unterstrichen in Distributionsnamen

Debian erlaubt eigentlich keine Unterstriche in Namen, aber das scheint für diese Spezifikation angesichts der üblichen Praxis, gültige Python-Bezeichner als Python-Distributionsnamen zu verwenden, übermäßig einschränkend zu sein. Eine Debian-Richtlinie zur Umwandlung von Unterstrichen in Bindestriche scheint einfach genug zu implementieren (und die Anforderung, Bindestriche und Unterstriche als gleichwertig zu betrachten, stellt sicher, dass dies keine Namenskonflikte einführt).

Zulassen der Verwendung von Unicode in Distributionsnamen

Dieser PEP vermeidet bewusst, Python 3 auf dem Weg zu beliebigen Unicode-Bezeichnern zu folgen, da die Sicherheitsimplikationen dafür im Anwendungsfall der Softwareverteilung wesentlich schlimmer sind (er eröffnet weit interessantere Angriffsvektoren als bloße Code-Obfuskation).

Darüber hinaus funktionieren die vorhandenen Tools wirklich nur richtig, wenn Sie Namen auf ASCII beschränken, und eine Änderung würde **viel** Arbeit für alle automatisierten Tools in der Kette erfordern.

Es mag vernünftig sein, diese Frage zu einem (fernen) zukünftigen Zeitpunkt erneut zu prüfen, aber die Einrichtung eines zuverlässigeren Systems zur Softwareverteilung ist bereits schwierig genug, ohne dass noch eine allgemeinere Unterstützung für Unicode-Bezeichner hinzugefügt wird.

Abhängen von Quellcode-Labels

Es gibt keinen Mechanismus, um eine Abhängigkeit von einem Quell-Label auszudrücken – sie sind nur für die interne Projektreferenz im Metadaten enthalten. Stattdessen müssen Abhängigkeiten entweder in Form von öffentlichen Versionen oder direkten URL-Referenzen ausgedrückt werden.

Alternative Abhängigkeiten

Ein früherer Entwurf dieses PEP erwog, Listen anstelle der üblichen Zeichenketten in Abhängigkeitsspezifikationen zuzulassen, um anzuzeigen, dass es mehrere Möglichkeiten gibt, eine Abhängigkeit zu erfüllen.

Wenn mindestens eine der einzelnen Abhängigkeiten bereits verfügbar war, würde die gesamte Abhängigkeit als erfüllt betrachtet, andernfalls würde der erste Eintrag zur Abhängigkeitsmenge hinzugefügt.

Beispiel für alternative Abhängigkeitsspezifikation

["Pillow", "PIL"]
["mysql", "psycopg2 >= 4", "sqlite3"]

Keines der gegebenen Beispiele ist besonders überzeugend, da Gabelungen im Pillow/PIL-Stil nicht üblich sind und der Anwendungsfall für Datenbanktreiber wohl besser durch eine von SQL Alchemy definierte "unterstützte Datenbanktreiber"-Metadatenerweiterung bedient würde, bei der ein Projekt von SQL Alchemy abhängt und dann in der Erweiterung deklariert, welche Datenbanktreiber vom Upstream-Projekt auf Kompatibilität geprüft werden.

Kompatible Release-Vergleiche in Umgebungsmarkern

PEP 440 definiert eine reichhaltige Syntax für Versionsvergleiche, die potenziell nützlich sein könnte mit python_version und python_full_version in Umgebungskennzeichnungen. Die vollständige Syntax zuzulassen würde jedoch bedeuten, dass Umgebungskennzeichnungen keine Python-Teilmengen mehr sind, während nur einige der Vergleiche zugelassen würden, was noch einen weiteren Sonderfall zum Behandeln einführt.

Da Umgebungskennzeichnungen nur in Fällen verwendet werden, in denen durch die Metadatenstruktur ein höheres "oder" impliziert wird, erscheint es einfacher, die Verwendung mehrerer Vergleiche mit spezifischen Python-Versionen für die seltenen Fälle zu verlangen, in denen dies nützlich wäre.

Bedingte Bereitstellungen

Unter dem überarbeiteten Metadatendesign würden bedingte "provides" basierend auf Laufzeitfunktionen oder der Umgebung in ein separates "may_provide"-Feld verschoben werden. Es ist jedoch nicht klar, ob es dafür irgendeinen Anwendungsfall gibt, daher wird die Idee abgelehnt, es sei denn, jemand kann einen überzeugenden Anwendungsfall vorlegen (und selbst dann wird die Idee frühestens bei Metadaten 2.1 wieder in Betracht gezogen).