Draft: docs(specs): add S34 PyPI hosted format spec

What does this MR do and why?

Adds S34: PyPI hosted — the master spec for hosted PyPI repositories — plus its spec-index row. Opened with **Status:** Approved per the spec-MR guardrail (the merge is the approval signal).

This is the unified draft: two independently authored S34 candidates were deeply compared (assertion-based grading against fact-checked PyPI protocol ground truth plus a comparative design review), and this spec merges the stronger base with the best elements of the second draft.

Scope: hosted (local) repositories only; remote and virtual PyPI are deferred to future slice specs. Client matrix: pip install, twine upload, Poetry and uv (resolve and publish), and hash-checking CI (pip --require-hashes).

Highlights:

  • Read surface: Simple Repository API in HTML (1.0) and JSON (1.1) with q-value Accept negotiation and a 406 rule; exact Content-Type on every response (uv hard-fails without one); strong ETags; PEP 833's HTML freeze honored; PEP 592 yanked rendering (state columns ship now, mutations stay with S17).
  • PEP 658 metadata files: extracted at publish time behind the canonical registry's decompression guard — wheels strict (METADATA is mandated), sdists tolerant (PKG-INFO when present) — served as <file-url>.metadata with only the PEP 714 core-metadata keys (the legacy spelling crashes incident-window pip; all three resolvers verifiably read the renamed key). A publish-time coherence check requires the archive-internal Name/Version to match the declared fields.
  • Publish flow: streaming multipart upload through the S06 two-phase session; fail-closed sha256 policy; append-only filename-claims ledger implementing PyPI's never-reuse-a-filename rule race-free; 409 + already exists duplicate contract verified against twine's and Poetry's skip-existing matchers; RETURNING-gated exactly-once release counters under concurrency.
  • Data model: pypi_* tables as flagged ADR 007 amendments following the partitioning/UUIDv7/composite-key conventions; format enum value allocated as next-free (4 at drafting), confirmed against main at implementation time.
  • Every protocol claim traces to a source fetched during authoring (PyPA specs, PEP status pages, PyPI docs, and pip/twine/Poetry/uv source); observed-only behavior is explicitly marked; alternatives considered during unification are recorded in Resolutions with reasons.

Supersedes !1006 (closed) (the pre-unification draft on suleimiahmed/s34-pypi-hosted-spec); that MR can be closed in favor of this one.

Amendments to raise separately (flagged in-spec): ADR 004 PyPI limits row, ADR 007 PyPI tables section, ADR 009 PyPI client routes — all handbook-repo MRs. The format::pypi scoped label exists and is applied.

After this merges: /planner for the implementation plan MR, then /implement-step per step.

Follow-ups tracked: PEP 740 attestation support in #363.

Edited by Dzmitry (Dima) Meshcharakou

Merge request reports

Loading
Loading