src レイアウト対フラットレイアウト#

「フラットレイアウト」とは、さまざまな設定ファイルや インポートパッケージ をすべてトップレベルのディレクトリに置くようなやり方で、プロジェクトのファイル群をひとつのフォルダまたはリポジトリに配置することです。

.
├── README.md
├── noxfile.py
├── pyproject.toml
├── setup.py
├── awesome_package/
│   ├── __init__.py
│   └── module.py
└── tools/
    ├── generate_awesomeness.py
    └── decrease_world_suck.py

「src レイアウト」は、インポート可能 (すなわち import awesome_package 、別名 インポートパッケージ) にするつもりのソースコードをサブディレクトリに置く点でフラットレイアウトとは異なります。このサブディレクトリは、典型的には src/ と命名されるので、「src レイアウト」と呼ばれるのです。

.
├── README.md
├── noxfile.py
├── pyproject.toml
├── setup.py
├── src/
│    └── awesome_package/
│       ├── __init__.py
│       └── module.py
└── tools/
    ├── generate_awesomeness.py
    └── decrease_world_suck.py

ここで、src レイアウトとフラットレイアウトの動作の違いで重要なものを掲出しておきましょう:

  • src レイアウトではそのソースコードを走らせるためにプロジェクトのインストールが要求されますが、フラットレイアウトではそのようなことはありません。

    これが意味するところは、src レイアウトの場合にはプロジェクトの開発ワークフローに追加的なステップ (典型的には、開発には 編集可能なインストール を使い、テストには通常のインストールを用いる) が必要になるということです。

  • src レイアウトを採用することは、今まさに開発中のソースコードを使ってしまうという事故を防ぐことを助けます。

    Python インタープリタはカレントワーキングディレクトリをインポートパスの先頭に含むので、これは妥当なことです。これが意味するところは、もしインストール済みのパッケージと同名のものがカレントワーキングディレクトリに存在するならば、カレントワーキングディレクトリにあるものが使われるであろうということです。これによって、配布物に一部ファイル群が含まれない結果に終わるという、プロジェクトのパッケージングツールの微妙な誤設定をもたらしかねません。

    src レイアウトを使えば、パッケージ群をプロジェクトのルートディレクトリとは異なるディレクトリに置くので、インストール済みのパッケージの方を使用することが保証され、このような誤設定を避ける助けになります。

  • src レイアウトを使うことで、インポートしようと意図した 編集可能なインストール だけをインポートするように強制することを助けます。

    これは、編集可能なインストール (のパッケージ) がインポートパスにそのディレクトリを追加するように動く パス設定ファイル を使って実装されている場合に、特に適切です。

    フラットレイアウトでは、インポートパスに他のプロジェクトファイル群 (例えば README.mdtox.ini) や、パッケージング/ツール使用の設定ファイル (例えば setup.pynoxfile.py) を追加します。こうすることによって、あるインポートが、通常のインストールではなくて編集可能なインストールの側を使うことを確実にするでしょう。