python-best-practices

Python のベストプラクティス

Python の記述とレビューのガイドラインです。影響度に応じて優先順位を付けた、8 つのカテゴリにわたる 75 のルールをまとめています。

ルールへの該当はシグナルであり、最終的な判断ではありません。ほとんどのルールは新しいコードに対する設計上の好みであり、リポジトリ全体で修正すべきバグではありません。レビューで指摘したり、安定したコードをリファクタリングしたりする前に、ルールの影響度を確認してください。

クイックリファレンスの項目はきっかけであり、適用してよいという許可ではありません。レビューの指摘や変換にルールを適用する前に、ルールファイルを開き、反対のシグナルを確認してください。ここでいう反対のシグナルとは、適用すべきでない状況を示す、マーカーで始まる段落（**When ...**／**Scope:**／**Preserve ...**）です。

適用する場面

• 新しい Python モジュール、関数、クラス、データモデルを記述するとき
• 正確性や型安全性についてコードをレビューするとき
• 変更中のコードに含まれるパターンをリファクタリングするとき

安定したコード全体にこれらのルールを一律に適用するのは避けてください。大抵の場合、変更に伴うコストに見合うメリットはありません。

影響度

• CRITICAL — 実際に発生し得るバグの種類（データ破損、キャンセルの握りつぶし、安全でないデフォルト設定など）を防ぎます。見つけたら修正してください。
• HIGH — 正確性や保守性を大きく向上させます。ほとんどの状況で修正する価値があります。
• MEDIUM — 優れたプラクティスであり、明確さの向上や逸脱の防止につながります。新しいコードには適用し、安定したコードに不要な変更を加えないでください。
• LOW-MEDIUM／LOW — スタイルや小規模な最適化に関するものです。機会があれば適用してください。

Python のバージョンの基準

ルールは Python 3.11 以降を前提としています。より新しいバージョンに依存するルールには、その旨がインラインで記載されています。

• warnings.deprecated() — 3.13 以降
• zoneinfo — 3.9 以降
• isinstance() のユニオン型 — 3.10 以降
• assert_never — 3.11 以降（typing_extensions でバックポート可能）
• PEP 695 の type 文とジェネリック構文 — 3.12 以降（types-modern-syntax にインラインで記載）

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-

セクションに付けられた影響度は、一般的なケースを示すラベルです。個々のルールの影響度は、その前後 1 段階の範囲に及びます。ルールファイルを確認してください。

クイックリファレンス

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

• data-mutable-defaults — def f(items=[]) のような定義は避けてください。None と関数本体での構築、または default_factory を使用してください
• data-derive-dont-store — 状態から真偽値を計算してください。互いに対応するフラグをキャッシュしないでください
• data-mutation-contract — 関数ごとに曖昧さのない契約を 1 つ定めてください。変更する（新しい情報を返すのは問題ありません）か、新しい値を返すかのどちらかにし、変更済みのオブジェクトを新しい値のように返さないでください
• 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 — 生成されないユニオンのバリアントは削除してください
• data-reject-bool-as-int — bool は int のサブクラスです。数値チェックの前に明示的に拒否してください

エラー処理（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}" を使います
• error-match-types-not-messages — メッセージの部分文字列ではなく、例外の型とステータスコードで分類します

型安全性（types-）

• types-fix-errors-not-ignore — 型エラーを修正します。# type: ignore は最後の手段です
• types-avoid-any — Any よりも Protocol、TypeVar、ユニオンを使います
• 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: を使います
• types-modern-syntax — Optional / Union / typing.List ではなく、X | None、list[str] を使います
• types-sequence-over-list-params — 読み取り専用の引数には Sequence / Mapping を使います。list は不変です

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 — 早期に return し、正常系を入れ子にしないでください
• 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 — 偽値に意味上の違いがない場合は x or default を使います
• simplify-flatten-nested-if — 間にコードがなければ if cond1 and cond2: を使います
• simplify-inline-single-use-vars — 1 回しか使わない中間変数を削除します
• 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 — 静的な正規表現はモジュールスコープでコンパイルします。タイトなループで効果があります
• perf-type-adapter-constant — モジュールスコープの TypeAdapter (適用対象：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 — モジュールはインポート時に低コストでなければなりません。インポート時にネットワーク／モデル／環境変数を読み込まないでください
• imports-top-of-file — インポートはファイルの先頭に記述します。循環／オプション／遅延インポートの例外は文書化します
• imports-optional-dependencies — インストール方法のヒントを添えて try / except ImportError を使います
• imports-scope-helpers-to-usage — ヘルパーは使用箇所の近くに定義します
• imports-remove-unused — 未使用のインポートを削除します
• imports-no-duplicates — 同じ名前を複数回インポートしません
• imports-lightweight-init — 親の __init__.py はサブモジュールのインポートごとに実行されます。重い依存関係やオプションの依存関係を含めないでください

使い方

詳細は各ルールファイルを参照してください。

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

各ルールには次の内容が含まれます。

• フロントマターに記載された影響レベル
• 簡単な説明
• 誤った例
• 正しい例
• エッジケースに関する任意の注記

すべてのルールを展開した完全版のガイドについては、AGENTS.md を参照してください。