linting

Ruff によるリンティング

Ruff は、Flake8（数十個のプラグインを含む）、isort、pydocstyle、pyupgrade、autoflake などの代替としてそのまま使えるように設計された、非常に高速な Python リンターです。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