入选理由:小样本即可核对诊断、修复与格式化,官方文档给出了规则配置与退出状态,补充指南目录中的 Python 代码质量实践。
入选:2026-11-07 · 资料核对:2026-11-07。根据官方资料整理,未进行安装与功能实测。
Ruff:让一次 Python 检查和格式化有可核对的结果
它解决什么问题
Ruff 可以检查 Python 源码中的静态问题,也能统一引号和空白等格式。这里用一个样本把两个步骤分开,先发现并移除未使用的导入,再检查并整理格式。学会读取检查结果后,可以把相同流程放到提交前或持续集成中。
适合谁,哪些情况不适合
经常维护 Python 脚本或团队仓库的人,可以先在单个文件上熟悉规则与格式选项。已有检查器的项目可以选取小目录试行,核对改动后再确定覆盖范围。需要验证程序输出、接口行为或类型时,还要运行项目测试或相应的类型检查工具。
环境与准备
示例使用 macOS 或 Linux 的终端,要求 python3 能创建带 pip 的虚拟环境。安装阶段需要能访问 Python 包索引。使用独立练习目录和虚拟环境,可以把示例文件和软件版本放在一起。Windows 用户可以按官方安装页选择相应安装方式,下面的路径与终端命令以 macOS 和 Linux 为例。
安装与第一次使用
1. 创建独立目录并安装。 本例固定为本次核对过发行说明的 0.17.4。以下命令在同一个终端执行。
workdir=$(mktemp -d) &&
cd "$workdir" &&
python3 -m venv .venv &&
.venv/bin/python -m pip install 'ruff==0.17.4' &&
.venv/bin/ruff --version
确认最后一条显示 Ruff 版本,再继续创建两个文件。ruff.toml 只选 F401,便于把未使用导入与其他规则区分开。
cat > ruff.toml <<'TOML'
[lint]
select = ["F401"]
TOML
cat > example.py <<'PY'
import math
print( "hello" )
PY
2. 先读诊断,再应用修复。 运行下面的检查,应在第一行看到 F401,表示导入的 math 没有被使用。此时可以打开文件确认。
.venv/bin/ruff check --config ruff.toml example.py
确认这行导入可以移除后,运行:
.venv/bin/ruff check --config ruff.toml --fix example.py
.venv/bin/ruff check --config ruff.toml example.py
第二次检查应通过,文件里应只剩打印语句及空白。真实项目可在修复前先查看规则和预期改动。
3. 检查格式并验证。 先用 --check 查看是否仍有格式差异,随后执行写回。
.venv/bin/ruff format --config ruff.toml --check example.py
.venv/bin/ruff format --config ruff.toml example.py
.venv/bin/ruff format --config ruff.toml --check example.py
cat example.py
.venv/bin/python example.py
第一次格式检查预计提示文件需要调整,最后一次应通过。源码应显示为 print("hello"),运行应输出 hello。这里的预期结果来自文档和示例,未把文档核对当作现场运行记录。
主要能力与典型场景
- 提交前排查。 对改动文件先运行 check,按诊断中的文件位置与规则编号处理问题。只对已确认的范围使用 --fix。
- 统一已有项目的格式。 先对小目录运行 format --check,确认差异后单独提交格式调整,便于审阅。
- 让团队用同一套设置。 把规则与目标 Python 版本写入项目配置,固定 CI 使用的 Ruff 版本。已有 pyproject.toml 的项目可在 tool.ruff.lint 下配置检查规则。
- 整理导入。 如果团队需要导入排序,可在检查配置中增加 I 系列规则,检查并修复后再格式化。格式化命令本身只处理版式。
常见问题与排错
- 检查没有出现 F401。 确认进入练习目录,文件中仍有 import math,且 --config 指向本例的 ruff.toml。也可用 check --show-settings 查看解析后的设置。
- 格式检查退出码为 1。 有文件需要格式化时,--check 会用非零状态提示差异。若配置无效或命令异常,格式化文档列出的退出码为 2。
- 终端与编辑器结果不同。 比对工具版本、目标文件和配置路径。嵌套项目可能命中更近的配置文件。
- 自动修复改了文件。 先看差异再决定是否保留。用于 CI 的格式检查可用 --check,仅报告状态。
费用、隐私与限制
Ruff 源码采用 MIT,本文命令在本地读取与检查源文件,无需模型账号或上传代码。安装软件包需要联网。自动修复和格式化会改写目标文件,使用前确认路径和工作区状态。规则诊断覆盖配置选定的问题,代码是否符合业务预期由项目测试核对。