项目初始化

相关源文件

• crates/uv-configuration/src/project_build_backend.rs
• crates/uv-workspace/src/workspace.rs
• crates/uv/src/commands/project/init.rs
• crates/uv/tests/it/init.rs
• docs/concepts/projects/init.md

本文档介绍了 uv 的项目初始化系统，该系统用于创建新的 Python 项目和 PEP 723 脚本。有关现有项目的依赖管理信息，请参阅 依赖管理。有关工作空间管理的概念，请参阅 工作空间。

概述

项目初始化系统支持两种主要的初始化类型：项目（应用程序和库）和 PEP 723 脚本。项目初始化会创建完整的 Python 项目结构，并包含 pyproject.toml 文件，而脚本初始化则会创建带有嵌入式依赖元数据的独立可执行 Python 文件。

初始化类型和代码映射

• InitKind::Script → init_script() 函数
• InitKind::Project(InitProjectKind::Application) → init_application() 方法
• InitKind::Project(InitProjectKind::Library) → init_library() 方法

来源：crates/uv/src/commands/project/init.rs669-700 crates/uv/src/commands/project/init.rs684-700

初始化流程

主要的初始化过程遵循结构化的流程，该流程确定 Python 的要求、与工作空间集成并生成适当的项目结构。

关键函数和入口点

• 主入口：init() 函数位于 crates/uv/src/commands/project/init.rs40-186
• 脚本处理：init_script() 函数位于 crates/uv/src/commands/project/init.rs189-270
• 项目处理：init_project() 函数位于 crates/uv/src/commands/project/init.rs274-667

来源：crates/uv/src/commands/project/init.rs40-186 crates/uv/src/commands/project/init.rs105-113

Python 版本解析

Python 版本的确定遵循优先级层次结构，该结构考虑了用户输入、现有环境、工作空间设置和系统默认值。

Python 解析优先级（按顺序）

1. --python CLI 参数 → PythonRequest::parse()
2. .python-version 文件 → PythonVersionFile::discover()
3. 现有 .venv → PythonEnvironment::from_root()
4. 工作空间 requires-python → find_requires_python()
5. 系统 Python → PythonInstallation::find_or_download()

来源：crates/uv/src/commands/project/init.rs351-575 crates/uv/src/commands/project/init.rs374-482

工作区集成

项目初始化会自动发现并与现有工作空间集成，更新工作空间成员资格并继承配置。

工作空间集成组件

• 发现：来自工作空间模块的 Workspace::discover()
• 成员资格检查：workspace.excludes() 和 workspace.includes() 方法
• 添加成员：PyProjectTomlMut::add_workspace() 方法
• 配置继承：Python 版本和依赖项来源

来源：crates/uv/src/commands/project/init.rs298-343 crates/uv/src/commands/project/init.rs592-649 crates/uv-workspace/src/workspace.rs143-236

构建后端选择

初始化系统支持多种构建后端，以适应不同的项目类型和需求，并根据项目类型和用户偏好自动选择。

构建后端	枚举值	用例	模板文件
hatchling	ProjectBuildBackend::Hatch	打包项目的默认设置	标准 Python 布局
uv_build	ProjectBuildBackend::Uv	预览模式默认	标准 Python 布局
flit-core	ProjectBuildBackend::Flit	简单的纯 Python 包	标准 Python 布局
pdm-backend	ProjectBuildBackend::PDM	PDM 生态系统项目	标准 Python 布局
setuptools	ProjectBuildBackend::Setuptools	旧版兼容性	标准 Python 布局
poetry-core	ProjectBuildBackend::Poetry	Poetry 生态系统项目	标准 Python 布局
maturin	ProjectBuildBackend::Maturin	Rust 扩展模块	Cargo.toml, lib.rs
scikit-build-core	ProjectBuildBackend::Scikit	C/C++ 扩展模块	CMakeLists.txt, main.cpp

构建系统生成函数

• 主生成：pyproject_build_system() 函数位于 crates/uv/src/commands/project/init.rs944-1015
• 先决条件：pyproject_build_backend_prerequisites() 函数位于 crates/uv/src/commands/project/init.rs1027-1170 crates/uv/src/commands/project/init.rs873-880 crates/uv/src/commands/project/init.rs944-1015
• 后端类型：ProjectBuildBackend 枚举位于 crates/uv-configuration/src/project_build_backend.rs6-38

来源：crates/uv/src/commands/project/init.rs798-805 crates/uv/src/commands/project/init.rs873-880 crates/uv/src/commands/project/init.rs944-1015

项目结构生成

不同的项目类型会根据初始化参数和项目类型生成不同的文件结构和内容。

文件生成函数

• 主要的项目元数据：pyproject_project() 函数位于 crates/uv/src/commands/project/init.rs916-940
• 包结构：generate_package_scripts() 函数位于 crates/uv/src/commands/project/init.rs1172-1396
• 脚本创建：uv-scripts crate 中的 Pep723Script::create()
• VCS 初始化： init_vcs() 于 crates/uv/src/commands/project/init.rs1398-1429

应用程序与库的区别

• 应用程序：可选打包，main.py 用于简单场景，打包后使用命令行脚本
• 库：始终打包，src 布局，py.typed 标记，API 导向的 __init__.py
• 脚本：带有 PEP 723 元数据块的独立文件

来源：crates/uv/src/commands/project/init.rs753-836 crates/uv/src/commands/project/init.rs840-893 crates/uv/src/commands/project/init.rs1172-1396

错误处理与验证

该初始化系统包括对常见失败场景的全面错误处理，并在创建之前验证项目约束。

错误类型与处理

• WorkspaceError 变体来自 crates/uv-workspace/src/workspace.rs44-77
• 项目存在性检查于 crates/uv/src/commands/project/init.rs106-113
• 通过 crates/uv/src/commands/project/init.rs228-234 验证脚本
• 库打包要求于 crates/uv/src/commands/project/init.rs854-856

来源：crates/uv/src/commands/project/init.rs106-113 crates/uv/src/commands/project/init.rs228-234 crates/uv/src/commands/project/init.rs854-856 crates/uv-workspace/src/workspace.rs44-77