python

Python のガイドライン

Python 開発の標準とベストプラクティスです。Python コードを作成または変更する際は、これらのガイドラインに従ってください。

設計原則

DRY、KISS、SOLID を一貫して適用してください。適切な場合は関数型のメソッドを優先し、状態を持つ振る舞いにはクラスを使用してください。インターフェースには継承ではなく、Protocol クラスとのコンポジションを使用してください。各モジュールは単一の責務を持つようにしてください。クラスの依存関係には依存性注入を使用してください。

コードスタイル

• 命名：変数、メソッド、クラスには、説明的で簡潔な名前を付けます
• ドキュメント：すべてのクラス、関数、列挙型、列挙値に docstring を付けます
• 型ヒント：一貫して使用し、必要な場合を除いて Any は避けます
• インポート：__init__.py でのバレルエクスポートは避け、空のファイルを推奨します

型アノテーション

• typing.Dict、typing.List ではなく、dict、list を使用します
• Optional[str] ではなく、str | None を使用します
• 型ヒントを含むファイルの先頭に from __future__ import annotations を記述します
• typing モジュールの同等の型より、組み込み型を優先します

アーキテクチャ

依存性注入

• クラスを使用する場合は、コンストラクターまたはメソッドを通じて必ず依存関係を注入します
• 1 つのモジュールにつきサービスクラスは 1 つにします（インターフェースとクラスモデルの追加は許可されます）
• 依存性注入とテストのためのインターフェース定義には Protocol クラスを使用します

モジュール構成

• 各モジュールは、明確な境界を持つ単一の関心事に集中します
• 重複を避けるため、再利用可能なメソッドを抽出します
• さまざまなコンテキストで再利用できるように設計します

環境変数

• 変数ごとに個別のメソッドを用意した environment.py ファイルを使用します（例：API_KEY には api_key()、DATABASE_URL には database_url()）
• テストでモックしやすくするため、環境へのアクセスはパッケージごとに 1 か所へまとめます

データモデル

• スキーマ、検証、データモデルには Pydantic v2 を使用します
• Pydantic の型検証、シリアライズ、構成管理を活用します
• API のリクエスト／レスポンススキーマ、構成オブジェクト、データ転送オブジェクトには Pydantic モデルを使用します

テスト

構成

• テストは src/ ディレクトリの構成を反映させます
• テストメソッド名は test_ で始めます
• テストクラスのスイートを使用します。def foo() に対しては class TestFoo を作成します
• 名前は簡潔にし、メソッド名からクラススイート名を省略します
• コードを変更する際は、適切なユニットテストがあるか必ず確認します

品質

• AAA（Arrange、Act、Assert）パターンを使用します
• テストは有用で、読みやすく、簡潔で、保守しやすいものにします
• 差分が膨大になったり、負担になったりするテストは避けます

ツール

• unittest より pytest を優先します
• モックには pytest-mock を使用します
• 共通フィクスチャには conftest.py を使用します
• 共通のテストコードには tests/__test_<package_name>__ を使用します

実装

Python コードを実装する際は、次の点に従ってください。

• コミット前に、コードが型チェックとテストに合格することを確認します
• 関連する変更とテストを、アトミックなコミットにまとめます
• 既存のワークフローパターン（spec-first、TDD など）を確認し、それに従います

参考資料

• uv 管理プロジェクトでのアドホックな Python スクリプトについては、references/uv-scripts.md を参照してください。
• uv と Hatch を使用するモノレポ固有のパターンについては、references/uv-monorepo.md を参照してください。