Pythonモジュールを構造化するためのルールとは？プロジェクト構成のベストプラクティス

Pythonプロジェクトを整理された形で構築するには、定評のあるディレクトリ構造を採用するのが効果的です。ここでは、Kenneth Reitz氏が公開しているサンプルプロジェクト「samplemod」を例に、優れたプロジェクト構成の方法を紹介します。このプロジェクトは「sample」モジュールを作成するもので、ディレクトリ構造は以下のようになっています。

README.rst
LICENSE
setup.py
requirements.txt
sample/__init__.py
sample/core.py
sample/helpers.py
docs/conf.py
docs/index.rst
tests/test_basic.py
tests/test_advanced.py

各ファイル・ディレクトリの役割

README.rst

モジュールの概要説明、セットアップ手順、使い方などを記載するファイルです。プロジェクトの「顔」となるドキュメントなので、最初に読まれることを意識して、簡潔かつ分かりやすくまとめましょう。

LICENSE（ライセンス）

ライセンス本文や著作権に関する記述を含むファイルです。オープンソースとして公開する場合は、適切なライセンスを選択して明記することが重要です。

setup.py

Pythonにおけるマルチプラットフォーム対応のインストーラーであり、Makefileに相当する役割を果たすファイルです。コマンドラインでのインストールに慣れている方なら、「make && make install」が「python setup.py build && python setup.py install」に相当すると考えると分かりやすいでしょう。ユーザーのマシン上でプロジェクトをビルドするために使用されます。

requirements.txt

Pipのrequirementsファイルは、プロジェクトへの貢献に必要な依存パッケージ（テスト、ビルド、ドキュメント生成など）を指定します。プロジェクトに開発用の依存関係がない場合や、setup.py経由で開発環境を構築したい場合は、このファイルは必須ではありません。

docs/（ドキュメントディレクトリ）

プロジェクトのドキュメントを格納するディレクトリです。Sphinxなどのドキュメント生成ツールを使って、APIリファレンスやチュートリアルを管理するのが一般的です。

tests/（テストディレクトリ）

すべてのテストコードはこのディレクトリに配置します。最初は単一のテストファイルから始めても問題ありませんが、テストが増えてきたら、モジュール本体のディレクトリ構造に合わせてテストも整理すると、保守性が高まります。

sample/（モジュール本体）

実際のモジュールコードを格納するディレクトリです。モジュールが単一ファイルのみで構成される場合は、sample.pyという名前でリポジトリのルート直下に置いても構いません。ライブラリのコードを曖昧なsrcやpythonといったサブディレクトリに配置するのは避けましょう。また、モジュールをパッケージとして扱いたい場合は、__init__.pyファイルを含める必要があります。