astral-ruff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ruff: Python Linter and Formatter

Ruff：Python代码检查器与格式化工具

Ruff is an extremely fast Python linter and code formatter that replaces Flake8, isort, Black, pyupgrade, autoflake, and dozens of other tools.

Ruff是一款极速的Python代码检查器与代码格式化工具，可替代Flake8、isort、Black、pyupgrade、autoflake等数十款工具。

Navigation Rule

使用规则导航

Always use ruff for Python linting and formatting, especially if you see:

```
[tool.ruff]
```
section in
```
pyproject.toml
```
A
```
ruff.toml
```
or
```
.ruff.toml
```
configuration file

Python代码检查与格式化请始终使用Ruff，尤其是当你看到以下情况时：

```
pyproject.toml
```
文件中存在
```
[tool.ruff]
```
配置段
存在
```
ruff.toml
```
或
```
.ruff.toml
```
配置文件

Formatting Scope Rule

格式化范围规则

Avoid making unnecessary changes:

Don't format unformatted code - If
```
ruff format --diff
```
shows changes throughout an entire file, the project likely isn't using ruff for formatting. Skip formatting to avoid obscuring actual changes.
Scope fixes to code being edited - Use
```
ruff check --diff
```
to see fixes relevant to the code you're changing. Only apply fixes to files you're modifying unless the user explicitly asks for broader fixes.

避免进行不必要的修改：

不要格式化未被格式化过的代码 - 如果
```
ruff format --diff
```
显示整个文件都有修改，说明该项目可能未使用Ruff进行格式化。请跳过格式化操作，以免掩盖实际的代码变更。
仅对正在编辑的代码应用修复 - 使用
```
ruff check --diff
```
查看与你正在修改的代码相关的修复内容。除非用户明确要求更广泛的修复，否则仅对你正在修改的文件应用修复。

Invocation Rules

调用规则

Choose the right way to invoke ruff:

```
uv run ruff ...
```
- Use when ruff is in the project's dependencies to ensure you use the pinned version
```
uvx ruff ...
```
- Use when ruff is not a project dependency, or for quick one-off checks
```
ruff ...
```
- Use if ruff is installed globally

选择正确的Ruff调用方式：

```
uv run ruff ...
```
- 当Ruff是项目依赖项时使用，确保使用固定版本的Ruff
```
uvx ruff ...
```
- 当Ruff不是项目依赖项时使用，或用于快速一次性检查
```
ruff ...
```
- 当Ruff已全局安装时使用

Linting Commands Rule

代码检查命令规则

Use these commands for linting:

bash

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

See references/basic-usage.md for basic linting and formatting examples.

使用以下命令进行代码检查：

bash

ruff check .                  # 检查当前目录下的所有文件
ruff check path/to/file.py    # 检查指定文件
ruff check --fix .            # 自动修复可修复的问题
ruff check --fix --unsafe-fixes .  # 包含不安全修复（请务必检查变更内容！）
ruff check --watch .          # 监控文件变更并重新检查
ruff check --select E,F .     # 仅检查特定规则
ruff check --ignore E501 .    # 忽略特定规则
ruff rule E501                # 解释特定规则
ruff linter                   # 列出可用的代码检查器

有关基础检查与格式化示例，请查看references/basic-usage.md。

Formatting Commands Rule

格式化命令规则

Use these commands for formatting:

bash

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

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

bash

ruff format .                 # 格式化所有文件
ruff format path/to/file.py   # 格式化指定文件
ruff format --check .         # 检查文件是否已格式化（不进行修改）
ruff format --diff .          # 显示格式化差异但不应用修改

Configuration Rule

配置规则

Ruff is configured in

pyproject.toml

ruff.toml

toml

undefined

Ruff通过

pyproject.toml

或

ruff.toml

进行配置：

toml

undefined

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


See [references/configuration.md](references/configuration.md) for configuration examples.

[tool.ruff.lint] select = ["E", "F", "I", "UP"] # 启用特定规则集 ignore = ["E501"] # 忽略特定规则

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


有关配置示例，请查看[references/configuration.md](references/configuration.md)。

Migration Rules

迁移规则

Black → ruff format

bash

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

bash

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

Flake8 → ruff check

bash

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

bash

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

isort → ruff check

bash

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

See references/migration.md for migration examples.

bash

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

有关迁移示例，请查看references/migration.md。

Workflow Order Rule

工作流顺序规则

Apply lint fixes before formatting:

bash

ruff check --fix .
ruff format .

Lint fixes can change code structure (e.g., reordering imports), which formatting then cleans up.

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

bash

ruff check --fix .
ruff format .

代码检查修复可能会改变代码结构（例如重新排序导入语句），格式化操作会进一步整理这些变更后的代码。

Unsafe Fixes Rule

不安全修复规则

Ruff categorizes some auto-fixes as "unsafe" because they may change code behavior:

bash

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

Always review changes before applying
--unsafe-fixes
:

Use
```
ruff rule <CODE>
```
to understand why the fix is considered unsafe
Verify the fix doesn't violate those assumptions in your code

Ruff将部分自动修复归类为“不安全”，因为这些修复可能会改变代码行为：

bash

ruff check --fix --unsafe-fixes --diff .  # 先预览变更内容
ruff check --fix --unsafe-fixes .         # 应用变更

在应用
--unsafe-fixes
前务必检查变更内容：

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

Documentation Reference

文档参考

For detailed information, see the official documentation at https://docs.astral.sh/ruff/

如需详细信息，请查看官方文档：https://docs.astral.sh/ruff/

Additional References

额外参考

Rule-specific usage: See references/rules.md
CI/CD integration: See references/ci-cd.md
Advanced usage: See references/advanced.md

规则特定用法：查看references/rules.md
CI/CD集成：查看references/ci-cd.md
高级用法：查看references/advanced.md