包管理

相关源文件

• crates/uv-client/Cargo.toml
• crates/uv-client/src/base_client.rs
• crates/uv-client/src/cached_client.rs
• crates/uv-client/src/error.rs
• crates/uv-client/src/flat_index.rs
• crates/uv-client/src/lib.rs
• crates/uv-client/src/linehaul.rs
• crates/uv-client/src/registry_client.rs
• crates/uv-dispatch/src/lib.rs
• crates/uv-distribution/src/distribution_database.rs
• crates/uv-distribution/src/error.rs
• crates/uv-distribution/src/source/mod.rs
• crates/uv/src/commands/pip/compile.rs
• crates/uv/src/commands/pip/install.rs
• crates/uv/src/commands/pip/operations.rs
• crates/uv/src/commands/pip/sync.rs
• crates/uv/src/commands/venv.rs

本文档涵盖了 uv 的包管理基础设施，包括分发数据库、源构建、注册表客户端和包安装系统。这些组件协同工作，从 PyPI 注册表、Git 存储库、本地路径和扁平索引等各种来源获取、构建和安装 Python 包。

有关依赖解析算法的信息，请参阅 依赖解析。有关 uv 缓存机制的详细信息，请参阅 缓存系统。

系统架构概览

uv 的包管理系统围绕几个核心组件构建，这些组件处理包的获取和安装的完整生命周期。

包管理系统遵循分层架构，其中客户端处理网络操作，分发数据库协调包解析，而专用构建器处理源分发编译。

来源：crates/uv-client/src/registry_client.rs1-300 crates/uv-distribution/src/distribution_database.rs1-100 crates/uv-distribution/src/source/mod.rs1-100

注册表客户端系统

The RegistryClient 是从 PyPI 兼容注册表中获取包元数据和 wheel 的主要接口。它支持 Simple Repository API (PEP 503) 和基于 JSON 的 Simple API (PEP 691)。

RegistryClient 配置

The RegistryClientBuilder 提供了一个流畅的 API 来配置注册表访问。

• 索引策略：控制如何搜索多个索引（FirstIndex、UnsafeBestMatch、UnsafeFirstMatch）
• 身份验证：支持 keyring 提供程序和凭据管理。
• 缓存：与 uv 的全局缓存系统集成。
• 连接性：处理在线/离线模式。
• 平台支持：根据平台标签和标记过滤包。

来源：crates/uv-client/src/registry_client.rs49-201 crates/uv-client/src/base_client.rs49-102

包元数据获取

注册表客户端实现了一种复杂的元数据获取策略。

对于 wheel 元数据，客户端按顺序尝试多种策略：

1. PEP 658 元数据 URL（.metadata 文件）
2. 远程 ZIP 范围请求 METADATA 文件
3. 作为后备的全 wheel 下载。

来源：crates/uv-client/src/registry_client.rs306-425 crates/uv-client/src/registry_client.rs656-763

分发数据库

The DistributionDatabase 是将分发引用转换为可用 wheel 或元数据的高级协调器。它管理从源获取到 wheel 生产的整个管道。

分发解析流程

数据库根据分发类型实现不同的策略：

1. 已构建的分发（Wheels）:

   • 注册表 wheels：从带缓存的索引下载。
   • 直接 URL wheels：从 URL 流式传输或下载。
   • 本地 wheels：直接从文件系统加载。

2. 源分发:

   • 下载源归档。
   • 解压到缓存。
   • 使用适当的后端构建 wheel。
   • 缓存生成的 wheel。

3. 已安装的分发:

   • 从 site-packages 读取元数据。
   • 应用用户提供的元数据覆盖。

来源：crates/uv-distribution/src/distribution_database.rs50-169 crates/uv-distribution/src/distribution_database.rs174-350

并发下载管理

The ManagedClient 包装器提供了受控的下载并发。

信号量限制并发下载，以防止服务器过载和消耗过多的带宽。

来源：crates/uv-distribution/src/distribution_database.rs1154-1200

源分发构建

The SourceDistributionBuilder 处理将源分发转换为 wheel 的复杂过程。它支持多种源类型并在多个级别实现缓存。

修订管理

源分发使用基于内容的修订 ID 进行缓存，以确保缓存一致性。

• HTTP 源：使用 ETag 和 Last-Modified 标头。
• Git 源：使用提交 SHA 作为修订。
• 本地源：使用文件修改时间和大小。
• 归档源：使用文件哈希作为修订。

来源：crates/uv-distribution/src/source/mod.rs679-756 crates/uv-distribution/src/source/revision.rs1-50

构建后端集成

构建器通过 BuildContext 接口与各种 Python 构建后端集成。

来源：crates/uv-dispatch/src/lib.rs77-148 crates/uv-distribution/src/source/mod.rs467-497

扁平索引支持

The FlatIndexClient 提供对 --find-links 风格的包索引的支持，这些索引可以是本地目录或包含包文件的远程 HTML 页面。

目录扫描

对于本地目录，客户端会递归扫描 Python 包文件。

• 识别 wheel 文件（.whl）。
• 识别源分发（.tar.gz、.zip）。
• 从文件名提取元数据。
• 构建本地访问的文件 URL。

HTML 解析

对于远程 HTML 索引，客户端会解析 HTML 内容以提取包链接。

• 使用 SimpleHtml 解析器。
• 从 anchor 标签提取 href 属性。
• 相对于基础 URL 解析相对 URL。
• 过滤识别的包文件扩展名。

来源：crates/uv-client/src/flat_index.rs140-220 crates/uv-client/src/flat_index.rs160-250

安装管道

包管理系统最终形成一个复杂的安装管道，负责依赖解析、wheel 准备和 site-packages 管理。

安装策略

该系统通过链接模式支持多种安装策略：

• 复制：用于隔离环境的全文件复制。
• 硬链接：在支持的场景下实现节省空间的链接。
• 符号链接：用于开发工作流的符号链接。
• 克隆：支持写时复制文件系统。

并发操作

在整个管道中，操作尽可能并行化。

• 多个包下载并发运行。
• 源构建可以并行运行。
• Wheel 提取和安装可以并行化。
• 网络操作使用连接池。

来源：crates/uv/src/commands/pip/operations.rs106-326 crates/uv-installer/src/planner.rs1-50 crates/uv-installer/src/preparer.rs1-50