Eine Veröffentlichungssitzung erstellen

Ein Release beginnt mit der Erstellung einer neuen Veröffentlichungssitzung. Um die Sitzung zu erstellen, übermittelt ein Client eine POST-Anfrage an die Stamm-URL, wie z. B.:

{
  "meta": {
    "api-version": "2.0"
  },
  "name": "foo",
  "version": "1.0",
}

Die Anfrage enthält die folgenden Top-Level-Schlüssel:

meta (erforderlich)

Beschreibt Informationen über die Nutzlast selbst. Derzeit ist der einzige definierte Unter-Schlüssel api-version, dessen Wert die Zeichenfolge "2.0" sein muss. Optionale Unter-Schlüssel können Index-spezifisches Verhalten definieren.

name (erforderlich)

Der Name des Projekts, dessen neue Version diese Sitzung zu veröffentlichen versucht. Der Name **MUSS** dem Standardformat für Paketnamen entsprechen und der Server **MUSS** den Namen normalisieren.

version (erforderlich)

Die Version des Projekts, zu der diese Sitzung Dateien hinzufügt. Die Versionszeichenfolge **MUSS** der Paketversionsspezifikation entsprechen.

Nach erfolgreicher Erstellung der Sitzung gibt der Server eine 201 Created-Antwort zurück. Die Antwort **MUSS** auch einen Location-Header enthalten, der auf dieselbe URL verweist wie der Schlüssel links.session im Antwortkörper.

Wenn eine Sitzung für ein Projekt erstellt wird, das noch keine vorherige Veröffentlichung hat, **KANN** der Index den Projektnamen reservieren, bevor die Sitzung veröffentlicht wird, aber er **DARF NICHT** möglich sein, auf dieses Projekt über die „regulären“ (d. h. nicht-gestagte) Zugriffsprotokolle zuzugreifen, *bis* die Stage veröffentlicht ist. Wenn diese erste Veröffentlichungs-Stage abgebrochen wird, **SOLLTE** der Index den Projekt-Datensatz löschen, als wäre er nie hochgeladen worden.

Die Sitzung gehört dem Benutzer, der sie erstellt hat, und alle nachfolgenden Anfragen **MÜSSEN** mit denselben Anmeldeinformationen durchgeführt werden, andernfalls wird bei diesen nachfolgenden Anfragen ein 403 Forbidden zurückgegeben.

Optionale Index-spezifische Metadaten

Indizes können optional ihre eigenen Metadaten für Index-spezifisches Verhalten definieren. Der Metadaten-Schlüssel **MUSS** mit einem Unterstrich beginnen, wobei der folgende Wert den Index leicht und eindeutig identifiziert. Zum Beispiel könnte PyPI die Erstellung von Projekten in einem Organisationskonto ermöglichen, dessen Mitglied der Publisher ist, indem der folgende Index-spezifische Metadatenabschnitt verwendet wird:

{
  "meta": {
    "api-version": "2.0",
    "_pypi.org": {
        "organization": "my-main-org"
    }
  },
  "name": "foo",
  "version": "1.0",
}

Dies ist nur ein Beispiel. Dieses PEP definiert oder reserviert keine Index-spezifischen Schlüssel oder Metadaten; dies liegt im Ermessen des Index zur Spezifizierung und Dokumentation. Die Semantik (z. B. ob falsche Schlüssel oder Werte zu einem Fehler führen oder ignoriert werden) der Index-spezifischen Metadaten ist hier ebenfalls undefiniert.

{
  "meta": {
    "api-version": "2.0"
  },
  "links": {
    "stage": "...",
    "upload": "...",
    "session": "...",
  },
  "mechanisms": ["http-post-bytes"],
  "session-token": "<token-string>",
  "expires-at": "2025-08-01T12:00:00Z",
  "status": "pending",
  "files": {},
  "notices": [
    "a notice to display to the user"
  ]
}

Eine Veröffentlichungssitzung abschließen

Um eine Sitzung abzuschließen und die darin enthaltenen Dateien zu veröffentlichen, sendet ein Client eine POST-Anfrage an den session Link, der in der Antwort des Sitzungserstellungsvorgangs angegeben ist.

Die Anfrage sieht so aus:

{
  "meta": {
    "api-version": "2.0"
  },
  "action": "publish",
}

Wenn der Server die Veröffentlichungssitzung sofort abschließen kann, kann er dies tun und eine Antwort mit dem Statuscode 201 Created zurückgeben. Wenn er die Veröffentlichungssitzung nicht sofort abschließen kann (z. B. wenn eine Validierung erforderlich ist, die länger als ein HTTP-Anfrage-Timeout dauert), kann er eine Antwort mit dem Statuscode 202 Accepted zurückgeben.

Der Server **MUSS** in der Antwort einen Location-Header einfügen, der auf die URL des Veröffentlichungssitzungsstatus verweist, die zur Abfrage des aktuellen Sitzungsstatus verwendet werden kann. Wenn der Server eine Antwort mit 202 Accepted zurückgegeben hat, kann das Abfragen dieser URL verwendet werden, um auf Änderungen des Sitzungsstatus zu warten.

Abbruch der Veröffentlichungssitzung

Um eine Veröffentlichungssitzung abzubrechen, sendet ein Client eine DELETE-Anfrage an den session Link, der in der Antwort des Sitzungserstellungsvorgangs angegeben ist. Der Server markiert die Sitzung dann als abgebrochen und **SOLLTE** alle Daten löschen, die im Rahmen dieser Sitzung hochgeladen wurden. Zukünftige Zugriffsversuche auf diese Sitzungs-URL oder eine der Veröffentlichungssitzungs-URLs **MÜSSEN** eine Antwort mit dem Statuscode 404 Not Found zurückgeben.

Um hängende Sitzungen zu verhindern, können Server auch abgelaufene Sitzungen eigenständig abbrechen. Es wird empfohlen, dass Server ihre Sitzungen nach nicht weniger als einer Woche löschen, aber jeder Server kann seinen eigenen Zeitplan wählen. Server **KÖNNEN** clientgesteuerte Sitzungserweiterungen unterstützen.

Status der Veröffentlichungssitzung

Ein Client kann jederzeit den Status einer Sitzung abfragen, indem er eine GET-Anfrage an die URL sendet, die im links.session-URL (ebenfalls im Location-Header der Antwort des Sitzungserstellungsvorgangs) angegeben ist.

Der Server wird auf diese GET-Anfrage mit derselben Antwort des Veröffentlichungssitzungserstellungsvorgangs antworten, die er beim anfänglichen Erstellen der Veröffentlichungssitzung erhalten hat, mit Ausnahme von Änderungen an status, expires-at oder files.

Erweiterung der Veröffentlichungssitzung

Server **KÖNNEN** es Clients erlauben, Sitzungen zu verlängern, aber die Gesamtlaufzeit und die Anzahl der erlaubten Verlängerungen liegen im Ermessen des Servers. Um eine Sitzung zu verlängern, sendet ein Client eine POST-Anfrage an die links.session-URL (wie oben, auch der Location-Header).

Die Anfrage sieht so aus:

{
  "meta": {
    "api-version": "2.0"
  },
  "action": "extend",
  "extend-for": 3600
}

Die angegebene Anzahl von Sekunden ist nur ein Vorschlag an den Server für die Anzahl zusätzlicher Sekunden, um die aktuelle Sitzung zu verlängern. Wenn der Client beispielsweise die aktuelle Sitzung um eine weitere Stunde verlängern möchte, wäre extend-for 3600. Nach erfolgreicher Verlängerung antwortet der Server mit derselben Antwort des Veröffentlichungssitzungserstellungsvorgangs, die er beim anfänglichen Erstellen der Veröffentlichungssitzung erhalten hat, mit Ausnahme von Änderungen an status, expires-at oder files.

Wenn der Server sich weigert, die Sitzung um die angeforderte Anzahl von Sekunden zu verlängern, **MUSS** er dennoch eine erfolgreiche Antwort zurückgeben, und der Schlüssel expires-at wird einfach die aktuelle Ablaufzeit der Sitzung widerspiegeln.

Token der Veröffentlichungssitzung

Indizes **SOLLTEN** Vorschau-Stufen unterstützen, damit hochgeladene Dateien live getestet werden können, bevor sie veröffentlicht werden. Z. B. könnte ein CI-Client Installations-Tests mit vorveröffentlichten Wheels durchführen, um sicherzustellen, dass seine neue Version wie erwartet funktioniert, bevor er die Version öffentlich veröffentlicht.

Indizes werben mit der Unterstützung für gestufte Vorschauen, indem sie zwei wichtige Informationen in ihrer Antwort auf die Erstellung von Veröffentlichungssitzungen zurückgeben. Indizes, die keine gestuften Vorschauen unterstützen, **dürfen** diese nicht in ihren Antworten enthalten.

Der session-token ist ein kurzer Token, der als Bequemlichkeit für die Benutzererfahrung von Installationstools verwendet werden könnte, wenn diese gestufte Vorschauen über einen Kommandozeilen-Schalter unterstützen möchten, z. B. $TOOL install --staging $SESSION_TOKEN. Der Schlüssel links.stage gibt die vollständige URL zur Stufe an, die in der CLI verwendet werden könnte, z. B. pip install --extra-index-url $STAGE_URL. Sowohl der Sitzungstoken als auch die URL **MÜSSEN** kryptografisch nicht erratbar sein, aber der Algorithmus zur Generierung des Tokens liegt beim Index. Die Stufen-URL **MUSS** aus dem Sitzungstoken berechenbar sein, unter Verwendung eines vom Index dokumentierten Formats, aber das genaue Format der URL liegt ebenfalls beim Index.

Eine Datei-Upload-Sitzung erstellen

Nachdem eine Veröffentlichungssitzung erstellt wurde, wird der upload-Endpunkt aus der session-Links-Zuordnung der Antwort verwendet, um den Upload neuer Dateien in diese Sitzung zu starten. Clients **MÜSSEN** die bereitgestellte upload-URL verwenden und **dürfen NICHT** davon ausgehen, dass es ein Muster oder eine Gemeinsamkeit dieser URLs von einer Sitzung zur nächsten gibt.

Um einen Dateiupload zu initiieren, sendet ein Client zuerst eine POST-Anfrage an die upload-URL. Die Anfrage sieht so aus:

{
  "meta": {
    "api-version": "2.0"
  },
  "filename": "foo-1.0.tar.gz",
  "size": 1000,
  "hashes": {"sha256": "...", "blake2b": "..."},
  "metadata": "...",
  "mechanism": "http-post-bytes"
}

Neben dem Standardschlüssel meta enthält das JSON der Anfrage die folgenden zusätzlichen Schlüssel:

filename (erforderlich)

Der Name der hochzuladenden Datei. Der Dateiname **MUSS** entweder der Spezifikation für Quellcode-Distributionsdateinamen oder der Konvention für Binärdistributionsdateinamen entsprechen. Indizes **SOLLTEN** diese Dateinamen zum Zeitpunkt der Anfrage validieren und einen Fehlercode 400 Bad Request zurückgeben, wie im Abschnitt Fehler beschrieben, wenn die Dateinamen nicht konform sind.

size (erforderlich)

Die Größe der hochzuladenden Datei in Bytes.

hashes (erforderlich)

Eine Zuordnung von Hash-Namen zu hexadezimal kodierten Digests. Jeder dieser Digests sind die Prüfsummen der hochzuladenden Datei, wenn sie mit dem im Namen identifizierten Algorithmus gehasht wird.

Standardmäßig kann jeder im hashlib verfügbare Hash-Algorithmus als Schlüssel für das hashes-Dictionary verwendet werden [3]. Mindestens ein sicherer Algorithmus aus hashlib.algorithms_guaranteed **MUSS** immer enthalten sein. Dieses PEP empfiehlt speziell sha256.

Mehrere Hashes können gleichzeitig übergeben werden, aber alle bereitgestellten Hashes **MÜSSEN** für die Datei gültig sein.

mechanism (erforderlich)

Die für diese Datei vom Client beabsichtigten Upload-Mechanismen. Dieser Mechanismus **SOLLTE** aus der Liste der im Antwort des Veröffentlichungssitzungserstellungsvorgangs beworbenen Mechanismen ausgewählt werden. Ein Client **KANN** einen Mechanismus senden, der nicht beworben wird, in Fällen, in denen Serverbetreiber einen neuen oder bevorstehenden Mechanismus dokumentiert haben, der auf "Vorabversion"-Basis verfügbar ist.

metadata (optional)

Falls vorhanden, ist dies ein Zeichenkettenwert, der die Kernmetadaten der Datei enthält.

Server **KÖNNEN** die in dieser Anfrage bereitgestellten Daten für einige Plausibilitätsprüfungen verwenden, bevor sie den Upload der Datei zulassen. Diese Prüfungen können umfassen, sind aber nicht beschränkt auf:

• Prüfung, ob der filename bereits in einer veröffentlichten Version vorhanden ist;
• Prüfung, ob die size ein Projekt- oder Dateikontingent überschreiten würde;
• Prüfung, ob der Inhalt der metadata, falls vorhanden, gültig ist.

Wenn der Server feststellt, dass der Upload fortgesetzt werden soll, gibt er eine Antwort mit 202 Accepted mit dem unten stehenden Antwortkörper zurück. Der Status der Veröffentlichungssitzung enthält auch den Dateinamen in der files-Zuordnung. Wenn der Server einen Upload nicht fortsetzen kann, weil der vom Client bereitgestellte mechanism nicht unterstützt wird, **MUSS** er eine Antwort mit 422 Unprocessable Content zurückgeben. Der Server **KANN** parallele Uploads von Dateien zulassen, ist aber nicht dazu verpflichtet. Wenn der Server feststellt, dass der Upload nicht fortgesetzt werden kann, **MUSS** er eine Antwort mit 409 Conflict zurückgeben.

{
  "meta": {
    "api-version": "2.0"
  },
  "links": {
    "file-upload-session": "..."
  },
  "status": "pending",
  "expires-at": "2025-08-01T13:00:00Z",
  "mechanism": {
    "identifier": "http-post-bytes",
    "file_url": "...",
    "attestations_url": "..."
  }
}

Eine Datei-Upload-Sitzung abschließen

Um eine Datei-Upload-Sitzung abzuschließen, was bedeutet, dass der Datei-Upload-Mechanismus ausgeführt wurde und keine Fehler erzeugt hat, sendet ein Client eine POST an den file-upload-session-Link in der Antwort des Datei-Upload-Sitzungserstellungsvorgangs.

Die Anfrage sieht so aus:

{
  "meta": {
    "api-version": "2.0"
  },
  "action": "complete",
}

Wenn der Server die Datei-Upload-Sitzung sofort abschließen kann, kann er dies tun und eine Antwort mit 201 Created zurückgeben und den Status der Datei-Upload-Sitzung auf complete setzen. Wenn er die Datei-Upload-Sitzung nicht sofort abschließen kann (z. B. wenn eine Validierung erforderlich ist, die länger als eine HTTP-Anfrage dauern könnte), kann er eine Antwort mit 202 Accepted zurückgeben und den Status der Datei-Upload-Sitzung auf processing setzen.

In beiden Fällen sollte der Server einen Location-Header einfügen, der auf die URL des Status der Datei-Upload-Sitzung verweist.

Server **MÜSSEN** es Clients erlauben, die URL des Datei-Upload-Sitzungsstatus abzufragen, um auf Statusänderungen zu warten. Wenn der Server mit 20 Accepted antwortet, können Clients die URL des Datei-Upload-Sitzungsstatus abfragen, um auf Statusänderungen zu warten. Clients **SOLLTEN** den Retry-After-Header-Wert der Antwort des Datei-Upload-Sitzungsstatus respektieren.

Abbruch und Löschung

Ein Client kann eine laufende Datei-Upload-Sitzung abbrechen oder eine bereits vollständig hochgeladene Datei löschen. In beiden Fällen führt der Client dies durch Senden einer DELETE-Anfrage an die URL links.file-upload-session aus der Antwort des Datei-Upload-Sitzungserstellungsvorgangs der Datei, die er löschen möchte.

Eine erfolgreiche Löschanfrage **MUSS** mit einer Antwort vom Typ 204 No Content beantwortet werden.

Nach dem Abbrechen oder Löschen **darf** ein Client nicht davon ausgehen, dass die vorherige Datei-Upload-Sitzungsressource oder zugehörige Datei-Upload-Mechanismen wiederverwendet werden können.

Ersetzen einer teilweise oder vollständig hochgeladenen Datei

Um eine Sitzungsdatei zu ersetzen, **MUSS** die Datei-Uploadsitzung zuvor abgeschlossen, abgebrochen oder gelöscht worden sein. Es ist nicht möglich, eine Datei zu ersetzen, wenn der Upload für diese Datei noch läuft.

Um eine Sitzungsdatei zu ersetzen, sollten Clients zuerst den laufenden Upload abbrechen und löschen. Danach kann der neue Datei-Upload eingeleitet werden, indem die gesamte Datei-Upload-Sequenz erneut gestartet wird. Das bedeutet, die Metadatenanfrage erneut zu stellen, um eine neue Upload-Ressourcen-URL zu erhalten. Clients **dürfen NICHT** davon ausgehen, dass die vorherige Upload-Ressourcen-URL nach dem Löschen wiederverwendet werden kann.

Status der Datei-Upload-Sitzung

Der Client kann den Status der Datei-Upload-Sitzung abfragen, indem er eine GET-Anfrage an die URL links.file-upload-session aus der Antwort des Datei-Upload-Sitzungserstellungsvorgangs sendet. Der Server antwortet auf diese Anfrage mit derselben Nutzlast wie die Antwort des Datei-Upload-Sitzungserstellungsvorgangs, mit Ausnahme von Änderungen an status und expires-at.

Erweiterung der Datei-Upload-Sitzung

Server **KÖNNEN** es Clients erlauben, Datei-Upload-Sitzungen zu verlängern, aber die Gesamtlaufzeit und die Anzahl der erlaubten Verlängerungen liegen im Ermessen des Servers. Um eine Datei-Upload-Sitzung zu verlängern, sendet ein Client eine POST-Anfrage an die URL links.file-upload-session aus der Antwort des Datei-Upload-Sitzungserstellungsvorgangs.

Die Anfrage sieht so aus:

{
  "meta": {
    "api-version": "2.0"
  },
  "action": "extend",
  "extend-for": 3600
}

Die angegebene Anzahl von Sekunden ist nur ein Vorschlag an den Server für die Anzahl zusätzlicher Sekunden, um die aktuelle Datei-Upload-Sitzung zu verlängern. Wenn der Client beispielsweise die Sitzung um eine weitere Stunde verlängern möchte, wäre extend-for 3600. Nach erfolgreicher Verlängerung antwortet der Server mit derselben Antwort des Datei-Upload-Sitzungserstellungsvorgangs, die er beim anfänglichen Erstellen der Veröffentlichungssitzung erhalten hat, mit Ausnahme von Änderungen an status oder expires-at.

Wenn der Server sich weigert, die Sitzung um die angeforderte Anzahl von Sekunden zu verlängern, **MUSS** er dennoch eine erfolgreiche Antwort zurückgeben, und der Schlüssel expires-at wird einfach die aktuelle Ablaufzeit der Sitzung widerspiegeln.

Erforderliche Datei-Upload-Mechanismen

Content-Type: application/octet-stream

<binary contents of the file to upload>

Content-Type: application/json

[{"version": 1, "verification_material": {...}, "envelope": {...}},...]

Serverspezifische Datei-Upload-Mechanismen

Ein bestimmter Server **KANN** eine beliebige Anzahl von serverseitig spezifischen Mechanismen implementieren und ist dafür verantwortlich, deren Verwendung zu dokumentieren.

Eine serverseitig spezifische Implementierung eines Datei-Upload-Mechanismus-Identifikators hat drei Teile:

<prefix>-<operator identifier>-<implementation identifier>

Serverseitig spezifische Implementierungen **MÜSSEN** vnd als ihr prefix verwenden. Der operator-identifier **sollte** den Serverbetreiber klar identifizieren, eindeutig von anderen bekannten Indizes sein und nur alphanumerische Zeichen [a-z0-9] enthalten. Der implementation-identifier **sollte** die zugrunde liegende Implementierung prägnant beschreiben und nur alphanumerische Zeichen [a-z0-9] und - enthalten.

Wenn Serverbetreiber wesentliche Änderungen an ihren Upload-Mechanismen vornehmen müssen, **sollten** sie einen neuen Mechanismus-Identifikator erstellen, anstatt den bestehenden zu ändern. Das empfohlene Muster ist, einen Versionsuffix wie -v1, -v2 usw. an den Implementierungs-Identifikator anzuhängen. Dies ermöglicht es Clients, sich explizit für neue Versionen zu entscheiden und gleichzeitig die Abwärtskompatibilität mit bestehenden Clients aufrechtzuerhalten.

Zum Beispiel:

Wenn ein Server beabsichtigt, das Verhalten der Implementierung eines anderen Servers genau nachzubilden, **KANN** er mit dem Namen des Datei-Upload-Mechanismus dieser Implementierung antworten.