HOWTO · Python

Python アプリケーションのプロジェクト構造

Python アプリケーションを構築する方法を学ぶ

このページの内容

保守しやすい Python プロジェクトでは、ルートを必要なファイルに絞り、関連するコードをパッケージにまとめ、アプリケーションに必要な場合だけ補助ディレクトリを追加します。プログラムの実行方法に合わせて構成を選びましょう。モジュール化したアプリケーションも、単一の小規模なモノリスとしてデプロイできます。

アプリケーションに合った構成を選ぶ

明確なプロジェクト構成にすると、コードを探しやすくなり、保守や共同作業もしやすくなります。プログラムをマイクロサービスに分割する必要はありません。小規模なアプリケーションなら、関連するコードをモジュールやパッケージにまとめながら、単一のプログラムとしてデプロイできます。ディレクトリは、プロジェクト内で役立つ境界を作る場合に追加しましょう。大規模プロジェクトの構成をまねるためだけに、空のフォルダーを作るのは避けてください。

適切な構成は、アプリケーションの実行方法や内容によって異なります。コマンドラインツールに必要なのは、アプリケーションコード、依存関係の情報、テストだけかもしれません。Webアプリケーションには、テンプレートや静的ファイルも必要になることがあります。SQLite を使うプロジェクトではローカルのデータベースファイルを作成する場合があります。一方、データベースサービスに接続するプロジェクトでは、通常、そのデータをソースツリーの外に置きます。

プロジェクトルートから始める

プロジェクトルートとは、アプリケーションの開発、テスト、文書化、パッケージ化に使うファイルを置くディレクトリです。よく置かれるファイルには、セットアップ方法と使い方を記した README.md、コードの使用や配布に関する条件を示す LICENSE、pyproject.toml や requirements.txt などの依存関係定義があります。それぞれ役割が異なるため、すべてのパッケージ形式や依存関係形式を使う必要はありません。

Python アプリケーションに共通の必須エントリーポイント名はありません。コマンドラインプログラムは python -m package_name で起動できる場合があります。また、フレームワークやパッケージ設定で別のコマンドを定義することもできます。どのプロジェクトにも run.py や setup.py が必要だと決めつけず、アプリケーションに合った起動方法を使いましょう。

プロジェクトにインストールするパッケージを分離するため、ローカルに仮想環境を作成します。仮想環境はバージョン管理に含めないでください。共同作業者は依存関係の情報から、自分の環境を作成できます。.gitignore ファイルでは、仮想環境に加えてキャッシュなどの生成ファイルも除外するのが一般的です。ルートは簡潔なままにし、必要に応じて文書やパッケージ設定を追加しましょう。

アプリケーションコードをパッケージに整理する

Python モジュールは、その責務ごとにまとめましょう。たとえばブログなら、アカウント関連のコードを users に、投稿関連のコードを posts に置けます。これは同一プロセス内での一般的な整理方法です。2つのパッケージは、独立したサービスとして通信しなくても、1つのアプリケーションの一部として動作できます。

通常のパッケージには __init__.py ファイルが含まれることがよくあります。このファイルは空でも構いませんし、パッケージのインターフェースとして選んだ名前を公開することもできます。一方、Python ではこのファイルを省略できる名前空間パッケージもサポートされています。__init__.py が常に必要と考えるのではなく、プロジェクトで採用するパッケージ形式とツールに従いましょう。複数の部分で使うコードはモジュールやパッケージにまとめ、同じ処理を複数のフォルダーに重複して書かないようにします。

必要に応じてテスト、ドキュメント、Web用リソースを追加する

tests ディレクトリを使うと、自動チェックをアプリケーションコードから分けて管理できます。小規模なプロジェクトでも、コードの変更に伴って期待する動作を確認しやすくなるため、テストは役立ちます。README だけでは説明が足りなくなったら、docs ディレクトリに利用者や貢献者向けの詳しい案内を置けます。

Webプロジェクトでは、アプリケーションが描画する HTML 用の templates ディレクトリや、CSS、JavaScript、画像などを置く static ディレクトリを使うことがよくあります。正確な配置場所は、フレームワークとその設定によって異なります。Webを使わないコマンドラインアプリケーションに、これらを含める必要は通常ありません。

データベースモデルの配置場所は、選んだ設計に合わせます。専用の models.py モジュールに置く方法も、複数のモデル群をまとめるパッケージを作る方法もあります。database.db のようなファイルが適切なのは、SQLite など、ローカルのファイルベースデータベースを実際に使う場合に限られます。データを別の場所に保存するアプリケーションでは、ソースの構成にデータベースファイルを加える必要はありません。

例:小規模なブログアプリケーション

このブログでは、アカウント関連と投稿関連のコードを別々のパッケージにまとめ、Web専用のリソースとプロジェクトの補助ファイルをルートに置いています。以下のツリーは出発点です。フレームワークの慣習によっては、テンプレート、モデル、静的ファイルの配置が異なる場合があります。データベースファイルはローカルの SQLite を使う構成として示しています。また、ローカルの仮想環境は、バージョン管理対象のプロジェクト構成に含めていません。

この例を実行します。

このセクションのコードと表示されるラベルや出力は英語のままです。

layout = [
    "blog/",
    "├── README.md",
    "├── LICENSE",
    "├── pyproject.toml",
    "├── blog/",
    "│   ├── __init__.py",
    "│   ├── users/",
    "│   └── posts/",
    "├── templates/",
    "├── static/",
    "├── tests/",
    "└── database.db  (local SQLite only)",
]
print("\n".join(layout))
blog/
├── README.md
├── LICENSE
├── pyproject.toml
├── blog/
│   ├── __init__.py
│   ├── users/
│   └── posts/
├── templates/
├── static/
├── tests/
└── database.db  (local SQLite only)

デプロイ設定やフレームワーク固有の詳細はこの例に含めていないため、使用するツールチェーンに合わせて調整してください。models.py などのファイルは、データ処理を担当するパッケージ内に追加できます。成長したパッケージをさらに分割しても構いません。コマンドラインプロジェクトではWeb用フォルダーを省き、データベースサービスを使う場合はローカルのデータベースファイルを省きます。プロジェクトが成長しても、各ディレクトリが関連するコードやリソースを見つけやすくするという原則を保ちましょう。