Rye 依赖管理实战指南：从 `pyproject.toml` 到 `rye add` 的完整解析

Rye 依赖管理实战指南从pyproject.toml到rye add的完整解析【免费下载链接】ryea Hassle-Free Python Experience项目地址: https://gitcode.com/gh_mirrors/ry/rye导读本文围绕 Rye 官方指南 deps.md 展开系统讲解如何在 Rye 管理的 Python 项目中声明与维护依赖从最基础的rye add普通依赖、PEP 508 版本约束、extras 特性依赖到开发依赖、Git/本地路径依赖与 workspace 协作。同时结合本仓库的 Rust 源码rye/src/cli/add.rs、rye/src/pyproject.rs与测试用例rye/tests/test_add.rs剖析依赖写入pyproject.toml的底层机制与参数语义。读完本文你将掌握 Rye 中依赖声明、添加、移除与同步的完整工作流并能根据项目场景选择最合适的依赖类型。依赖声明的核心pyproject.tomlrye add在 Rye 中所有依赖最终都声明在项目的 pyproject.toml 中。虽然你可以手工编辑该文件但 Rye 提供了更友好的rye add命令来简化这一过程——它接受 PEP 508 需求字符串作为输入同时提供一系列辅助参数如--git、--path让声明依赖这件事不再需要记忆冗长的语法。Rye 对project.dependencies这一键不做任何私有化改造——它完全符合标准pyproject.toml的语义只是 Rye 具备通过rye add/rye remove自动修改这些条目的能力。也就是说用rye add写进去的内容和手写标准 PEP 508 字符串完全等价。从源码看rye add的核心执行流程rye/src/cli/add.rs分为三步解析传入的 PEP 508 需求字符串并应用--git、--path、--features等参数改写为最终需求ReqExtras::apply_to_requirement借助内置的 uv 解析器解析出可用的最新版本并按照默认或指定的 pin 操作符生成版本约束调用PyProject::add_dependency把需求写入对应的 TOML 键rye/src/pyproject.rs最后按需触发自动同步autosync。依赖在 TOML 中的归属根据DependencyKind枚举rye/src/pyproject.rsRye 支持四类依赖写入位置依赖类型写入位置触发参数普通依赖regularproject.dependencies默认开发依赖devtool.rye.dev-dependencies--dev排除依赖excludedtool.rye.excluded-dependencies--excluded可选分组依赖optionalproject.optional-dependencies.分组名--optional 名称源码中add_dependency函数rye/src/pyproject.rs正是按这个映射将需求写入不同键位且会自动创建缺失的数组或表。这与 pyproject.md 中project.dependencies、tool.rye.dev-dependencies等键的说明一一对应。添加基础依赖添加普通依赖最简单的方式就是直接用包名调用rye addrye add Flask该命令会先初始化/复用项目虚拟环境随后解析出当前 Python 版本下兼容的最新版本并以操作符写入project.dependencies最后自动生成requirements.lock与requirements-dev.lock并安装依赖。测试 rye/tests/test_add.rs 中记录的真实输出为$ rye add flask colorama Added flask3.0.0 as regular dependency Added colorama0.4.6 as regular dependency Reusing already existing virtualenv Generating production lockfile: requirements.lock Generating dev lockfile: requirements-dev.lock Installing dependencies Done!对应的pyproject.toml片段[project] dependencies [ flask3.0.0, colorama0.4.6, ]指定版本使用 PEP 508 需求字符串如果想控制版本直接传入 PEP 508 需求字符串即可rye add Flask2.0 rye add werkzeug3.0.0注意测试 test_add_explicit_version_or_url 显示当你显式给出完整版本如3.0.0时Rye 会保留原样写入不再解析追加操作符而只给包名时才会自动补上解析得到的最新版本与默认操作符。默认版本操作符的定制Rye 默认使用作为自动 pin 操作符但这一行为可通过全局配置dependency-operator调整rye/src/config.rs# config.toml [default] dependency-operator ~ # 可选默认、、~此外rye add还提供--pin参数在单次命令中覆盖该默认值可选值为equal、tilde-equal~、greater-than-equal并支持、~、、exact、compatible等别名见 rye/src/cli/add.rsrye add Flask --pintilde-equal # 写入 flask~解析版本从源码看解析出的版本约束还会做两个细节处理rye/src/cli/add.rs对带本地版本号local version的版本强制使用当~目标版本只有一位 release 时降级为。extras 特性依赖feature / extraPython 包通常提供可选的 extras特性Rye 支持两种等价写法rye add Flask[dotenv] # 直接在 PEP 508 字符串中声明 rye add Flask --featuresdotenv # 使用 --features 参数--features参数在源码中按逗号切分并去重后合并进需求的extras字段rye/src/cli/add.rs因此也支持一次传入多个特性rye add Flask --featuresdotenv,async两种写法最终写入project.dependencies的效果一致例如flask[dotenv]3.0.0。测试 test_add_flask_dotenv 证实添加flask[dotenv]后解析结果中会额外安装python-dotenv。关于预发布版本pre-releases的重要提示默认情况下rye add不会考虑预发布版本。如果你添加的依赖在版本号中带有.dev、rc等预发布标识将无法解析到匹配项。此时需要显式传入--prerye add Flask2.0.0rc2 --pre从源码看--pre会一路传递给 uv 解析器uv.resolve(..., pre, ...)见 rye/src/cli/add.rs控制其是否允许预发布匹配。开发依赖Development Dependencies只用于开发阶段如格式化、静态检查工具的依赖用--dev添加rye add --dev black开发依赖不会被写入标准的project.dependencies而是存放在 Rye 私有的tool.rye.dev-dependencies键中pyproject.md[tool.rye] dev-dependencies [black~23.3.0]对应的源码映射见 rye/src/pyproject.rs--dev时add_dependency会往tool.rye表的dev-dependencies数组追加条目不存在则自动创建。测试 test_add_dev 展示了pyproject.toml中tool.rye表的最终形态。用rye run运行开发工具开发依赖默认随rye sync安装进虚拟环境但不需要手动激活虚拟环境即可运行其中的工具——直接用rye runrye run blackrye run会优先在虚拟环境中查找并执行对应命令这一机制同样适用于 tool.rye.scripts 中注册的自定义脚本。若希望sync时不安装开发依赖可传--no-dev详见 sync.md。排除依赖Excluded Dependenciestool.rye.excluded-dependencies是一个特殊键其中的依赖永远不会被安装即使它们作为间接依赖子依赖被拉取进来。使用rye add --excluded自动添加rye add --excluded cffi[tool.rye] excluded-dependencies [cffi]在源码中DependencyKind::Excluded与Dev一样写入tool.rye表rye/src/pyproject.rs且--excluded与--dev、--optional互斥rye/src/cli/add.rs。这一功能在项目与某个传递依赖存在兼容性冲突时非常实用。可选依赖组Optional Dependency Groups通过--optional可以将依赖加入标准project.optional-dependencies下的命名分组rye add --optionalweb flask写入后的 TOML[project.optional-dependencies] web [flask3.0.0]该分组在rye lock/rye sync时可通过--featuresweb启用参见 sync.md 的--features说明。源码中--optional与--dev、--excluded互斥且会创建project.optional-dependencies表及对应分组rye/src/pyproject.rs。Git / 本地路径依赖当依赖来自 Git 仓库或本地目录时可以传--git、--url、--path参数无需在需求字符串里手工拼接rye add Flask --githttps://github.com/pallets/flask rye add My-Utility --path ./my-utility rye add pip --urlhttps://example.com/pip-1.3.1.zip注意使用这些参数时必须同时提供包名--path/--git/--url与一次传多个需求不兼容源码中对此有显式校验见 rye/src/cli/add.rs。且这些参数会与需求字符串中已有的版本约束冲突——如果需求已经带有版本标记会直接报错requirement already has a version markerrye/src/cli/add.rs。Git 依赖的 tag / rev / branchGit 依赖支持额外的定位参数rye add Flask --githttps://github.com/pallets/flask --tag3.0.0 rye add Flask --githttps://github.com/pallets/flask --revabc1234 rye add Flask --githttps://github.com/pallets/flask --branchmain源码实现中rye/src/cli/add.rs--rev、--tag、--branch三选一互斥拼接为giturlref形式的 URL--tag/--rev/--branch均要求同时存在--git。测试输出示例$ rye add flask --git https://github.com/pallets/flask Added flask githttps://github.com/pallets/flask as regular dependency本地路径依赖与--absolute--path依赖最终会写成file://URL。默认情况下 Rye 会尝试生成基于${PROJECT_ROOT}的相对路径以便项目迁移但当构建后端为 hatchling其{root:uri}写法不被 uv 支持或显式传入--absolute时会强制生成绝对路径rye/src/cli/add.rs。--absolute需要同时传入--pathrye add My-Utility --path ./my-utility --absolute本地依赖强烈建议配合 workspace当项目依赖本地包时官方指南强烈建议将其配置为 workspace 成员。workspace 让子目录中的 Python 项目共享同一个虚拟环境与锁文件从而保证本地依赖与主项目在解析、安装时的一致性。配置方式详见 workspaces.md[tool.rye.workspace] members [mylib-*]移除依赖与添加对称的是rye remove命令参考见 remove.mdrye remove flask rye remove black --dev # 移除开发依赖 rye remove flask --optionalweb # 移除可选分组依赖它会从pyproject.toml对应的依赖列表中删除条目rye/src/pyproject.rs 中的remove_dependency与add_dependency使用相同的键位映射。与add一样是否立即同步安装状态取决于 auto-sync 设置。自动同步auto-sync与--sync/--no-syncrye add/rye remove之后依赖是否立刻被安装由全局配置behavior.autosync默认开启决定rye/src/config.rs若 auto-sync 关闭添加依赖后不会自动安装需要手动rye sync或本次命令显式传--sync若 auto-sync 开启但本次不想同步可传--no-sync--sync与--no-sync互斥见 rye/src/cli/add.rs。rye add flask --sync # 即使 auto-sync 关闭也立即同步 rye add flask --no-sync # 即使 auto-sync 开启也跳过同步从execute主流程看rye/src/cli/add.rs同步条件为(autosync !no_sync) || sync满足时调用autosync完成锁文件生成与虚拟环境安装。所谓同步本质是更新两份锁文件requirements.lock与requirements-dev.lock并用它们重建虚拟环境锁定的完整参数说明见 sync.md。从源码理解rye add的完整调用链汇总rye add的底层链路便于读者深入阅读仓库参数解析Args与ReqExtras结构体定义全部命令行参数及互斥/依赖关系rye/src/cli/add.rs需求构造Requirement::from_str解析 PEP 508 字符串ReqExtras::apply_to_requirement应用--git/--url/--path/--featuresrye/src/cli/add.rs版本解析resolve_requirements_with_uv通过内置 uv 解析器找到最新兼容版本并按默认操作符生成版本约束rye/src/cli/add.rs写入 TOMLPyProject::add_dependency按DependencyKind写入对应键位rye/src/pyproject.rs自动同步按 auto-sync 配置调用autosync完成 lock install。完整的行为快照含真实输出、最终 TOML 内容可在测试文件 rye/tests/test_add.rs 中逐一验证覆盖普通依赖、extras、dev 依赖、显式版本、URL 依赖、自定义 sources 等场景是学习rye add语义的最佳参考。小结普通依赖rye add 包名写入project.dependencies支持 PEP 508 版本约束与--pin定制操作符特性依赖PEP 508 的[extra]写法与--features等价开发依赖--dev写入tool.rye.dev-dependencies用rye run免激活运行排除/可选依赖--excluded、--optional 组名对应tool.rye.excluded-dependencies与project.optional-dependenciesGit/本地依赖--git配--tag/--rev/--branch、--url、--path配--absolute本地依赖建议纳入 workspace同步控制受autosync全局配置影响可用--sync/--no-sync覆盖单次行为。完整命令参数清单可参考 add.md配置文件各键的权威解释见 pyproject.md。【免费下载链接】ryea Hassle-Free Python Experience项目地址: https://gitcode.com/gh_mirrors/ry/rye创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考