JavaScriptを有効にしてください

Pythonパッケージのディレクトリ構成

 ·   4 min read

はじめに

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

1
2
from .my_package import *
from .my_module_0 import *

また、my_module_0.pymy_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の拡張子を付けても問題ないと思います。

参考

 
ディレクトリ構成のテンプレートを生成するcookiecutterというPythonライブラリもあります。

シェアする

Helve
WRITTEN BY
Helve
関西在住、電機メーカ勤務のエンジニア。X(旧Twitter)で新着記事を配信中です

サイト内検索