Documentation

Standards

velodex targets the interoperability standards a modern index and its clients rely on. The Simple Repository API is the living consolidation of most of them; velodex serves meta.api-version 1.4.

What a pip install asks for

Knowing the request sequence makes the table below concrete. For pip install requests against any standards-compliant index:

indexpip / uvindexpip / uvresolve, repeating metadata fetchesfor candidates as neededGET /simple/requests/ (Accept: PEP 691 JSON)file list: names, URLs, sha256, yanked, core-metadataGET …requests-2.32.5…whl.metadata (PEP 658)core metadata: dependencies, requires-pythonGET …requests-2.32.5…whlthe wheel, which pip verifies against its sha256
indexpip / uvindexpip / uvresolve, repeating metadata fetchesfor candidates as neededGET /simple/requests/ (Accept: PEP 691 JSON)file list: names, URLs, sha256, yanked, core-metadataGET …requests-2.32.5…whl.metadata (PEP 658)core metadata: dependencies, requires-pythonGET …requests-2.32.5…whlthe wheel, which pip verifies against its sha256

Every hop names a standard: the page format is PEP 503/691, its fields are PEP 700, the yank markers are PEP 592, the metadata shortcut is PEP 658/714, and the filename pip parsed to pick a wheel is PEP 427. velodex sits on both sides of this conversation, a server to your clients and a client to its upstreams, which is why the table below mixes "served" and "parsed".

StandardRole in velodex
PEP 503The HTML simple index and project-name normalization; served to clients that do not ask for JSON, and parsed from HTML-only upstreams
PEP 691The JSON simple index and its content negotiation; the primary wire format both directions
PEP 629Version marker on responses so clients can detect capabilities
PEP 700The versions, size, and upload-time fields introduced in api-version 1.1
PEP 592Yanked files: parsed from upstreams, re-served, and settable on uploads
PEP 658 / PEP 714The .metadata sibling that lets resolvers skip wheel downloads; advertised, fetched, verified, and cached
PEP 740Provenance URLs on Simple API file entries; preserved when an upstream provides them
PEP 440Version parsing, ordering, and Requires-Python validation
PEP 427 / PEP 625Wheel filename, .dist-info, WHEEL, and RECORD checks; modern .tar.gz sdist filename, root, and required-file checks
Core metadataMETADATA and PKG-INFO parsing for upload identity checks, PEP 658 siblings, and Metadata 2.4+ sdist license-file checks
Legacy JSON APICompatibility responses for tools that call /pypi/{project}/json and /pypi/{project}/{version}/json
Legacy upload APIThe multipart upload protocol twine and uv publish speak
.pypircThe __token__ authentication convention for uploads and upstream mirrors

PEP 714 and the core-metadata key

PEP 658 shipped with a bug in its dist-info-metadata key name, and PEP 714 renamed it to core-metadata. Indexes such as pypi.org emit both keys for compatibility. velodex parses both spellings, prefers core-metadata when both are present, and emits both spellings downstream for older clients.

Graceful degradation

Some upstreams implement only part of the stack; Artifactory and GitLab serve HTML alone. velodex negotiates JSON first, parses PEP 503 HTML as the fallback, and re-serves the modern formats downstream, so a client gets api-version 1.4. Features the upstream cannot express (a missing .metadata sibling, absent sizes) degrade per file rather than per index. An upstream that advertises another Simple API major version is rejected with a 502 response; velodex supports Simple API 1.x.

The discovery documents at /+api and /{route}/+api report only capabilities Velodex implements today. They advertise Simple HTML/JSON, api-version 1.4, PEP 658 metadata siblings, project status, provenance, and legacy JSON. The legacy JSON responses are derived from Simple detail pages, so fields outside that source, such as ownership and vulnerability data, are empty.

In practice

On this page