はじめに #
Pythonでパッケージを構築するときのディレクトリ構成（フォルダ構成）をまとめました。
以下のようなパッケージを対象としています。
- 1個以上のモジュール（*.pyファイル）から構成される。
- テストを行う必要がある。
また、この記事ではデータ分析プロジェクトは対象外としています。
環境：Python 3.9.7
ディレクトリ構成 #
ディレクトリ構成の例を以下に示します。<my_project>は任意のパッケージ名に変更します。
<my_project>/
<my_project>/
__init__.py
<my_project>.py
*.py
tests/
__init__.py
test_<my_project>.py
test_*.py
docs/
README.md
requirements.txt
setup.py
LICENSE
パッケージの実体 #
ルートフォルダの下に同じ名前のフォルダを作り、その中にパッケージの実体を置きます。Pythonにパッケージとして認識させるため、__init__.pyというファイルを置きます。また、パッケージをインポートしたときに、__init__.pyが実行されます。そのため、__init__.pyにはパッケージの初期化処理を書くことがあります。
__init__.pyの中身の書き方はいくつかありますが、ここではパッケージを柔軟に使える書き方を示します。例えば、my_packageという名前のパッケージにmy_package.pyとmy_module_0.pyというモジュールがある場合、以下のように書きます。
from .my_package import *
from .my_module_0 import *
また、my_module_0.pyにmy_func()という名前の関数が定義されているとします。このとき、パッケージの外部から以下3つの方法で呼び出せます（他にも呼び出し方はあります）。
例1
# 例1 (my_module_0.pyというモジュール名を利用しない)
import my_package
my_package.my_func()
# 例2 (my_module_0.pyというモジュール名を利用する)
import my_package
my_package.my_module_0.my_func()
# 例3 (my_func関数のみインポートする)
from my_package import my_func
my_func()
実体が1ファイルのみの場合 #
パッケージ内のファイルが1個だけの場合、以下のようにルートフォルダの直下に置くことができます。
<my_project>/
<my_project>.py
tests #
testsフォルダには、テストを行うためのスクリプトを置きます。テストを行うライブラリには、現在主流のpytestや、Python標準のunittestがあります。これらのライブラリの慣習または仕様として、テスト用スクリプトにtest_から始まる名前を付けます。
docs #
docsフォルダには、パッケージに関するドキュメントを置きます。Sphinxを使ってdocstringから自動生成したドキュメントを置く運用方法もあるようです。
Sphinxの使用方法については以下の記事も参考にしてください。
SphinxでPython docstringからドキュメントを自動生成する – Helve Tech Blog
README.md #
README.mdには以下のような情報を記載します。
- リポジトリの概要
- パッケージの使い方
- インストール方法
requirements.txt #
パッケージの実行に必要なライブラリをrequirements.txtに記述します。Pythonのパッケージ管理システムpipで以下のコマンドを実行することで、requirements.txtを作成できます。
$ pip freeze > requirements.txt
別の環境でライブラリを一括でインストールするには、以下のコマンドを実行します。
$ pip install -r requirements.txt
setup.py #
pipでパッケージをインストール可能とするためには、setup.pyを記述する必要があります。
LICENSE #
LICENSEファイルにはソフトウェアのライセンス（MIT LicenseやApache Licenseなど）を、テキスト形式で記述します。慣習的に拡張子を付けないことも多いですが、WindowsやMac OSで開きやすいように、.txtや.mdの拡張子を付けても問題ないと思います。
参考 #
- Structuring Your Project — The Hitchhiker’s Guide to Python
- pythonプロジェクトのディレクトリ推奨構成 - Qiita
- あとで後悔しないPythonのディレクトリ構成をつくってみる - Qiita
ディレクトリ構成のテンプレートを生成するcookiecutterというPythonライブラリもあります。
