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).

Scope decided in the authoring interview: 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 Accept negotiation; exact Content-Type on every response (uv hard-fails without it); strong ETags; PEP 833's HTML freeze honored.
  • PEP 658 wheel metadata files: extracted at publish time behind the canonical registry's decompression guard (stored/deflated only, 64 MiB cap, ratio 50), served as <file-url>.metadata with the PEP 714 core-metadata keys only — the deciding factor for fast Poetry/uv resolution against a private index.
  • 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 the skip-existing matchers of twine (source, 6.2.0) and Poetry (source, main).
  • 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 and unverifiable claims were excluded.

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. A format::pypi scoped label does not exist yet and needs creating; this MR carries the closest existing label set.

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

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

Merge request reports

Loading
Loading