Python ベストプラクティス

Pythonコードの作成とレビューのためのガイドライン。8つのカテゴリに分かれた70個のルール。影響度順に優先付けされています。

ルールのマッチはシグナルであり、判定ではありません。ほとんどのルールは新規コード向けの設計推奨であり、リポジトリ全体のバグ修正ではありません。レビューで指摘する前に、または安定したコードをリファクタリングする前に、ルールの影響度を確認してください。

適用するタイミング

• 新しいPythonモジュール、関数、クラス、またはデータモデルを作成する
• コードの正確性または型安全性をレビューする
• 編集の際に既存コード内のパターンをリファクタリングする

安定したコード全体へのルール適用を避けてください。チャーン（変更の頻繁性）はほとんど見合いません。

影響度レベル

• CRITICAL — 実際のバグクラス（データ破損、キャンセルの飲み込み、不安全なデフォルト）を防止します。見つかったら修正してください。
• HIGH — 有意な正確性またはメンテナンス性の向上。ほとんどの文脈で修正する価値があります。
• MEDIUM — グッドプラクティス。明確さまたはドリフト防止。新規コードに適用してください。安定したコードをチャーンさせないでください。
• LOW-MEDIUM / LOW — スタイルまたはマイクロ最適化。機会に応じて適用します。

Python バージョン基準

ルールはPython 3.11以上を想定しています。より高いバージョンに依存するルールは、インライン記載されています：

• warnings.deprecated() — 3.13以上
• zoneinfo — 3.9以上
• isinstance()内のUnion型 — 3.10以上
• assert_never — 3.11以上 (typing_extensions経由のバックポート)

applicability:pydanticタグが付いたルールはPydantic固有です。

ルールカテゴリ（優先度順）

優先度	カテゴリ	影響度	プレフィックス
1	データモデリング	HIGH	data-
2	エラーハンドリング	MEDIUM-HIGH	error-
3	型安全性	MEDIUM-HIGH	types-
4	API設計	MEDIUM	api-
5	コード簡潔化	LOW-MEDIUM	simplify-
6	パフォーマンス	LOW-MEDIUM	perf-
7	命名	LOW-MEDIUM	naming-
8	インポートと構造	LOW	imports-

セクション影響度は典型的なケースのラベルです。個別のルールは一段階上下する場合があります。ルールファイルを確認してください。

クイックリファレンス

データモデリング（data-）

• data-mutable-defaults — def f(items=[]) は禁止。None + body構成または default_factory を使用
• data-derive-dont-store — 状態からブール値を計算。相互にミラーリングするフラグはキャッシュしない
• data-mutation-contract — 変更するか返すか。両方ではない
• data-aware-datetimes — datetime.now(timezone.utc) でタイムゾーン対応。utcnow() は非推奨
• data-discriminated-unions — バリアントにタグを付ける。オプションフィールドバッグではなく
• data-explicit-variants — モードごとにコンクリートクラス。is_thread / is_edit フラグより優れている
• data-phased-composition — 共存するオプショナルを1つのネストされたオプショナルにグループ化
• data-encapsulate-mutable-state — 可変状態を最も狭く明確なスコープにトラップ
• data-sentinel-when-none-is-valid — None が有意な値の場合、プライベートセンチネルを使用
• data-newtype-for-ids — NewType('UserId', str) でIDが相互交換不可に
• data-delete-dead-variants — 構成されていないunionアームを削除

エラーハンドリング（error-）

• error-specific-exceptions — 特定の型をキャッチ。素の except: や except BaseException: は禁止（Ctrl-Cと非同期キャンセルを破壊）。except Exception: は3.8以上でキャンセルセーフ
• error-context-managers — ファイル、ロック、セッション用に with / async with を使用
• error-assert-debug-only — assert は -O で消える。ランタイムコントラクト用ではない
• error-validate-at-boundaries — システムエッジで高価な処理前に高速失敗
• error-trust-validated-state — イミュータブルでローカルに構成された状態を信頼
• error-consolidate-try-except — 同じキャッチと処理をするブロックをマージ
• error-assert-never-exhaustiveness — 網羅性用に typing.assert_never を使用
• error-raise-from-for-chains — 因果関係を保持するために raise NewErr(...) from original を使用
• error-inherit-base-exceptions — 互換性のために新規例外は既存ベースを継承
• error-log-exception-context — except 内で logger.exception(...) を使用。ログにトレースバックを保持
• error-repr-in-messages — エラーテキスト内の識別子に f"tool {name!r}" を使用

型安全性（types-）

• types-fix-errors-not-ignore — 型エラーを修正。# type: ignore は最後の手段
• types-avoid-any — Protocol、TypeVar、union を Any の代わりに使用
• types-typeddict-over-dict-any — 構造が既知の場合は TypedDict / dataclass を使用
• types-literal-for-fixed-sets — 固定文字列用に Literal["a", "b"] を使用
• types-fix-types-not-cast — 定義を修正。cast() はランタイムで実際に絞り込む場合のみ
• types-isinstance-for-narrowing — hasattr / type(x).__name__ の代わりに isinstance() を使用
• types-narrow-to-runtime-reality — アノテーションは制御フローが実際に許可するものと一致
• types-trust-the-checker — 型が既に強制するランタイムチェックを削除
• types-remove-redundant-optional — 値が存在することが保証されている場合は | None を削除
• types-type-checking-imports — オプションまたは重いインポート用に if TYPE_CHECKING: を使用

API設計（api-）

• api-required-before-optional — 必須フィールドがオプションの前（Pythonが強制）
• api-keyword-only-params — オプション/設定パラメータに * マーカーを使用
• api-no-boolean-flag-params — True, False の汤の代わりに Literal / Enum を使用
• api-immutable-transforms — 新しいコレクションを返す。入力を変更しない
• api-model-cohesion — フラットモデル。重複またはシングルキーラップフィールドなし
• api-underscore-for-private — 内部用に _prefix を使用。__all__ から除外
• api-deprecated-aliases — 名前が変更されたAPI用に warnings.deprecated()（3.13以上）を使用
• api-no-private-access — モジュール外から _prefixed 名にアクセスしない
• api-instance-vs-module-fn — 所有権と一致する名前空間を選択

コード簡潔化（simplify-）

• simplify-early-return — 早期リターン。happy pathをネストさせない
• simplify-extract-after-duplication — 2番目のコピーが決定ポイント。3番目が安全なデフォルト
• simplify-cached-property — イミュータブルインスタンス上で @cached_property を使用。スレッドセーフではない
• simplify-comprehensions — for + .append() の代わりに内包表記を使用
• simplify-any-all-builtins — 手動フラグ + break の代わりに any() / all() を使用
• simplify-fallback-or — falsy値が意味的でない場合に x or default を使用
• simplify-flatten-nested-if — 介入コードがない場合に if cond1 and cond2: を使用
• simplify-inline-single-use-vars — 一度だけ使用される中間変数を削除
• simplify-remove-dead-code — コメントアウトコードを削除。gitが履歴を保持

パフォーマンス（perf-）

• perf-set-for-membership — 繰り返される in チェックに set を使用
• perf-dict-index-over-nested-loops — ルックアップ用に dict を構築
• perf-lru-cache-pure-fns — 純粋関数上で functools.lru_cache / functools.cache を使用
• perf-generator-over-list — メモリまたはレイテンシが重要な場合ジェネレータでストリーム
• perf-combine-iterations — filter + map を1パスに融合
• perf-compile-regex-module-level — 静的regexをモジュール範囲でコンパイル。タイトループで重要
• perf-type-adapter-constant — モジュール範囲 TypeAdapter (applicability: pydantic)
• perf-isinstance-tuple-syntax — タプル形式がわずかに高速。プロファイルされたホットパスのみ

命名（naming-）

• naming-rename-on-behavior-change — 動作が変わったら名前変更。古い名前は誤解を招く
• naming-consistent-terminology — 同じ概念、コード/ドキュメント/エラー全体で同じ単語
• naming-specific-over-generic — toolset_id。素の id ではなく
• naming-drop-redundant-prefixes — ToolConfig.description。ToolConfig.tool_description ではなく
• naming-upper-case-constants — MAX_RETRIES。内部用に _ プレフィックス
• naming-no-type-suffixes — _dict / _list サフィックスなし。型は型に注釈

インポートと構造（imports-）

• imports-no-side-effects — モジュールは安価にインポート可能。インポート時のネットワーク/モデル/env読み込みなし
• imports-top-of-file — ファイルの上部にインポート。循環参照/オプション/遅延実行の文書化例外
• imports-optional-dependencies — try / except ImportError とインストール指示付き
• imports-scope-helpers-to-usage — 使用場所の近くにヘルパーを定義
• imports-remove-unused — 未使用のインポートを削除
• imports-no-duplicates — 名前ごとに1つのインポート

使用方法

個別のルールファイルの詳細を読んでください：

rules/data-mutable-defaults.md
rules/error-specific-exceptions.md

各ルールには以下が含まれます：

• 前置きのインパクトレベル
• 簡潔な説明
• 誤った例
• 正しい例
• エッジケースのオプショナル説明

すべてのルールを展開した完全なコンパイルガイド用：AGENTS.md