第3章 Ruff によるコード検証と自動フォーマット

Ruff は、Python のコード品質を保つための超高速なリンター（静的解析）およびフォーマッター（自動整形）です。

これまで Python コミュニティでは、用途ごとに複数のツール（Flake8, Black, isort, pycodestyle, pydocstyle など）を併用していました。Ruff はこれら主要ツールの機能を単一の高速バイナリに統合し、圧倒的な処理速度でコードを検査・整形します。本章では、Ruff の使い方と設定手法を解説します。

3.1 Ruff の特徴と利点

Ruff を導入することで、以下の大きなメリットが得られます。

驚異的な実行速度: Rust で実装されており、従来の Python 製ツール（Flake8 や Black など）と比較して 10〜100 倍以上高速に動作します。数万行のコードでもコンマ数秒で検証が完了します。
ツールの一元化: コードの潜在的バグ・不要なインポートの検出（Linter）と、インデントや改行の自動整形（Formatter）、インポート文の並び替え（isort 相当）が 1 つのツールで完結します。
Black 互換のフォーマッター: コード整形スタイルは事実上の標準である Black と互換性があり、既存プロジェクトからの移行も容易です。
豊富な組み込みルール: 800 以上のルール（Flake8 プラグイン群、Bugbear、Pyupgrade、PEP8 命名規則等）を組み込みでサポートしており、追加プラグインの個別インストールが不要です。

3.2 プロジェクトへの Ruff の追加

前章で学んだ uv を使用して、開発用ツールとして Ruff をプロジェクトに追加します。

uv add --dev ruff

これだけで、プロジェクトの仮想環境に Ruff が組み込まれ、uv run ruff 経由で即座に利用可能になります。

3.3 リンターによる静的解析 (ruff check)

コード内の文法違反、未定義変数、未使用のインポートなどを検査するには、ruff check コマンドを実行します。

uv run ruff check .

もしコードに問題があれば、ファイル名、行番号、ルールコード（例: F401）、および問題の内容が表示されます：

src/main.py:3:1: F401 `os` imported but unused
Found 1 error.

自動修正の適用 (–fix)

Ruff の強力な機能の 1 つが自動修正です。軽微な構文ミスや不要なインポートの削除などは、--fix オプションを付けるだけで自動的に修正されます。

uv run ruff check --fix .

手動でファイルを修正することなく、瞬時にクリーンなコードベースを維持できます。

3.4 フォーマッターによるコード自動整形 (ruff format)

プロジェクト全体のコードスタイル（改行、スペース、引用符、インデント）を統一するには、ruff format コマンドを使用します。

uv run ruff format .

フォーマットの差分確認とチェックモード

CI（継続的インテグレーション）などで「ファイルが正しくフォーマットされているか」をファイル変更を行わずに検証したい場合は、--check オプションを指定します：

uv run ruff format --check .

未整形の箇所がある場合は非ゼロの終了コード（エラー）が返されるため、自動テストでのスタイル検証に活用できます。

3.5 pyproject.toml での設定

Ruff の動作設定は、プロジェクトルートの pyproject.toml に記述します。

以下は、代表的な推奨設定例です：

[tool.ruff]
# 対象とする Python バージョン
target-version = "py312"

# 1行の最大文字数
line-length = 88

# 整形・検証から除外するディレクトリ
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
]

[tool.ruff.lint]
# 適用するルールグループ
select = [
    "E",     # pycodestyle エラー
    "W",     # pycodestyle 警告
    "F",     # Pyflakes (未定義変数、未使用インポート等)
    "I",     # isort (インポート文の整列)
    "B",     # flake8-bugbear (バグになりやすい書き方の検出)
    "UP",    # pyupgrade (最新の Python 記法への自動置換)
    "SIM",   # flake8-simplify (コードの簡素化)
    "RUF",   # Ruff 独自ルール
]

# 明示的に無視するルール
ignore = [
    "E501",  # 行長制限違反 (フォーマッターに委ねるため)
]

[tool.ruff.lint.isort]
# isort の設定 (複数行インポートのスタイルなど)
combine-as-imports = true

[tool.ruff.format]
# 文字列リテラルの引用符スタイル (既定: double)
quote-style = "double"

# インデントのスタイル (既定: space)
indent-style = "space"

主なルールプレフィックス

プレフィックス	由来ツール	内容・用途
`F`	Pyflakes	未使用インポート、未定義変数、重複引数などの明確な不具合
`E`, `W`	pycodestyle	PEP 8 スタイル違反（スペース、改行の不整合）
`I`	isort	アルファベット順・標準ライブラリ順のインポート文ソート
`B`	flake8-bugbear	ミュータブルなデフォルト引数など、見落としやすい落とし穴
`UP`	pyupgrade	旧バージョンの古い Python 記法を最新構文へ自動更新
`RUF`	Ruff 独自	型アノテーションの冗長性や無効な構文のチェック

3.6 エディタ連携による開発の快適化

VS Code を利用している場合は、公式拡張機能である「Ruff」を導入することを強く推奨します。

設定（.vscode/settings.json）に以下を記述することで、ファイルを保存するたびに自動でインポート文の整理、リントの修正、およびフォーマットが瞬時に実行されるようになります：

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll.ruff": "explicit",
      "source.organizeImports.ruff": "explicit"
    }
  }
}

この設定により、開発者はコードの整形やインポート順序を手作業で気にする必要がなくなり、本来の実装ロジックに集中できます。

Keyboard shortcuts