Metadaten-Produzenten

Diese PEP legt Folgendes für Metadaten-Produzenten fest:

• Bei der Generierung von Metadaten ab Version 1.2 SOLLTEN Produzenten nur Project-URL ausgeben und NICHT die Felder Home-page oder Download-URL ausgeben.

Diese Festlegungen ändern nichts an der Optionalität von URL-Feldern in den Kernmetadaten. Mit anderen Worten: Produzenten KÖNNEN nach eigenem Ermessen Project-URL ganz weglassen.

Diese PEP schlägt nicht die vollständige Entfernung der Unterstützung für Home-page oder Download-URL vor. Siehe jedoch Zukünftige Überlegungen für Gedanken, wie eine neue (noch nicht spezifizierte) Hauptversion der Kernmetadaten den Veraltungszyklus durch Entfernung dieser veralteten Felder abschließen könnte.

Ebenso schlägt diese PEP nicht vor, dass Metadaten-Produzenten normalisierte Labels ausgeben. Die Label-Normalisierung erfolgt ausschließlich auf der Verarbeitungs- und Konsumseite (d. h. innerhalb von Indizes und anderen Konsumenten von Distributionsmetadaten).

Paketindizes

Diese PEP legt Folgendes für Paketindizes fest:

• Bei der Interpretation von Metadaten einer Distribution ab Version 1.2 (z. B. zur Anzeige auf einer Webseite) MUSS der Index die Project-URL-Felder als Quelle für URLs bevorzugen gegenüber Home-page und Download-URL, auch wenn letztere explizit angegeben sind.
• Wenn die Metadaten einer Distribution nur die Felder Home-page und Download-URL enthalten, KANN der Index wählen, diese Felder zu ignorieren und sich so zu verhalten, als wären keine URLs in den Metadaten vorhanden. In diesem Fall SOLLTE der Index eine entsprechende Warnung oder Benachrichtigung an die hochladende Partei ausgeben.
  • Der Mechanismus zur Anzeige dieser Warnung oder Benachrichtigung ist nicht spezifiziert, da er je nach Index variieren wird. Als Beispiel kann ein Index wählen, eine Warnung in der HTTP-Antwort auf eine Upload-Anfrage auszugeben oder eine E-Mail oder eine andere Benachrichtigung an die Betreuer des Projekts zu senden.
• Wenn die Metadaten einer Distribution beide Feldersätze enthalten, KANN der Index wählen, die Distribution sofort zurückzuweisen. Dies wird jedoch NICHT EMPFOHLEN, bis eine zukünftige, nicht spezifizierte Hauptversion der Metadaten die Unterstützung für Home-page und Download-URL formell entfernt.
• Änderungen an der Interpretation von Metadaten ab Version 1.2, die dazu führen, dass zuvor erkannte URLs nicht mehr erkannt werden, SOLLTEN NICHT retroaktiv auf zuvor hochgeladene Pakete angewendet werden.

Diese Festlegungen ändern nichts an der Optionalität der URL-Verarbeitung durch Indizes. Mit anderen Worten: Ein Index, der keine URLs in hochgeladenen Distributionen verarbeitet, kann weiterhin alle URL-Felder vollständig ignorieren.

Ebenso implizieren diese Festlegungen nicht, dass der Index jegliche Normalisierungen, die er durchführt, in den Metadaten einer Distribution oder deren "Sidecar" PEP 658-Metadatendatei beibehalten sollte. Mit anderen Worten: Diese PEP schreibt Label-Normalisierung zum Zweck der Benutzerpräsentation vor, nicht zum Zweck der Änderung einer hochgeladenen Distribution oder ihrer "Sidecar" PEP 658-Metadatendatei.

Label-Normalisierung

Die Kernmetadaten-Spezifikation besagt, dass Project-URL-Labels Freitext sind und auf 32 Zeichen begrenzt sind.

Diese PEP schlägt vor, das Konzept eines „normalisierten“ Labels in die Kernmetadaten-Spezifikation aufzunehmen. Die Label-Normalisierung ist über die folgende Python-Funktion definiert:

import string
def normalize_label(label: str) -> str:
    chars_to_remove = string.punctuation + string.whitespace
    removal_map = str.maketrans("", "", chars_to_remove)
    return label.translate(removal_map).lower()

In einfacher Sprache ausgedrückt: Ein Label wird normalisiert, indem alle ASCII-Satzzeichen und Leerzeichen gelöscht und das Ergebnis dann in Kleinbuchstaben umgewandelt wird.

Die folgende Tabelle zeigt Beispiele für Labels vor (roh) und nach der Normalisierung:

Bei der Verarbeitung von Distributionsmetadaten SOLLTEN Paketindizes eine Label-Normalisierung durchführen, um festzustellen, ob ein gegebenes Label für eine nachfolgende spezielle Verarbeitung bekannt ist. Labels, die nicht bekannt sind, MÜSSEN in ihrer unnormalisierten Form verarbeitet werden.

Die Normalisierung ändert nichts an den bestehenden Semantiken bezüglich duplizierter Project-URL-Labels. Mit anderen Worten: Die Normalisierung kann zu doppelten Labels in den Metadaten des Projekts führen, aber nur auf die gleiche Weise, die bereits zulässig war (da die Kernmetadatenspezifikation nicht vorschreibt, dass Labels eindeutig sind).

Auszugsweise Beispiele für normalisierte Metadatenfelder sind in Anhang A angegeben.

Bekannte Labels

Zusätzlich zu den oben genannten Normalisierungsregeln schlägt diese PEP einen festen (aber erweiterbaren) Satz von „bekannten“ Project-URL-Labels sowie Aliase und menschenlesbare Entsprechungen vor.

Die folgende Tabelle listet diese Labels in normalisierter Form auf:

Indizes KÖNNEN nach Wahl die oben vorgeschlagenen menschenlesbaren Entsprechungen in ihren UI-Elementen verwenden, falls zutreffend. Alternativ KÖNNEN Indizes ihre eigenen geeigneten menschenlesbaren Entsprechungen für UI-Elemente wählen.

Packer und Metadaten-Produzenten KÖNNEN wählen, jedes Label zu verwenden, das zu diesen Labels (oder ihren Aliassen) normalisiert wird, um spezifische URL-Intentionen an Paketindizes und nachgelagerte Systeme zu kommunizieren.

Ebenso KÖNNEN Indizes wählen, ihre Darstellung oder Präsentation von URLs mit diesen Labels zu spezialisieren, z. B. durch die Anzeige eines entsprechenden Symbols oder Tooltips für jedes Label.

Indizes KÖNNEN auch die Darstellung oder Präsentation von zusätzlichen Labels oder URLs spezialisieren, einschließlich (aber nicht beschränkt auf) Labels, die mit einem bekannten Label beginnen, und URLs, die auf einen bekannten Dienstanbieter-Domain verweisen (z. B. für die Dokumentations-Hosting oder Fehlerverfolgung).

Diese PEP erkennt an, dass die Liste der bekannten Labels wahrscheinlich nicht statisch bleiben wird und dass nachfolgende Ergänzungen dazu nicht den Overhead eines formellen PEP-Prozesses oder einer neuen Metadatenversion erfordern sollten. Daher schlägt diese PEP vor, dass die obige Liste eine „lebende“ Liste innerhalb der PyPA-Spezifikationen wird.

Begrenzte Auswirkungen

Diese PEP wird voraussichtlich wenig bis gar keine Auswirkungen auf bestehende Packaging-Tools oder Paketindizes haben

• Packaging-Tools: Keine Änderungen an der Korrektheit oder Formvollendung der Kernmetadaten. Diese PEP schlägt Veraltungen sowie Verhaltensverfeinerungen vor, aber alle derzeit (und historisch) produzierten Metadaten werden weiterhin gemäß den Regeln ihrer jeweiligen Version gültig sein.
• Paketindizes: Indizes werden weiterhin gut geformte Kernmetadaten erwarten, ohne Verhaltensänderungen. Indizes KÖNNEN wählen, Warnungen oder Benachrichtigungen bei Vorhandensein von nunmehr veralteten Feldern auszugeben, gemäß oben.