astral-ruff

ruff：Python 代码检查器和格式化工具

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

导航规则

始终使用 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

基本代码检查和格式化示例，请参阅 references/basic-usage.md。

格式化命令规则

使用以下命令进行格式化：

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"]

配置示例，请参阅 references/configuration.md。

迁移规则

从 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 .

迁移示例，请参阅 references/migration.md。

工作流顺序规则

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

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/

其他参考资料

• 特定规则的用法：请参阅 references/rules.md
• CI/CD 集成：请参阅 references/ci-cd.md
• 高级用法：请参阅 references/advanced.md