Ruff代码检查 — Ruff超快Python linter¶

# 方法1：用 uv 安装（推荐，最快）
uv tool install ruff@latest

# 方法2：用 pip 安装
pip install ruff

# 方法3：用 pipx 安装（隔离环境）
pipx install ruff

# 方法4：用 Homebrew 安装（macOS）
brew install ruff

# 验证安装
ruff --version  # 应该显示 ruff 0.15.x
ruff check --help  # 查看检查命令帮助

[tool.ruff]
target-version = "py311"      # 目标 Python 版本
line-length = 88              # 每行最大字符数（和 Black 一致）
src = ["src", "tests"]        # 源码目录

[tool.ruff.lint]
select = [                    # 启用的规则集
    "E",     # pycodestyle 错误（PEP8 风格）
    "F",     # pyflakes（未使用变量、导入等）
    "W",     # pycodestyle 警告
    "I",     # isort（导入排序）
    "N",     # pep8-naming（命名规范）
    "UP",    # pyupgrade（升级老语法）
    "B",     # flake8-bugbear（常见 bug 模式）
    "SIM",   # flake8-simplify（简化代码）
    "RUF",   # Ruff 自有规则
]
ignore = [                    # 忽略的规则
    "E501",  # 行太长（交给 formatter 处理）
]
fixable = ["ALL"]             # 所有规则都可自动修复

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]      # __init__.py 允许未使用的导入
"tests/**" = ["S101"]         # 测试文件允许用 assert

[tool.ruff.format]
quote-style = "double"        # 双引号
indent-style = "space"        # 用空格缩进
line-ending = "auto"          # 自动检测换行符

# ===== 代码检查（Lint） =====
ruff check .                  # 检查当前目录所有 Python 文件
ruff check src/               # 只检查 src 目录
ruff check main.py            # 检查单个文件

# 自动修复
ruff check --fix .            # 自动修复能修的问题
ruff check --fix --unsafe-fixes .  # 包括"不太安全"的修复

# 查看具体规则说明
ruff rule E501                # 查看 E501 规则的详细说明

# ===== 代码格式化（Format） =====
ruff format .                 # 格式化所有文件
ruff format --check .         # 只检查格式，不修改（CI 用）
ruff format --diff .          # 显示格式差异但不修改

# ===== 导入排序 =====
ruff check --select I --fix . # 只修复导入排序问题

src/main.py:10:1: F401 [*] `os` imported but unused
src/main.py:15:5: E711 Comparison to `None` (use `is None`)
src/utils.py:23:1: I001 [*] Import block is un-sorted or un-formatted
Found 3 errors (2 fixable)

# Ruff 一个工具替代这些：
# Flake8     → ruff check（代码检查）
# Black      → ruff format（代码格式化）
# isort      → ruff check --select I（导入排序）
# pyupgrade  → ruff check --select UP（语法升级）
# autoflake  → ruff check --select F（移除未使用导入）
# pydocstyle → ruff check --select D（文档字符串检查）

# 从 Flake8 迁移：一行命令
# Ruff 支持绝大多数 Flake8 规则，编号完全一样
# 直接把 .flake8 配置转到 pyproject.toml 即可

# 传统方式：每行都要加 noqa
x = some_func(A, B, C)  # noqa: N803
y = some_func(D, E, F)  # noqa: N803

# 新方式：块级抑制（Ruff 2026 新增）
# ruff: disable[N803]
x = some_func(A, B, C)  # 这个范围内 N803 不报错
y = some_func(D, E, F)
# ruff: enable[N803]

# 文件级抑制
# ruff: file-ignore[E501]  # 整个文件忽略 E501

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4          # 拉取代码
      - uses: astral-sh/ruff-action@v3    # 官方 GitHub Action
        with:
          args: "check --output-format=github"  # 检查并标注在 PR 中
      - uses: astral-sh/ruff-action@v3
        with:
          args: "format --check"                # 检查格式

// .vscode/settings.json
{
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",  // 用 Ruff 格式化
        "editor.formatOnSave": true,                       // 保存时自动格式化
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",              // 保存时自动修复
            "source.organizeImports.ruff": "explicit"      // 保存时排序导入
        }
    }
}

# 规则集编号 → 对应原工具 → 检查内容
# E/W  → pycodestyle  → PEP8 代码风格
# F    → pyflakes     → 逻辑错误（未使用变量等）
# I    → isort        → 导入排序
# N    → pep8-naming  → 命名规范
# UP   → pyupgrade    → Python 版本升级建议
# B    → bugbear      → 常见 bug 模式
# SIM  → simplify     → 代码简化建议
# C4   → comprehensions → 推导式优化
# DTZ  → datetimez    → datetime 时区问题
# S    → bandit       → 安全问题
# RUF  → Ruff 原创    → Ruff 自有规则

# ===== 检查命令 =====
ruff check .                       # 检查所有文件
ruff check --fix .                 # 自动修复
ruff check --select E,F,I .        # 只检查指定规则
ruff check --ignore E501 .         # 忽略指定规则
ruff check --statistics .          # 按规则统计错误数
ruff check --output-format=json .  # JSON 输出

# ===== 格式化命令 =====
ruff format .                      # 格式化
ruff format --check .              # 检查格式（CI 用）
ruff format --diff .               # 显示差异

# ===== 其他命令 =====
ruff rule E501                     # 查看规则说明
ruff linter                        # 列出所有可用 linter
ruff clean                         # 清除缓存

# ===== 行内注释 =====
x = 1  # noqa: E501               # 本行忽略 E501
# ruff: noqa: E501                 # 本行以下忽略 E501
# type: ignore                     # 忽略类型检查