PyPI Onboarding — Field Guides

No. 00 The PyPI Universe An orientation map of the repos and services around PyPI — what's official infra, what's a satellite service, and what's someone's side project — before diving into any one of them. Orientation 3,873 words · ~19 min Read
No. 01 Warehouse Overview The Pyramid app that runs pypi.org: request lifecycle, project/release model, and the shape of the codebase everything else in this series orbits. PyPI · Core app pypi/warehouse 6,509 words · ~33 min Read
No. 02 Warehouse's Plugin Architecture 50 self-contained Pyramid "plugins" wired together with includeme, a hybrid URL-traversal-and-dispatch pattern, and how Forklift's upload API still shares this codebase. PyPI · Dev patterns pypi/warehouse · Pyramid 5,657 words · ~28 min Read
No. 03 Swappable Backends Why Warehouse defines a zope.interface for file storage, email, and rate limiting — and how one config setting swaps local disk for S3 without touching a single view. PyPI · Dev patterns pypi/warehouse · zope.interface 6,536 words · ~33 min Read
No. 04 PyPI's API History From XML-RPC and a legacy JSON endpoint to the Simple API's HTML-links-turned-hypermedia design — why it's so cacheable, and what macaroons/caveats add to auth. PyPI · History XML-RPC · Simple API · macaroons 7,587 words · ~38 min Read
No. 05 PEP 694 Field Guide Uploads, then and now — from Forklift's web-form-era upload endpoint to PEP 694's sessions, staged releases, and one atomic publish. PyPI · Uploads PEP 694 · pypi/warehouse 5,468 words · ~27 min Read
No. 06 Wheels & What's (Wheel)Next Today's wheel filename tags, their real limits, and the PEP 817 → PEP 825 → PEP 777 thread on wheel variants — how a package might one day ship separate builds per GPU. PyPI · Packaging future PEP 817 · PEP 825 · PEP 777 · wheelnext.dev 6,709 words · ~34 min Read
No. 07 Infra The Terraform layer underneath Warehouse — DNS, transactional email, file hosting, the image proxy, and docs hosting: what actually runs the app in production. PyPI · Infrastructure pypi/infra 7,285 words · ~36 min Read
No. 08 Camo The HTTPS image proxy that rewrites README images so project pages never trigger mixed-content warnings — an HMAC-signing scheme split across two codebases. PyPI · Satellite service pypi/camo 5,181 words · ~26 min Read
No. 09 Conveyor The legacy URL and docs redirector — why old pypi.python.org links still resolve, and how it serves user docs uploaded before Warehouse rendered its own. PyPI · Satellite service pypi/conveyor 5,243 words · ~26 min Read
No. 10 Linehaul Field Guide A pip install becomes a row in a public BigQuery table. This guide shows how, and how to change the code. PyPI · Telemetry pypi/linehaul-cloud-function 5,324 words · ~27 min Read
No. 11 Support The issue tracker and the PEP 541 name-retention runbook — the human process side of PyPI: account recovery, upload-limit requests, and squatting disputes. PyPI · Process pypi/support 7,226 words · ~36 min Read
No. 12 pip Meets PyPI How a pip install resolves, negotiates, and downloads across the Simple API — the client side of everything the rest of this series explains from the server. PyPI · Client pypa/pip · pypa/packaging 7,381 words · ~37 min Read