※記事内に商品プロモーションを含むことがあります。

はじめに

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というモジュールがある場合、以下のように書きます。

1
2

from .my_package import *
from .my_module_0 import *

また、my_module_0.pyにmy_func()という名前の関数が定義されているとします。このとき、パッケージの外部から以下3つの方法で呼び出せます（他にも呼び出し方はあります）。

例1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 例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ライブラリもあります。

• Pythonメモ _ cookiecutterでプロジェクトの雛形を作成する - もた日記