linting

Ruff 代码检查

Ruff 是一款速度极快的 Python 代码检查工具，旨在直接替代 Flake8（以及数十个插件）、isort、pydocstyle、pyupgrade、autoflake 等工具。它使用 Rust 编写，性能比传统 Python 代码检查工具快 10–100 倍。

概述

Ruff 提供统一的 CLI，用于代码检查，并可选择自动修复。它支持丰富的规则集，内置 800 多条规则，还能与 pre-commit、CI 系统和现代编辑器无缝集成。

主要功能

• 速度极快：比 Flake8、Black、isort 快 10–100 倍
• 直接替代：兼容现有的 Flake8 插件和配置
• 支持自动修复：自动修复许多常见问题
• 规则全面：整合热门代码检查工具的 800 多条内置规则
• 单一工具：可替代 flake8、isort、pyupgrade、autoflake、pydocstyle 等工具

适用场景

• 在项目或团队中统一代码质量标准
• 在 CI/CD 流水线中强制执行一致的编码规则
• 用单一的高速解决方案替代多个代码检查工具
• 自动修复常见的代码风格问题
• 从 Flake8、isort 或其他旧版代码检查工具迁移

快速开始

# Install Ruff
uv pip install ruff
# or
pip install ruff

# Run linting on current directory
ruff check .

# Run linting with auto-fix
ruff check . --fix

# Watch mode for development
ruff check --watch

核心模式

1. 从最小规则集开始：先启用 E 和 F 规则，再逐步扩展
2. 安全地自动修复：使用 ruff check --fix 仅应用安全修复
3. 按文件忽略规则：仅用于生成的代码或特殊情况
4. 集成 CI：在 GitHub Actions 中使用 ruff check --output-format github
5. 单一事实来源：通过 pyproject.toml 或 ruff.toml 进行配置

规则选择

Ruff 使用代码系统，每条规则由 1–3 个字母的前缀和数字组成（例如 F401）。规则通过 lint.select、lint.extend-select 和 lint.ignore 控制。

推荐规则集

最小规则集（从这里开始）：

[tool.ruff.lint]
select = ["E", "F"]  # pycodestyle errors + Pyflakes

均衡规则集（推荐）：

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "F",    # Pyflakes
    "UP",   # pyupgrade
    "B",    # flake8-bugbear
    "SIM",  # flake8-simplify
    "I",    # isort
]

全面规则集：

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # Pyflakes
    "UP",   # pyupgrade
    "B",    # flake8-bugbear
    "SIM",  # flake8-simplify
    "I",    # isort
    "N",    # pep8-naming
    "S",    # flake8-bandit (security)
    "C4",   # flake8-comprehensions
    "DTZ",  # flake8-datetimez
    "T20",  # flake8-print
    "RUF",  # Ruff-specific rules
]
ignore = ["E501"]  # Line too long (handled by formatter)

规则优先级

CLI 选项优先于 pyproject.toml，而 pyproject.toml 优先于继承的配置：

1. CLI（--select、--ignore）——优先级最高
2. 当前的 pyproject.toml
3. 继承的 pyproject.toml 文件

有关规则配置的详细信息，请参阅 references/rule_selection.md。

配置

pyproject.toml（推荐）

[tool.ruff]
line-length = 88
target-version = "py311"
exclude = [".venv", "dist", "build", "*.pyi"]

[tool.ruff.lint]
select = ["E", "F", "UP", "B", "SIM", "I"]
ignore = ["E501"]
fixable = ["ALL"]
unfixable = []

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101"]      # Allow assert in tests
"__init__.py" = ["F401"]         # Allow unused imports
"**/{tests,docs,tools}/*" = ["E402"]  # Allow late imports

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

[tool.ruff.lint.pydocstyle]
convention = "google"

ruff.toml 替代方案

line-length = 88
target-version = "py311"

[lint]
select = ["E", "F", "UP", "B", "SIM", "I"]
ignore = ["E501"]

[lint.per-file-ignores]
"tests/**/*.py" = ["S101"]

修复安全性

Ruff 将修复分为安全和不安全两类：

类型	行为	默认状态
安全	保留代码语义	已启用
不安全	可能改变运行时行为	已禁用

# Apply only safe fixes (default)
ruff check --fix

# Apply all fixes including unsafe
ruff check --fix --unsafe-fixes

# Show what unsafe fixes are available
ruff check --unsafe-fixes

调整修复安全性

[tool.ruff.lint]
# Promote unsafe fixes to safe
extend-safe-fixes = ["F601"]

# Demote safe fixes to unsafe
extend-unsafe-fixes = ["UP034"]

# Control which rules can be fixed
fixable = ["ALL"]
unfixable = ["F401"]  # Never auto-fix unused imports

有关修复安全性的详细文档，请参阅 references/fix_safety.md。

错误抑制

行级（noqa）

x = 1  # noqa: F841           # Ignore specific rule
i = 1  # noqa: E741, F841     # Ignore multiple rules
x = 1  # noqa                  # Ignore all rules (avoid this)

文件级

# ruff: noqa                   # Ignore all rules in file
# ruff: noqa: F841             # Ignore specific rule in file

代码块级（预览模式）

# ruff: disable[E501]
VALUE_1 = "Very long string..."
VALUE_2 = "Another long string..."
# ruff: enable[E501]

有关抑制模式的详细信息，请参阅 references/error_suppression.md。

CLI 命令

# Basic linting
ruff check .                           # Lint current directory
ruff check path/to/file.py             # Lint specific file
ruff check . --fix                     # Lint and auto-fix
ruff check . --fix --unsafe-fixes      # Include unsafe fixes

# Output formats
ruff check . --output-format text      # Default human-readable
ruff check . --output-format github    # GitHub Actions annotations
ruff check . --output-format json      # JSON output
ruff check . --output-format sarif     # SARIF format

# Inspection
ruff check . --diff                    # Show what would change
ruff check . --show-fixes              # Show available fixes
ruff check . --statistics              # Show rule statistics
ruff rule F401                         # Explain a specific rule

# Development
ruff check --watch                     # Watch mode
ruff check . --add-noqa                # Add noqa comments
ruff check . --extend-select RUF100    # Find unused noqa comments

退出代码

代码	含义
0	未发现违规，或所有违规均已修复
1	发现违规
2	配置错误或内部错误

修改退出行为：

ruff check . --exit-zero               # Always exit 0
ruff check . --exit-non-zero-on-fix    # Exit 1 if any violations (even if fixed)

CI 集成

GitHub Actions

name: Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3
        with:
          args: "check --output-format github"

Pre-commit

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

故障排查

问题	解决方案
规则与格式化工具冲突	使用 ruff format 时忽略格式规则（E501）
违规过多	从最小规则集（E、F）开始，逐步扩展
按文件忽略规则过多	检查规则选择，考虑禁用容易产生噪声的规则
大型代码库运行缓慢	确保排除 .venv，并检查是否存在递归符号链接
noqa 不起作用	检查语法：# noqa: F401（必须有冒号）

Common Rule Prefixes

Prefix	Source	Description
E/W	pycodestyle	Style errors/warnings
F	Pyflakes	Logical errors
B	flake8-bugbear	Common bugs
I	isort	Import sorting
UP	pyupgrade	Python version upgrades
SIM	flake8-simplify	Code simplification
N	pep8-naming	Naming conventions
S	flake8-bandit	Security issues
C4	flake8-comprehensions	Comprehension style
RUF	Ruff	Ruff-specific rules

References

• Quickstart Guide
• Rule Selection Reference
• Fix Safety Guide
• Error Suppression Patterns
• Common Pitfalls
• Official Documentation
• Full Rules Reference