[python] プロジェクトのディレクトリ推奨構成

初めに

pythonのプロジェクトにおいて、個人的にフォルダ構造を考察してまとめる。
ただし、プロジェクトの目的に応じた構造や、時期（バージョン）に応じた構造、
推奨するソース（社会的権威）の差などがあるため、完全に標準的な構造はない。
そのため、記事として本構造が適切であると推奨しているわけではない。

プロジェクトの構造について

まず、ソースコード、ドキュメント、テストを保管するフォルダ構造が基本構造となる。
そのため、pythonにおける一般的な名称を含めて以下は必須となる。

• myproject：開発するプロジェクトの名称。名称は任意。
• docs：ドキュメントの保管フォルダ。名称は固定（推奨）。
• tests：テストコードの保管フォルダ。名称は固定（推奨）。

myproject(root) /
 ├─ myproject /
 ├─ docs /
 ├─ tests /

また、基本的な情報ファイルとして、以下のファイルを含む。

• 一般的な説明を記したファイル（README.md）
• 実行環境（使用しているライブラリ）を明示する・導入するファイル（requirements.txt、setup.py）
• ライセンスを明示するファイル（LICENSE）※公開する場合

myproject(root) /
 ├─ myproject /
 ├─ docs /
 ├─ tests /
 ├─ README.md (or README.rst)
 ├─ requirements.txt
 ├─ setup.py
 └─ LICENSE

myproject

プロジェクトにおけるソースコードを保管するフォルダ。
myprojectは仮名（プロジェクト名称の任意名）であり、固定の名称ではない。
root直下のソースコードのフォルダにおいて、プロジェクトと同名を推奨としていたり、
同名となるフォルダ自体を設けるのが一般的なフォルダ構成としては推奨されないため、推奨しないとするスタンスがある。

myproject(root) /
 ├─ myproject /
     ├─ __init__.py
     ├─ __main__.py
     ├─ cli.py
     ├─ mylib /
        ├─ __init__.py
        ├─ mylib.py

プロジェクトが小規模である場合（ソースコードがmain.pyのみなど）は必須でないが、
ソースコードフォルダ（モジュール）であることを明示する「__init__.py」と、
動作時の「おまじない」とよく言われる__name__属性における、__main__をプロジェクト内唯一として明示するために「__main__.py」を配置する。
「__main__.py」内は、以下のようなコードのみ記載する。(cli.pyの命名は任意）

if __name__ == '__main__':
    from .cli import main
    main()

なお、プロジェクト実行時はrootフォルダにおいて、「__main__.py」を起動するのではなく、プロジェクトとして実行する。

# pyhonファイル自体の実行例（今回非推奨）
python __main__.py

# pythonプロジェクト(module)の実行例（今回推奨）
python -m myproject

今回の構成では、前述の通り自作モジュール（mylib）はソースコード管理しているフォルダ内に保管している。
自作モジュールなどはプロジェクトのソースコードと同様のフォルダ内に全て保管するスタンスと、別途root直下に保管するスタンスがある。
root直下に保管するケースでは、他のプロジェクトでも使用するなどの運用面から判断されている場合がある。

モジュール内はモジュール認識のための「__init__.py」が必須だが、それ以外の命名は特に指定しない。
一般的な話として、プロジェク全体内で重複する命名は避けるべきではあると思う。

docs

プロジェクトにおけるドキュメントを保管するフォルダ。
一般にはpythonコミュニティで推奨されているマークアップ言語であるrst：reStructuredTextで記載する。
内容について記述できれば良いので、マークダウン(md)でも別に良い。
大規模プロジェクトやドキュメントの自動生成を行う場合はpythonにおいてはsphinxを用いることが一般的であるため、
sphinxによるドキュメント生成結果を保管してもよい。

myproject(root) /
 ├─ docs /
     ├─ conf.py
     ├─ index.rst

tests

プロジェクトにおけるテストのためのコードを保管するフォルダ。
テストに関してはテスト手法としての概念が別途あるため、どのような構成であるかは厳密でないが、
テストコード自体をプロジェクト内で保管するという意味で、保管フォルダとしては定義する。

myproject(root) /
 ├─ tests /
     ├─ test_basic.py
     ├─ test_advanced.py

追加の構成

完全に使用ケースによるが、一般的に以下のような追加があるケースが想定される。
プロジェクトの運用状況（公開・非公開（内製完結））やチーム員のスキル、管理状況に応じる。

• .venv：仮想環境の保管先
• notebooks：Jupyter Notebook保管先
• Examples：使用例の保管先
• docker：dockerプロジェクトの保管先
• .vscode：VScodeの設定保管先

最後に

本記事初段に記載した通り、適切な構造はプロジェクトに応じるため、一例としてまとめた。
本記事のプロジェクト構造について、内容をまとめると以下のようになる。

myproject(root) /
 ├─ docker /
 ├─ .venv /
 ├─ .vscode /
 ├─ notebooks /
 │
 ├─ myproject /
 │   ├─ __init__.py
 │   ├─ __main__.py
 │   ├─ cli.py
 │   ├─ mylib /
 │      ├─ __init__.py
 │      ├─ mylib.py
 │
 ├─ docs /
 │   ├─ conf.py
 │   ├─ index.rst
 │
 ├─ tests /
 │   ├─ test_basic.py
 │   ├─ test_advanced.py
 │
 ├─ README.md (or README.rst)
 ├─ requirements.txt
 ├─ setup.py
 └─ LICENSE

参考

Python ヒッチハイク・ガイド_プロジェクトの構造化