用途
该技能是一份现代 Python 工具链与最佳实践指南,基于 Trail of Bits 的 cookiecutter-python 模板。它适用于以下情况:创建新的 Python 项目或包、配置 pyproject.toml、配置开发工具(lint、格式化、测试)、编写带外部依赖的 Python 脚本,以及在用户明确要求时从旧工具迁移。
不适合使用的情况:用户希望保留旧工具链(如明确要求时,应尊重现有工作流);项目要求 Python 3.11 以下版本(这些工具面向现代 Python);非 Python 项目或 Python 并非主要语言的混合代码库。
主要能力与工具概览
技能给出了工具替换关系:uv 用于包与依赖管理,替代 pip、virtualenv、pip-tools、pipx、pyenv;ruff 同时用于 lint 与格式化,替代 flake8、black、isort、pyupgrade、pydocstyle;ty 用于类型检查,是 mypy、pyright 的更快替代;pytest 用于带覆盖率的测试,替代 unittest;prek 用于 pre-commit 钩子,替代 pre-commit(更快、Rust 原生)。
安全工具包括:shellcheck 用于 shell 脚本 lint,detect-secrets 用于密钥检测(均在 pre-commit 运行);actionlint 用于工作流语法校验,zizmor 用于工作流安全审计(在 pre-commit、CI 运行);pip-audit 用于依赖漏洞扫描(CI 或手动);Dependabot 用于自动依赖更新(定时)。
关键原则与反模式
核心原则:始终用 uv add 和 uv remove 管理依赖;不要手动激活或管理虚拟环境,所有命令用 uv run;开发/测试/文档依赖用 [dependency-groups](PEP 735),而不是 [project.optional-dependencies]。
应避免的反模式(用前者替代后者):[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;用 [project.optional-dependencies] 管理开发工具应改为 [dependency-groups];手动激活虚拟环境应改为 uv run <cmd>;pre-commit 应改为 prek。
使用方式
决策路径:单文件脚本且带依赖,使用 PEP 723 内联元数据;新的多文件项目(不用于分发),使用最小 uv 设置;新的可复用包/库,使用完整项目设置;迁移已有项目,参考迁移指南。
最小项目快速开始:
uv init myproject
cd myproject
uv add requests rich
uv add --group dev pytest ruff ty
uv run python src/myproject/main.py
uv run pytest
uv run ruff check .
完整项目设置:若从零开始,可询问用户是否使用 Trail of Bits cookiecutter 模板引导完整项目:
uvx cookiecutter gh:trailofbits/cookiecutter-python
创建包结构:
uv init --package myproject
cd myproject
会生成 pyproject.toml、README.md、src/myproject/init.py 和 .python-version。
pyproject.toml 关键配置示例:
[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]
possibly-unresolved-reference = "error"
unused-ignore-comment = "warn"
安装依赖:
uv sync --all-groups
# 或
uv sync --group dev
可添加 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
常用 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 requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"
uv run --with rich python -m rich.progress
uv run --with requests --with rich python script.py
uv run --with httpx pytest
使用场景:uv add 用于项目依赖(写入 pyproject.toml/uv.lock);--with 用于一次性使用、测试或项目上下文之外的脚本。
依赖组示例:
[dependency-groups]
dev = ["ruff", "ty"]
test = ["pytest", "pytest-cov", "hypothesis"]
docs = ["sphinx", "myst-parser"]
安装:uv sync --group dev --group test。
迁移指南
从 requirements.txt + pip 迁移:先判断代码性质。独立脚本转为 PEP 723 内联元数据;项目则:
uv init --bare
uv add requests rich
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
随后删除 requirements.txt、requirements-dev.txt;删除虚拟环境(venv/、.venv/);将 uv.lock 加入版本控制。
从 setup.py / setup.cfg 迁移:运行 uv init --bare 创建 pyproject.toml;用 uv add 添加 install_requires 中每个依赖;用 uv add --group dev 添加开发依赖;将非依赖元数据(name、version、description 等)复制到 [project];删除 setup.py、setup.cfg、MANIFEST.in。
从 flake8 + black + isort 迁移:用 uv remove 移除三者;删除 .flake8、[tool.black]、[tool.isort] 配置;添加 ruff(uv add --group dev ruff);加入 ruff 配置;运行 uv run ruff check --fix . 和 uv run ruff format .。
从 mypy / pyright 迁移:用 uv remove 移除;删除 mypy.ini、pyrightconfig.json 或相关配置段;添加 ty(uv add --group dev ty);运行 uv run ty check src/。
最佳实践清单
使用 src/ 布局;设置 requires-python = ">=3.11";ruff 配置 select = ["ALL"] 并显式 ignore;使用 ty 做类型检查;强制测试覆盖率下限(80% 以上);开发工具使用依赖组而非 extras;将 uv.lock 加入版本控制;独立脚本使用 PEP 723。
限制与未提供信息
资料为工具链与配置指南,未提供收费、价格、平台支持范围、性能数据或效果承诺等信息;除明确列出的工具与命令外,其他功能与细节暂未提供。
引用文档
以下为作者声明的引用来源,保留指定版本、署名和许可。
- trailofbits/skills/plugins/modern-python/skills/modern-python/SKILL.md — 署名:Trail of Bits;许可:CC-BY-SA-4.0;版本:
5c15f4f5644b4bd3d48882a802a7232d501852b6。