python-types-contracts

Python の型とコントラクト

概要

型ヒントは装飾ではなく、インターフェース設計として扱います。 明示的なコントラクト、安定した公開 API、境界で安全なモデリングを重視します。

これらは一般的なケースで推奨されるデフォルトであり、普遍的なルールではありません。 デフォルトがプロジェクトの制約と相反する場合は、より適した代替案を提案し、トレードオフと補完策を説明します。

使用する場合

• 公開 API のシグネチャに型注釈がない、または広すぎる型が使われている。
• Pydantic モデルが信頼境界ではなく、内部ロジックのあちこちに散在している。
• コントラクトの変更によって、移行手段がないまま下流の利用者に影響するおそれがある。
• より狭い型を適用できる箇所で、インターフェースが Any、object、または型指定のない dict を受け入れている。
• レイヤー間（API、DB、ドメイン）のスキーマ境界が暗黙的、または一貫していない。
• プロトコル、抽象基底クラス、または構造的部分型付けを追加または変更する。

使用しない場合：

• 公開インターフェースのない、純粋な実装レベルのコード。
• 型の厳密さに価値がなく、かえってコストになる使い捨てスクリプトや一度限りのデータ加工。
• 型付けのオーバーヘッドが安全性よりも重要な、パフォーマンス重視の内側ループ。

クイックリファレンス

• 公開 API に型を付け、コントラクトを明確に保ちます。
• 広いパラメーター型よりも、狭いインターフェースと境界プロトコルを優先します。
• デフォルトではあらゆる場所で使うのではなく、信頼境界で Pydantic を使用します。
• コントラクトを変更する場合は、互換性と移行への影響を明確にします。
• 深い継承階層より、構造的部分型付けに Protocol を優先します。
• 公開関数は具体的な型を返し、入力にはプロトコルまたは共用体型を受け入れます。

よくある間違い

• すべてに同じように型を付ける。 内部ヘルパーに、公開 API と同じ厳密さは必要ありません。 非公開コードに型注釈を付けすぎると、安全性を高めずにノイズが増えます。
• あらゆる場所で Pydantic を使う。 信頼境界（API の受信時、設定の読み込み、外部データ）の検証に限定せず、内部データフローに Pydantic モデルを使う。
• 広すぎる戻り値の型。 公開関数が Any や dict を返すと、呼び出し側は構造を推測しなければなりません。 具体的な型または TypedDict を返します。
• コントラクトを黙って破壊する。 バージョン管理、非推奨の警告、移行に関する注記なしに、関数シグネチャを変更したり、フィールドを削除したり、受け入れる型を狭めたりする。
• None を無視する。 値が正当に存在しない場合があるのに、Optional や None との共用体型を省略し、実行時まで null 安全性のバグを見えなくする。

スコープに関する注記

• これらの推奨事項は、一般的なケースで推奨されるデフォルトとして扱い、普遍的なルールとはみなしません。
• デフォルトがプロジェクトの制約と相反する場合や、結果を悪化させる場合は、より適した代替案を提案し、このケースでより適している理由を説明します。
• デフォルトから逸脱する場合は、トレードオフと補完策（テスト、可観測性、移行、ロールバック）を明示します。

呼び出しに関する通知

• このスキルを呼び出す際は、python-design-modularity という名前でユーザーに知らせます。

参考資料

• references/typing-policy.md
• references/contract-evolution.md
• references/pydantic-boundaries.md