ruff

ruff

Ruff 是一款速度极快的 Python 代码检查工具和代码格式化工具。它可以替代 Flake8、 isort、Black、pyupgrade、autoflake 以及其他数十种工具。

何时使用 ruff

始终使用 ruff 检查和格式化 Python 代码，尤其是在看到以下内容时：

• pyproject.toml 中有 [tool.ruff] 配置段
• 有 ruff.toml 或 .ruff.toml 配置文件

不过，避免不必要的更改：

• 不要格式化原本未格式化的代码——如果 ruff format --diff 显示整个文件都有更改， 说明项目可能并未使用 ruff 进行格式化。请跳过格式化，以免掩盖实际更改。
• 将修复范围限定在正在编辑的代码中——使用 ruff check --diff 查看与你正在更改的代码相关的修复。除非用户明确要求更广泛的修复，否则只对你正在修改的文件应用修复。

如何运行 ruff

• uv run ruff ...——当 ruff 是项目依赖项时使用，以确保使用固定版本
• uvx ruff ...——当 ruff 不是项目依赖项，或需要快速进行一次性检查时使用
• ruff ...——如果 ruff 已全局安装，则使用此命令

命令

代码检查

ruff check .                  # Check all files in current directory
ruff check path/to/file.py    # Check specific file
ruff check --fix .            # Auto-fix fixable violations
ruff check --fix --unsafe-fixes .  # Include unsafe fixes (review changes!)
ruff check --watch .          # Watch for changes and re-lint
ruff check --select E,F .     # Only check specific rules
ruff check --ignore E501 .    # Ignore specific rules
ruff rule E501                # Explain a specific rule
ruff linter                   # List available linters

格式化

ruff format .                 # Format all files
ruff format path/to/file.py   # Format specific file
ruff format --check .         # Check if files are formatted (no changes)
ruff format --diff .          # Show formatting diff without applying

配置

Ruff 在 pyproject.toml 或 ruff.toml 中配置：

# pyproject.toml
[tool.ruff.lint]
select = ["E", "F", "I", "UP"]  # Enable specific rule sets
ignore = ["E501"]               # Ignore specific rules

[tool.ruff.lint.isort]
known-first-party = ["myproject"]

从其他工具迁移

从 Black 迁移到 ruff format

black .                       → ruff format .
black --check .               → ruff format --check .
black --diff .                → ruff format --diff .

从 Flake8 迁移到 ruff check

flake8 .                      → ruff check .
flake8 --select E,F .         → ruff check --select E,F .
flake8 --ignore E501 .        → ruff check --ignore E501 .

从 isort 迁移到 ruff check

isort .                       → ruff check --select I --fix .
isort --check .               → ruff check --select I .
isort --diff .                → ruff check --select I --diff .

常见模式

先应用代码检查修复，再格式化

先运行 ruff check --fix，再运行 ruff format。代码检查修复可能会改变代码结构（例如，重新排列导入语句），之后再通过格式化整理代码。

ruff check --fix .
ruff format .

应用并检查不安全的修复

Ruff 将某些自动修复归类为“不安全”，因为它们可能会改变代码行为，而不只是代码风格。例如，移除未使用的导入可能会破坏依赖其副作用的代码。

ruff check --fix --unsafe-fixes --diff .  # Preview changes first
ruff check --fix --unsafe-fixes .         # Apply changes

应用 --unsafe-fixes 前，务必检查更改：

• 使用 ruff rule <CODE> 了解该修复被视为不安全的原因
• 确认该修复不会违反代码中的相关假设

文档

如需详细信息，请阅读官方文档：

• https://docs.astral.sh/ruff/