Rye Python 项目管理¶

# Linux/macOS 安装 Rye
curl -sSf https://rye.astral.sh/get | bash

# 安装后重新加载 shell 配置
source "$HOME/.rye/env"  # 或重启终端

# 验证安装
rye --version  # 应输出 rye 0.x.x

# 安装 uv（Rye 的官方继任者）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或通过 pip 安装
pip install uv

# 验证
uv --version  # 应输出 uv 0.x.x

# Windows PowerShell 安装 Rye
winget install astral-sh.rye

# 或者安装 uv
winget install astral-sh.uv

# 查看当前配置
rye config

# 设置默认的 Python 版本
rye config --set-bool behavior.use-uv=true  # 使用 uv 作为后端（更快）

# 设置自动安装 Python
rye config --set-bool behavior.global-python=true

# 创建普通项目
rye init my-project               # 初始化项目目录
cd my-project

# 项目结构说明：
# my-project/
#   ├── pyproject.toml            # 项目配置文件（类似 package.json）
#   ├── .python-version           # 记录 Python 版本
#   ├── src/
#   │   └── my_project/           # 源代码目录
#   │       └── __init__.py
#   └── README.md

# 创建库项目（可发布到 PyPI 的包）
rye init my-lib --lib             # 创建库模板

# 创建不含 src 目录的扁平项目
rye init my-script --no-src       # 更简单的脚本项目

# 查看可用的 Python 版本
rye fetch --list                  # 列出所有可安装的 Python 版本

# 安装特定版本
rye fetch 3.12.3                  # 下载 Python 3.12.3

# 固定项目的 Python 版本
rye pin 3.12                      # 写入 .python-version 文件
rye pin 3.11.9                    # 精确版本

# 查看当前项目使用的 Python
rye run python --version          # 显示虚拟环境中的 Python 版本

# 添加生产依赖
rye add pandas                    # 添加最新版本
rye add "pandas>=2.0"             # 指定版本约束
rye add numpy scipy               # 一次添加多个

# 添加开发依赖（不打包到发布版本）
rye add pytest --dev              # 测试工具
rye add black ruff --dev          # 代码格式化和 lint 工具

# 移除依赖
rye remove pandas                 # 删除依赖

# 同步安装（根据 pyproject.toml 安装/更新所有依赖）
rye sync                          # 等价于 pip install -r requirements.txt

# 仅安装生产依赖（不安装 --dev 依赖）
rye sync --no-dev                 # 适合部署时使用

# 更新依赖到最新版本
rye lock --update-all             # 更新 lock 文件
rye sync                          # 根据新 lock 文件安装

# 在虚拟环境中运行
rye run python script.py          # 运行 Python 脚本
rye run pytest                    # 运行测试
rye run python -m mymodule        # 运行模块

# 激活虚拟环境（传统方式）
. .venv/bin/activate              # Linux/macOS
.venv\Scripts\activate            # Windows

# 代码质量工具
rye fmt                           # 格式化代码（使用 ruff）
rye lint                          # 检查代码问题（使用 ruff）
rye test                          # 运行测试（使用 pytest）

# 这是 Rye 项目的核心配置文件
[project]
name = "my-project"                    # 项目名称
version = "0.1.0"                      # 版本号
description = "A sample project"       # 描述
readme = "README.md"                   # README 文件
license = { text = "MIT" }            # 许可证
requires-python = ">=3.11"             # Python 版本要求
dependencies = [                       # 生产依赖列表
    "pandas>=2.0",
    "numpy>=1.24",
]

[tool.rye]
managed = true                         # 由 Rye 管理（标志位）
dev-dependencies = [                   # 开发依赖
    "pytest>=7.0",
    "ruff>=0.1",
    "black>=23.0",
]

[build-system]
requires = ["hatchling"]               # 构建工具
build-backend = "hatchling.build"

[tool.rye.scripts]
# 自定义脚本（类似 npm scripts）
start = "python src/my_project/main.py"   # rye run start
test = "pytest tests/"                     # rye run test
lint = "ruff check src/"                   # rye run lint

# 安装全局命令行工具（不污染项目环境）
rye tools install black            # 安装 black 格式化工具
rye tools install httpie           # 安装 http 命令行工具

# 查看已安装的全局工具
rye tools list

# 卸载全局工具
rye tools uninstall black

# 在 pyproject.toml 中配置工作区（Monorepo 模式）
# 适合同时管理多个互相依赖的 Python 包

# pyproject.toml 根项目配置
[tool.rye.workspace]
members = ["packages/*"]           # 所有 packages/ 下的子目录都是工作区成员

# 在 pyproject.toml 中配置私有源
[[tool.rye.sources]]
name = "private-pypi"
url = "https://pypi.example.com/simple/"
type = "index"

# 或者使用国内镜像（加速下载）
[[tool.rye.sources]]
name = "tuna"
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
type = "index"

# 构建发布包
rye build                         # 生成 dist/ 目录下的 wheel 和 sdist

# 发布到 PyPI
rye publish                       # 需要 PyPI 账号和 token

# 发布到测试 PyPI
rye publish --repository testpypi --yes

# 第一步：安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 第二步：进入现有 Rye 项目
cd my-rye-project

# 第三步：直接运行 uv（它能识别 Rye 的 pyproject.toml）
uv sync                           # 等同于 rye sync

# 验证迁移成功
uv run python -c "import pandas; print('迁移成功！')"

# 旧的 Rye 格式（dev-dependencies 在 tool.rye 下）
[tool.rye]
dev-dependencies = [
    "pytest>=7.0",
]

# 新的标准格式（推荐，uv 和其他工具通用）
[dependency-groups]
dev = [
    "pytest>=7.0",
]

# 私有源配置变化：从 tool.rye.sources 变为 tool.uv.indexes
[[tool.uv.indexes]]               # uv 的格式
name = "tuna"
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"

# ===== Rye 常用命令 =====

# 项目管理
rye init <name>            # 创建新项目
rye sync                   # 同步安装所有依赖
rye sync --no-dev          # 仅安装生产依赖

# 依赖管理
rye add <pkg>              # 添加依赖
rye add <pkg> --dev        # 添加开发依赖
rye add "<pkg>>=1.0"       # 添加带版本约束的依赖
rye remove <pkg>           # 移除依赖
rye lock                   # 更新 lock 文件
rye lock --update-all      # 更新所有依赖到最新

# Python 版本
rye fetch --list           # 查看可用版本
rye fetch 3.12             # 下载 Python 3.12
rye pin 3.12               # 固定项目 Python 版本

# 运行
rye run <cmd>              # 在虚拟环境中运行
rye run python script.py   # 运行脚本
rye run pytest             # 运行测试

# 代码质量
rye fmt                    # 格式化（ruff）
rye lint                   # 检查（ruff）

# 全局工具
rye tools install <pkg>    # 安装全局工具
rye tools list             # 列出全局工具
rye tools uninstall <pkg>  # 卸载全局工具

# ===== Rye → uv 迁移速查 =====

# Rye 命令              uv 等效命令
# rye init              uv init
# rye add <pkg>         uv add <pkg>
# rye add <pkg> --dev   uv add <pkg> --dev
# rye remove <pkg>      uv remove <pkg>
# rye sync              uv sync
# rye run <cmd>         uv run <cmd>
# rye pin 3.12          uv python pin 3.12
# rye fetch 3.12        uv python install 3.12
# rye fmt               uvx ruff format .
# rye lint              uvx ruff check .
# rye build             uv build
# rye publish           uv publish