Rye: Armin Ronacher 的 Python 项目管理工具¶

rye init          → 创建项目
rye pin 3.12      → 指定 Python 版本（Rye 自动下载）
rye add flask     → 添加依赖
rye sync          → 安装所有依赖到虚拟环境
rye run app       → 在虚拟环境中运行
rye build         → 构建包
rye publish       → 发布到 PyPI

my-project/
├── pyproject.toml            # 项目配置（核心文件）
├── requirements.lock         # 生产依赖锁文件
├── requirements-dev.lock     # 开发依赖锁文件
├── .python-version           # Python 版本（如 3.12.0）
├── .venv/                    # 虚拟环境（自动管理）
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
└── tests/
    └── test_main.py

curl -sSf https://rye.astral.sh/get | bash

# 按提示将 Rye 添加到 PATH
echo 'source "$HOME/.rye/env"' >> ~/.bashrc
# 或 Fish:
# echo 'source "$HOME/.rye/env.fish"' >> ~/.config/fish/config.fish

# 从官网下载安装程序
# https://rye.astral.sh
# 或使用 PowerShell
irm https://rye.astral.sh/get | iex

# 初始配置
rye config --set-bool behavior.global-python=true  # Rye 管理的 Python 作为全局默认
rye config --set-bool behavior.use-uv=true         # 使用 uv 作为安装器（更快）

[behavior]
global-python = true
use-uv = true

[default]
toolchain = "cpython@3.12"
build-system = "hatchling"

# 列出可用的 Python 版本
rye toolchain list --include-downloadable

# 安装特定版本
rye toolchain fetch 3.12
rye toolchain fetch 3.11

# 查看已安装的 Python
rye toolchain list

# 创建项目
rye init my-project
cd my-project

# 项目结构已自动创建
# 包含 pyproject.toml, src/, .python-version 等

# 自动生成的 pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
dependencies = []
readme = "README.md"
requires-python = ">= 3.11"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.backends"

# 添加生产依赖
rye add flask
rye add sqlalchemy
rye add "pydantic>=2.0"

# 添加开发依赖
rye add --dev pytest
rye add --dev ruff
rye add --dev mypy

# 同步（安装所有依赖）
rye sync

# 移除依赖
rye remove flask

# 设置项目 Python 版本
rye pin 3.12

# Rye 自动：
# 1. 下载 Python 3.12（如果没有）
# 2. 创建使用 3.12 的虚拟环境
# 3. 更新 .python-version 文件

# 在项目环境中运行
rye run python src/my_project/main.py

# 运行已安装的命令行工具
rye run pytest
rye run ruff check .
rye run mypy src/

# 进入项目的 Python Shell
rye run python

# pyproject.toml
[project.scripts]
serve = "my_project.main:main"

[tool.rye.scripts]
dev = "flask run --debug"
test = "pytest -v"
lint = { chain = ["ruff check .", "mypy src/"] }
format = "ruff format ."

rye run serve    # 运行 project.scripts 定义的入口
rye run dev      # 运行 tool.rye.scripts 定义的命令
rye run test     # 运行测试
rye run lint     # 链式执行 ruff + mypy

# 安装全局可用的工具（不依赖项目）
rye install ruff
rye install black
rye install httpie
rye install poetry  # 甚至可以安装其他包管理器

# 列出全局安装的工具
rye tools list

# 卸载全局工具
rye uninstall httpie

# 根目录 pyproject.toml
[tool.rye.workspace]
members = ["packages/*"]

# 目录结构
my-workspace/
├── pyproject.toml      # workspace 根配置
├── packages/
│   ├── core/
│   │   ├── pyproject.toml
│   │   └── src/core/
│   ├── api/
│   │   ├── pyproject.toml
│   │   └── src/api/
│   └── cli/
│       ├── pyproject.toml
│       └── src/cli/

# 同步整个 workspace
rye sync

# workspace 中的包可以互相依赖
# api/pyproject.toml 中:
# dependencies = ["core"]

# 生成/更新锁文件
rye lock

# 锁文件应该提交到 Git
# requirements.lock       — 生产依赖
# requirements-dev.lock   — 开发依赖

# 从锁文件安装（确定性安装）
rye sync

# 构建
rye build
# 输出: dist/my_project-0.1.0-py3-none-any.whl
# 输出: dist/my_project-0.1.0.tar.gz

# 发布到 PyPI
rye publish

# 发布到私有仓库
rye publish --repository-url https://private.pypi.org/simple/

# Rye 可以读取 Poetry 风格的 pyproject.toml
cd existing-poetry-project
rye sync  # Rye 自动识别依赖

# 然后用 rye 管理后续操作

# 初始化 Rye 项目
rye init my-project --no-pin
cd my-project

# 从 requirements.txt 导入
cat ../requirements.txt | xargs rye add

# 同步
rye sync

# Rye 可以使用 uv 作为底层安装器（更快）
rye config --set-bool behavior.use-uv=true

# uv 的等价命令
# rye init       → uv init
# rye add        → uv add
# rye sync       → uv sync
# rye run        → uv run
# rye lock       → uv lock
# rye build      → uv build
# rye publish    → uv publish

# Rye 自动在项目目录下创建 .venv
ls -la .venv/

# 大多数 IDE 会自动检测 .venv
# VS Code: 设置 Python Interpreter 指向 .venv/bin/python

# pyproject.toml
[[tool.rye.sources]]
name = "tuna"
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"

pip install -r requirements.lock