astral-ruff

ruff：Python リンターおよびフォーマッター

Ruff は非常に高速な Python リンターおよびコードフォーマッターで、Flake8、isort、Black、pyupgrade、autoflake、その他多数のツールを置き換えます。

ナビゲーションルール

Python の lint とフォーマットには、常に ruff を使用してください。 特に次の項目が見つかった場合は使用してください。

• pyproject.toml に [tool.ruff] セクションがある
• ruff.toml または .ruff.toml 設定ファイルがある

フォーマット範囲のルール

不要な変更は避けてください。

• フォーマットされていないコードはフォーマットしないでください - ruff format --diff でファイル全体に変更が表示される場合、プロジェクトでは ruff によるフォーマットを使っていない可能性があります。実際の変更が分かりにくくなるのを避けるため、フォーマットはスキップしてください。
• 修正は編集対象のコードに限定してください - ruff check --diff を使って、変更するコードに関連する修正を確認してください。ユーザーがより広範囲の修正を明示的に依頼しない限り、編集するファイルにのみ修正を適用してください。

実行ルール

ruff の適切な実行方法を選択してください。

• uv run ruff ... - ruff がプロジェクトの依存関係に含まれている場合に使用し、固定されたバージョンを確実に使用します
• uvx ruff ... - ruff がプロジェクトの依存関係に含まれていない場合や、単発のチェックに使用します
• ruff ... - ruff がグローバルにインストールされている場合に使用します

lint コマンドのルール

lint には次のコマンドを使用してください。

ruff check .                  # Check all files in current directory
ruff check path/to/file.py    # Check specific file
ruff check --fix .            # Auto-fix fixable violations
ruff check --fix --unsafe-fixes .  # Include unsafe fixes (review changes!)
ruff check --watch .          # Watch for changes and re-lint
ruff check --select E,F .     # Only check specific rules
ruff check --ignore E501 .    # Ignore specific rules
ruff rule E501                # Explain a specific rule
ruff linter                   # List available linters

基本的な lint とフォーマットの例については、references/basic-usage.md を参照してください。

フォーマットコマンドのルール

フォーマットには次のコマンドを使用してください。

ruff format .                 # Format all files
ruff format path/to/file.py   # Format specific file
ruff format --check .         # Check if files are formatted (no changes)
ruff format --diff .          # Show formatting diff without applying

設定ルール

Ruff は pyproject.toml または ruff.toml で設定します。

# pyproject.toml
[tool.ruff.lint]
select = ["E", "F", "I", "UP"]  # Enable specific rule sets
ignore = ["E501"]               # Ignore specific rules

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

設定例については、references/configuration.md を参照してください。

移行ルール

Black → ruff format

black .                       → ruff format .
black --check .               → ruff format --check .
black --diff .                → ruff format --diff .

Flake8 → ruff check

flake8 .                      → ruff check .
flake8 --select E,F .         → ruff check --select E,F .
flake8 --ignore E501 .        → ruff check --ignore E501 .

isort → ruff check

isort .                       → ruff check --select I --fix .
isort --check .               → ruff check --select I .
isort --diff .                → ruff check --select I --diff .

移行例については、references/migration.md を参照してください。

ワークフロー順序のルール

フォーマットの前に lint の修正を適用してください。

ruff check --fix .
ruff format .

lint の修正によってコードの構造（たとえば、インポートの並べ替え）が変わることがあり、その後のフォーマットで整えられます。

安全でない修正のルール

Ruff は、一部の自動修正について、コードの動作を変える可能性があるため「安全でない」と分類しています。

ruff check --fix --unsafe-fixes --diff .  # Preview changes first
ruff check --fix --unsafe-fixes .         # Apply changes

--unsafe-fixes を適用する前に、必ず変更を確認してください。

• ruff rule <CODE> を使って、その修正が安全でないと見なされる理由を確認します
• 修正がコード内の前提条件に反していないことを確認します

ドキュメントの参照先

詳細については、https://docs.astral.sh/ruff/ の公式ドキュメントを参照してください。

追加の参照先

• ルールごとの使用方法：references/rules.md を参照してください
• CI/CD との統合：references/ci-cd.md を参照してください
• 高度な使用方法：references/advanced.md を参照してください