Python プロジェクト構造 & モジュールアーキテクチャ

モジュール境界を明確にし、公開インターフェースを明示的に定義し、保守性の高いディレクトリ構造を備えた、よく整理された Python プロジェクトを設計します。適切な組織化により、コードの発見性が向上し、変更の予測可能性が高まります。

このスキルを使うとき

• 新しい Python プロジェクトをゼロから開始するとき
• 既存のコードベースを明確にするために再編成するとき
• __all__ でモジュールの公開 API を定義するとき
• フラットなディレクトリ構造とネストされた構造のいずれかを決定するとき
• テストファイルの配置戦略を決定するとき
• 再利用可能なライブラリパッケージを作成するとき

コアコンセプト

1. モジュールの凝集性

一緒に変わる関連コードをグループ化します。モジュールは単一で明確な目的を持つべきです。

2. 明示的インターフェース

__all__ を使って公開内容を定義します。リストに載っていないものはすべて内部実装の詳細です。

3. フラットな階層

浅いディレクトリ構造を優先します。真の下位ドメインがある場合にのみ深さを追加します。

4. 一貫した規約

プロジェクト全体で命名と組織パターンを均一に適用します。

クイックスタート

myproject/
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── services/
│       ├── models/
│       └── api/
├── tests/
├── pyproject.toml
└── README.md

基本パターン

パターン 1: ファイルごとに 1 つのコンセプト

各ファイルは単一のコンセプトまたは密接に関連した関数セットに焦点を当てるべきです。次の場合はファイルの分割を検討してください:

• 無関係な複数の責任を扱う
• 300～500 行を超えて成長する (複雑さによって異なる)
• 異なる理由で変更されるクラスが含まれている

# 良い例: 焦点の絞られたファイル
# user_service.py - ユーザーのビジネスロジック
# user_repository.py - ユーザーデータアクセス
# user_models.py - ユーザーデータ構造

# 避ける: 何でもかんでもが入ったファイル
# user.py - サービス、リポジトリ、モデル、ユーティリティを含む...

パターン 2: __all__ での明示的な公開 API

すべてのモジュールの公開インターフェースを定義します。リストに載っていないメンバーは内部実装の詳細です。

# mypackage/services/__init__.py
from .user_service import UserService
from .order_service import OrderService
from .exceptions import ServiceError, ValidationError

__all__ = [
    "UserService",
    "OrderService",
    "ServiceError",
    "ValidationError",
]

# 内部ヘルパーは省略によってプライベートのままです
# from .internal_helpers import _validate_input  # エクスポートされません

パターン 3: フラットなディレクトリ構造

最小限のネストを優先します。深い階層はインポートを冗長にし、ナビゲーションを困難にします。

# 推奨: フラット構造
project/
├── api/
│   ├── routes.py
│   └── middleware.py
├── services/
│   ├── user_service.py
│   └── order_service.py
├── models/
│   ├── user.py
│   └── order.py
└── utils/
    └── validation.py

# 避ける: 深いネスト
project/core/internal/services/impl/user/

真の下位ドメインで分離が必要な場合にのみサブパッケージを追加します。

パターン 4: テストファイルの編成

1 つのアプローチを選択し、プロジェクト全体で一貫して適用します。

オプション A: コロケーション済みテスト

src/
├── user_service.py
├── test_user_service.py
├── order_service.py
└── test_order_service.py

メリット: テストはそれが検証するコードのすぐ側に配置されます。カバレッジギャップを簡単に確認できます。

オプション B: 並列テストディレクトリ

src/
├── services/
│   ├── user_service.py
│   └── order_service.py
tests/
├── services/
│   ├── test_user_service.py
│   └── test_order_service.py

メリット: 本番コードとテストコードの明確な分離。大規模プロジェクトの標準です。

高度なパターン

パターン 5: パッケージ初期化

__init__.py を使用して、パッケージ利用者のために明確な公開インターフェースを提供します。

# mypackage/__init__.py
"""MyPackage - 便利なことを行うためのライブラリ。"""

from .core import MainClass, HelperClass
from .exceptions import PackageError, ConfigError
from .config import Settings

__all__ = [
    "MainClass",
    "HelperClass",
    "PackageError",
    "ConfigError",
    "Settings",
]

__version__ = "1.0.0"

利用者はパッケージから直接インポートできます:

from mypackage import MainClass, Settings

パターン 6: レイヤー化アーキテクチャ

関心の明確な分離のために、アーキテクチャレイヤーごとにコードを整理します。

myapp/
├── api/           # HTTP ハンドラー、リクエスト/レスポンス
│   ├── routes/
│   └── middleware/
├── services/      # ビジネスロジック
├── repositories/  # データアクセス
├── models/        # ドメインエンティティ
├── schemas/       # API スキーマ (Pydantic)
└── config/        # 設定

各レイヤーは下位のレイヤーにのみ依存し、上位には依存しないべきです。

パターン 7: ドメイン駆動構造

複雑なアプリケーションの場合、技術レイヤーではなくビジネスドメインごとに整理します。

ecommerce/
├── users/
│   ├── models.py
│   ├── services.py
│   ├── repository.py
│   └── api.py
├── orders/
│   ├── models.py
│   ├── services.py
│   ├── repository.py
│   └── api.py
└── shared/
    ├── database.py
    └── exceptions.py

ファイルとモジュール命名

規約

• すべてのファイルとモジュール名に snake_case を使用: user_repository.py
• 意味を不明確にする略語を避ける: usr_repo.py ではなく user_repository.py
• クラス名をファイル名に合わせる: user_service.py の中に UserService

インポートスタイル

明確さと信頼性のために絶対インポートを使用します:

# 推奨: 絶対インポート
from myproject.services import UserService
from myproject.models import User

# 避ける: 相対インポート
from ..services import UserService
from . import models

相対インポートはモジュールが移動または再編成されると破損する可能性があります。

ベストプラクティスの要約

1. ファイルを焦点的に保つ - ファイルごとに 1 つのコンセプト、300～500 行で分割を検討 (複雑さによって異なる)
2. __all__ を明示的に定義 - 公開インターフェースを明確にする
3. フラット構造を優先 - 真の下位ドメインがある場合にのみ深さを追加
4. 絶対インポートを使用 - より信頼性が高く、より明確
5. 一貫性を保つ - プロジェクト全体でパターンを均一に適用
6. 名前をコンテンツに合わせる - ファイル名はその目的を説明するべき
7. 関心を分離 - レイヤーを明確に保ち、依存関係が一方向に流れるようにする
8. 構造を文書化 - 組織の説明を含む README を含める