uv-distribution

crates/uv-distribution/ is the layer that turns "I want metadata for this distribution" into HTTP requests, sdist builds, and cached results. It sits between the resolver and the HTTP client: the resolver asks for versions and metadata; this crate decides whether the answer is in the cache, on a flat index, behind a git+https:// URL, or requires building an sdist.

Purpose

• Centralize distribution-database access behind a DistributionDatabase so the resolver doesn't need to know about HTTP, caches, or build pipelines.
• Cache distribution metadata (ResolutionMetadata, Metadata23) so a single resolution doesn't re-fetch the same package.
• Drive PEP 517 builds for sdists and direct-URL sources via uv-build-frontend.
• Read remote metadata in PEP 658 (sidecar .metadata files) and PEP 691 (JSON index) formats.

Directory layout

crates/uv-distribution/src/
├── lib.rs                       # Re-exports + ArchiveMetadata
├── distribution_database.rs     # DistributionDatabase: the orchestrator (~58k chars)
├── archive.rs                   # ArchiveMetadata wrapper
├── download.rs                  # Download helpers
├── error.rs                     # DistributionDatabaseError
├── reporter.rs                  # Progress reporter trait
├── index/                       # Index lookups: registry vs. flat
├── source/                      # Source distribution build orchestration
└── metadata/                    # Per-distribution metadata read paths

Key abstractions

Type	File	Role
DistributionDatabase	distribution_database.rs	The main entry point. Fetches distribution metadata, downloads files, builds sdists, all caching-aware.
BuildRequires	metadata/	The aggregated build-system requires for a project, including overrides and constraint sources.
ArchiveMetadata	archive.rs	A thin wrapper around Metadata23 plus the cache file path.
Reporter	reporter.rs	Progress callbacks (downloads, builds).

How it works

The resolver provides a ResolverProvider (typically DefaultResolverProvider) which, given a package name, asks the DistributionDatabase for VersionsResponse (the candidate version list) or WheelMetadataResult (per-version metadata). The database in turn:

1. Looks up the package in the configured indexes via uv-client.
2. For each candidate, checks the cache, then attempts to read metadata from:
   • PEP 658 sidecar .metadata files (if the index advertises support).
   • The wheel's METADATA file via a partial download (HTTP range requests).
   • A built sdist (last resort: triggers a PEP 517 build).
3. Persists the result in the cache.

The source/ subdirectory drives sdist builds. It coordinates with the BuildContext trait (from uv-types) to obtain a build environment with the right build-system.requires, runs the backend's prepare_metadata_for_build_wheel hook if available, and falls back to build_wheel if the backend doesn't support metadata-only builds.

Integration points

• Up: uv-resolver consumes DistributionDatabase through the ResolverProvider trait.
• Down: uv-client for HTTP, uv-cache for storage, uv-build-frontend for builds, uv-git for git sources, uv-extract for tar/zip extraction.

Entry points for modification

• A new metadata source — add a method on DistributionDatabase and dispatch from the metadata-resolution loop.
• A new distribution kind — most additions live in uv-distribution-types; this crate then adds the fetch/build path.
• Tweaking source builds — source/ orchestration. The actual subprocess invocation lives in uv-build-frontend.

Key source files

File	Purpose
crates/uv-distribution/src/distribution_database.rs	The orchestrator.
crates/uv-distribution/src/source/	Source-distribution build orchestration.
crates/uv-distribution/src/metadata/	Per-distribution metadata read paths.
crates/uv-distribution/src/index/	Registry / flat-index dispatch.

See also

• uv-distribution-types for the data types.
• uv-distribution-filename for parsing wheel/sdist filenames.
• uv-resolver for the consumer side.
• uv-build-frontend for sdist builds.