modern-python

现代 Python

现代 Python 工具与最佳实践指南，基于 trailofbits/cookiecutter-python。

何时使用此技能

• 创建新的 Python 项目或包
• 设置 pyproject.toml 配置
• 配置开发工具（lint、格式化、测试）
• 编写使用外部依赖的 Python 脚本
• 从旧版工具迁移（用户提出请求时）

何时不使用此技能

• 用户希望保留旧版工具：如果用户明确提出，请尊重现有工作流
• 必须使用 Python < 3.11：这些工具面向现代 Python
• 非 Python 项目：Python 并非主要语言的混合代码库

应避免的反模式

避免使用	改用
[tool.ty] python-version	[tool.ty.environment] python-version
uv pip install	uv add 和 uv sync
手动编辑 pyproject.toml 添加依赖	uv add <pkg> / uv remove <pkg>
hatchling 构建后端	uv_build（更简单，足以应对大多数情况）
Poetry	uv（更快、更简单，生态集成更好）
requirements.txt	脚本使用 PEP 723，项目使用 pyproject.toml
mypy / pyright	ty（来自 Astral 团队，速度更快）
使用 [project.optional-dependencies] 管理开发工具	使用 [dependency-groups]（PEP 735）
手动激活虚拟环境（source .venv/bin/activate）	uv run <cmd>
pre-commit	prek（更快，无需 Python 运行时）

关键原则：

• 始终使用 uv add 和 uv remove 管理依赖
• 不要手动激活或管理虚拟环境——所有命令都使用 uv run
• 使用 [dependency-groups] 管理开发、测试和文档依赖，而不是 [project.optional-dependencies]

决策树

What are you doing?
│
├─ Single-file script with dependencies?
│   └─ Use PEP 723 inline metadata (./references/pep723-scripts.md)
│
├─ New multi-file project (not distributed)?
│   └─ Minimal uv setup (see Quick Start below)
│
├─ New reusable package/library?
│   └─ Full project setup (see Full Setup below)
│
└─ Migrating existing project?
    └─ See Migration Guide below

工具概览

工具	用途	替代
uv	包和依赖管理	pip、virtualenv、pip-tools、pipx、pyenv
ruff	lint 和格式化	flake8、black、isort、pyupgrade、pydocstyle
ty	类型检查	mypy、pyright（更快的替代方案）
pytest	带覆盖率的测试	unittest
prek	提交前钩子（设置）	pre-commit（更快，原生 Rust）

安全工具

工具	用途	运行时机
shellcheck	Shell 脚本 lint	pre-commit
detect-secrets	密钥检测	pre-commit
actionlint	工作流语法验证	pre-commit、CI
zizmor	工作流安全审计	pre-commit、CI
pip-audit	依赖漏洞扫描	CI、手动
Dependabot	自动更新依赖	定期计划

有关配置和用法，请参阅 security-setup.md。

快速入门：最小项目

适用于不打算发布的简单多文件项目：

# Create project with uv
uv init myproject
cd myproject

# Add dependencies
uv add requests rich

# Add dev dependencies
uv add --group dev pytest ruff ty

# Run code
uv run python src/myproject/main.py

# Run tools
uv run pytest
uv run ruff check .

完整项目设置

如果从头开始，请询问用户是否希望使用 Trail of Bits cookiecutter 模板来搭建完整项目，并预先配置好工具。

uvx cookiecutter gh:trailofbits/cookiecutter-python

1. 创建项目结构

uv init --package myproject
cd myproject

这将创建：

myproject/
├── pyproject.toml
├── README.md
├── src/
│   └── myproject/
│       └── __init__.py
└── .python-version

2. 配置 pyproject.toml

完整配置参考请参阅 pyproject.md。

主要部分：

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = []

[dependency-groups]
dev = [{include-group = "lint"}, {include-group = "test"}, {include-group = "audit"}]
lint = ["ruff", "ty"]
test = ["pytest", "pytest-cov"]
audit = ["pip-audit"]

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["ALL"]
ignore = ["D", "COM812", "ISC001"]

[tool.pytest]
addopts = ["--cov=myproject", "--cov-fail-under=80"]

[tool.ty.terminal]
error-on-warning = true

[tool.ty.environment]
python-version = "3.11"

[tool.ty.rules]
# Strict from day 1 for new projects
possibly-unresolved-reference = "error"
unused-ignore-comment = "warn"

3. 安装依赖

# Install all dependency groups
uv sync --all-groups

# Or install specific groups
uv sync --group dev

4. 添加 Makefile

.PHONY: dev lint format test build

dev:
	uv sync --all-groups

lint:
	uv run ruff format --check && uv run ruff check && uv run ty check src/

format:
	uv run ruff format .

test:
	uv run pytest

build:
	uv build

迁移指南

用户要求从旧版工具迁移时：

从 requirements.txt + pip 迁移

首先，确定代码的类型：

对于独立脚本：转换为 PEP 723 内联元数据（参阅 pep723-scripts.md）

对于项目：

# Initialize uv in existing project
uv init --bare

# Add dependencies using uv (not by editing pyproject.toml)
uv add requests rich  # add each package

# Or import from requirements.txt (review each package before adding)
# Note: Complex version specifiers may need manual handling
grep -v '^#' requirements.txt | grep -v '^-' | grep -v '^\s*$' | while read -r pkg; do
    uv add "$pkg" || echo "Failed to add: $pkg"
done

uv sync

然后：

1. 删除 requirements.txt、requirements-dev.txt
2. 删除虚拟环境（venv/、.venv/）
3. 将 uv.lock 纳入版本控制

从 setup.py / setup.cfg 迁移

1. 运行 uv init --bare 创建 pyproject.toml
2. 使用 uv add 添加 install_requires 中的每项依赖
3. 使用 uv add --group dev 添加开发依赖
4. 将非依赖元数据（名称、版本、描述等）复制到 [project]
5. 删除 setup.py、setup.cfg、MANIFEST.in

从 flake8 + black + isort 迁移

1. 使用 uv remove 移除 flake8、black、isort
2. 删除 .flake8、pyproject.toml [tool.black]、[tool.isort] 配置
3. 添加 ruff：uv add --group dev ruff
4. 添加 ruff 配置（参见 ruff-config.md）
5. 运行 uv run ruff check --fix . 应用修复
6. 运行 uv run ruff format . 进行格式化

从 mypy / pyright 迁移

1. 使用 uv remove 移除 mypy/pyright
2. 删除 mypy.ini、pyrightconfig.json 或 [tool.mypy]/[tool.pyright] 部分
3. 添加 ty：uv add --group dev ty
4. 运行 uv run ty check src/

快速参考：uv 命令

命令	描述
uv init	创建新项目
uv init --package	创建可分发的软件包
uv add <pkg>	添加依赖
uv add --group dev <pkg>	添加到依赖组
uv remove <pkg>	移除依赖
uv sync	安装依赖
uv sync --all-groups	安装所有依赖组
uv run <cmd>	在虚拟环境中运行命令
uv run --with <pkg> <cmd>	使用临时依赖运行命令
uv build	构建软件包
uv publish	发布到 PyPI

使用 --with 添加临时依赖

对于需要使用项目中未包含的软件包的一次性命令，请使用 uv run --with：

# Run Python with a temporary package
uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"

# Run a module with temporary deps
uv run --with rich python -m rich.progress

# Multiple packages
uv run --with requests --with rich python script.py

# Combine with project deps (adds to existing venv)
uv run --with httpx pytest  # project deps + httpx

何时使用 --with，何时使用 uv add：

• uv add：软件包是项目依赖（会写入 pyproject.toml/uv.lock）
• --with：一次性使用、测试，或在项目上下文之外运行脚本

完整参考请参见 uv-commands.md。

快速参考：依赖组

[dependency-groups]
dev = ["ruff", "ty"]
test = ["pytest", "pytest-cov", "hypothesis"]
docs = ["sphinx", "myst-parser"]

使用以下命令安装：uv sync --group dev --group test

最佳实践检查清单

• 软件包使用 src/ 布局
• 设置 requires-python = ">=3.11"
• 配置 ruff，使用 select = ["ALL"] 并明确指定忽略项
• 使用 ty 进行类型检查
• 强制执行最低测试覆盖率（80%+）
• 使用依赖组代替 extras 来管理开发工具
• 将 uv.lock 纳入版本控制
• 独立脚本使用 PEP 723

接下来阅读

• migration-checklist.md - 逐步完成迁移清理
• pyproject.md - 完整的 pyproject.toml 参考
• uv-commands.md - uv 命令参考
• ruff-config.md - Ruff lint/格式化配置
• testing.md - pytest 和覆盖率设置
• pep723-scripts.md - PEP 723 内联脚本元数据
• prek.md - 使用 prek 配置快速的提交前钩子
• security-setup.md - 安全钩子和依赖扫描
• dependabot.md - 自动更新依赖