Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python Enhancement Proposals

PEP 503 – Einfache Repository-API

Autor:
Donald Stufft <donald at stufft.io>
BDFL-Delegate:
Donald Stufft <donald at stufft.io>
Discussions-To:
Distutils-SIG Liste
Status:
Final
Typ:
Standards Track
Thema:
Packaging
Erstellt:
04-Sep-2015
Post-History:
04-Sep-2015
Resolution:
Distutils-SIG Nachricht
Inhaltsverzeichnis

Wichtig

Dieses PEP ist ein historisches Dokument. Die aktuelle, kanonische Spezifikation, Simple Repository API, wird auf der PyPA Specs-Seite gepflegt.

×

Siehe den PyPA-Spezifikations-Update-Prozess, um Änderungen vorzuschlagen.

Zusammenfassung

Es gibt viele Implementierungen einer Python-Paket-Repositorys und viele Werkzeuge, die sie verbrauchen. Von diesen ist die kanonische Implementierung, die festlegt, wie die „einfache“ Repository-API aussieht, die Implementierung, die PyPI antreibt. Dieses Dokument wird diese API spezifizieren und das korrekte Verhalten für jede Implementierung der einfachen Repository-API dokumentieren.

Spezifikation

Ein Repository, das die einfache API implementiert, wird durch seine Basis-URL definiert. Dies ist die oberste URL, unterhalb derer sich alle zusätzlichen URLs befinden. Die API wird als „einfache“ Repository-API bezeichnet, da die Basis-URL von PyPI lautet: https://pypi.org/simple/.

Hinweis

Alle nachfolgenden URLs in diesem Dokument sind relativ zu dieser Basis-URL (also bei PyPIs URL wäre eine URL von /foo/ https://pypi.org/simple/foo/).

Innerhalb eines Repositorys **MUSS** die Root-URL (/ für diese PEP, die die Basis-URL repräsentiert) eine gültige HTML5-Seite mit einem einzigen Anker-Element pro Projekt im Repository sein. Der Text des Anker-Tags **MUSS** der Name des Projekts sein und das href-Attribut **MUSS** auf die URL dieses bestimmten Projekts verlinken. Als Beispiel

<!DOCTYPE html>
<html>
  <body>
    <a href="/frob/">frob</a>
    <a href="/spamspamspam/">spamspamspam</a>
  </body>
</html>

Unterhalb der Root-URL befindet sich eine weitere URL für jedes einzelne Projekt, das in einem Repository enthalten ist. Das Format dieser URL ist /<projekt>/, wobei das <projekt> durch den normalisierten Namen dieses Projekts ersetzt wird, so hätte ein Projekt namens „HolyGrail“ eine URL wie /holygrail/. Diese URL muss mit einer gültigen HTML5-Seite mit einem einzigen Anker-Element pro Datei für das Projekt beantwortet werden. Das href-Attribut **MUSS** eine URL sein, die auf den Speicherort der Datei zum Download verlinkt, und der Text des Anker-Tags **MUSS** mit der letzten Komponente des Pfades (dem Dateinamen) der URL übereinstimmen. Die URL **SOLLTE** einen Hash in Form eines URL-Fragments mit der folgenden Syntax enthalten: #<hashname>=<hashvalue>, wobei <hashname> der kleingeschriebene Name der Hash-Funktion ist (wie z. B. sha256) und <hashvalue> der hexadezimal kodierte Digest ist.

Zusätzlich zu den oben genannten Punkten werden die folgenden Einschränkungen für die API festgelegt:

  • Alle URLs, die mit einer HTML5-Seite beantwortet werden, **MÜSSEN** mit einem / enden, und das Repository **SOLLTE** URLs ohne ein / umleiten, um ein / am Ende hinzuzufügen.
  • URLs können entweder absolut oder relativ sein, solange sie auf den richtigen Speicherort zeigen.
  • Es gibt keine Einschränkungen, wo die Dateien relativ zum Repository gehostet werden müssen.
  • Es dürfen beliebige andere HTML-Elemente auf den API-Seiten vorhanden sein, solange die erforderlichen Anker-Elemente existieren.
  • Repositories **KÖNNEN** nicht normalisierte URLs auf die kanonische normalisierte URL umleiten (z. B. kann /Foobar/ auf /foobar/ umgeleitet werden), jedoch **DÜRFEN** Clients sich nicht auf diese Umleitung verlassen und **MÜSSEN** die normalisierte URL anfordern.
  • **SOLLTEN** Repositories eine Hash-Funktion aus einer derjenigen auswählen, die über das Modul hashlib in der Python-Standardbibliothek garantiert verfügbar sind (derzeit md5, sha1, sha224, sha256, sha384, sha512). Die aktuelle Empfehlung ist die Verwendung von sha256.
  • Wenn eine GPG-Signatur für eine bestimmte Distributionsdatei vorhanden ist, **MUSS** sie neben dieser Datei unter demselben Namen mit angehängtem .asc liegen. Wenn also die Datei /packages/HolyGrail-1.0.tar.gz existierte und eine zugehörige Signatur hatte, würde die Signatur unter /packages/HolyGrail-1.0.tar.gz.asc liegen.
  • Ein Repository **KANN** ein Attribut data-gpg-sig auf einem Dateilink mit dem Wert true oder false enthalten, um anzuzeigen, ob eine GPG-Signatur vorhanden ist oder nicht. Repositories, die dies tun, **SOLLTEN** es auf jedem Link einschließen.
  • Ein Repository **KANN** ein Attribut data-requires-python auf einem Dateilink enthalten. Dies gibt das Metadatenfeld *Requires-Python* preis, das in PEP 345 spezifiziert ist, für die entsprechende Veröffentlichung. Wo dies vorhanden ist, **SOLLTEN** Installer-Tools den Download ignorieren, wenn sie für eine Python-Version installieren, die die Anforderung nicht erfüllt. Zum Beispiel
    <a href="..." data-requires-python="&gt;=3">...</a>

    Im Attributwert müssen < und > als &lt; und &gt; HTML-kodiert sein.

Normalisierte Namen

Diese PEP bezieht sich auf das Konzept eines „normalisierten“ Projektnamens. Gemäß PEP 426 sind die einzigen gültigen Zeichen in einem Namen das ASCII-Alphabet, ASCII-Zahlen, ., - und _. Der Name sollte kleingeschrieben werden, wobei alle aufeinanderfolgenden Zeichen ., - oder _ durch ein einzelnes - Zeichen ersetzt werden. Dies kann in Python mit dem Modul re implementiert werden.

import re

def normalize(name):
    return re.sub(r"[-_.]+", "-", name).lower()

Änderungen

  • Das optionale Attribut data-requires-python wurde im Juli 2016 hinzugefügt.

Quelle: https://github.com/python/peps/blob/main/peps/pep-0503.rst

Zuletzt geändert: 2025-08-20 21:30:45 GMT