Ruff 完全指南：用 Rust 重写 Python 代码检查，比 Flake8 快 100 倍

# 方式 1：使用 pip（推荐）
pip install ruff

# 方式 2：使用 uv（更快）
uv tool install ruff

# 方式 3：macOS Homebrew
brew install ruff

# 方式 4：官方安装脚本
curl -LsSf https://astral.sh/ruff/install.sh | sh

# 验证安装
ruff --version
# 输出：ruff 0.9.x

import os
import sys
import json  # unused

def  hello_world():
    x=1+2
    print("hello world")
    return x

if __name__ == "__main__":
    hello_world()

ruff check hello.py

hello.py:1:8: F401 [*] `os` imported but unused
hello.py:2:8: F401 [*] `sys` imported but unused
hello.py:3:8: F401 [*] `json` imported but unused
hello.py:5:1: W293 [*] Blank line contains whitespace
hello.py:7:6: E225 [*] Missing whitespace around operator
Found 5 errors.
[*] 5 fixable with the `--fix` option.

ruff check --fix hello.py

def hello_world():
    x = 1 + 2
    print("hello world")
    return x

if __name__ == "__main__":
    hello_world()

ruff format hello.py

[tool.ruff]
# 目标 Python 版本
target-version = "py312"
# 行长度限制
line-length = 88
# 要检查的目录
src = ["src", "tests"]
# 排除的目录
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
]

[tool.ruff.lint]
# 启用的规则集
select = [
    "E",      # pycodestyle 错误
    "W",      # pycodestyle 警告
    "F",      # pyflakes
    "I",      # isort（import 排序）
    "UP",     # pyupgrade（版本升级建议）
    "B",      # flake8-bugbear（常见 bug 模式）
    "SIM",    # flake8-simplify（代码简化）
    "RUF",    # Ruff 自带规则
]
# 忽略的规则
ignore = [
    "E501",   # 行太长（交给 formatter 处理）
    "E402",   # import 不在文件顶部（某些脚本需要）
]
# 最大允许复杂度
mccabe.max-complexity = 10

[tool.ruff.lint.per-file-ignores]
# 测试文件忽略部分规则
"tests/**/*.py" = ["S101", "PLR2004"]
# 迁移文件忽略所有规则
"**/migrations/*.py" = ["ALL"]

[tool.ruff.format]
# 引号风格：单引号或双引号
quote-style = "double"
# 缩进类型
indent-style = "space"
# 末尾换行
skip-magic-trailing-comma = false

pip uninstall black isort flake8 autoflake pyupgrade -y

[tool.ruff]
line-length = 88          # Black 默认行宽
target-version = "py312"

[tool.ruff.format]
quote-style = "double"    # Black 默认双引号
indent-style = "space"

[tool.ruff.lint]
select = ["E", "W", "F", "I"]

# 第一步：格式化所有 Python 文件
ruff format .

# 第二步：检查并自动修复
ruff check --fix .

# 第三步：查看剩余问题（不自动修复）
ruff check .

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.9.0
    hooks:
      # 先格式化
      - id: ruff-format
      # 再检查
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]

pip install pre-commit
pre-commit install

name: Ruff Check

on: [push, pull_request]

jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install Ruff
        run: pip install ruff

      - name: Run Ruff format check
        run: ruff format --check .

      - name: Run Ruff lint
        run: ruff check --output-format=github .

ruff:
  image: python:3.12-slim
  stage: test
  script:
    - pip install ruff
    - ruff format --check .
    - ruff check .
  allow_failure: true  # 初期可以先允许失败

# 只检查变更的文件（CI 场景）
ruff check --diff .

# 输出 SARIF 格式（用于 GitHub Code Scanning）
ruff check --output-format=sarif . > results.sarif

# 只检查特定规则
ruff check --select=F,E .

# 查看 Ruff 的配置和缓存状态
ruff check --show-settings .

[tool.ruff.lint]
select = ["E", "F", "W"]

# 将某些规则设为警告而非错误
[tool.ruff.lint.flake8-errmsg]
max-string-length = 20

[tool.ruff.lint.pydocstyle]
convention = "google"  # 或 "numpy", "pep257"

// .vscode/settings.json
{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.fixAll.ruff": "explicit"
    }
  }
}

# 监听文件变化，自动重新检查
ruff check --watch .

# 输出 JSON 格式，可以用 jq 处理
ruff check --output-format=json . | jq '.'

# 或使用 sarif 格式配合 GitHub Code Scanning
ruff check --output-format=sarif . > ruff-results.sarif