Pythonアプリケーションに最適なプロジェクト構造は何ですか？[閉まっている]

Pythonで重要なエンドユーザーデスクトップ（ウェブではない）アプリケーションを開発したいとします。プロジェクトのフォルダー階層を構造化する最良の方法は何ですか？

望ましい機能は、メンテナンスの容易さ、IDEとの親和性、ソース管理の分岐/マージへの適合性、およびインストールパッケージの簡単な生成です。

特に：

1. ソースはどこに置きますか？
2. アプリケーションの起動スクリプトはどこに配置しますか？
3. IDEプロジェクトをどこに配置しますか？
4. ユニット/受け入れテストはどこに置きますか？
5. 設定ファイルなどのPython以外のデータはどこに配置しますか？
6. pyd / soバイナリ拡張モジュール用のC ++などの非Pythonソースをどこに置きますか？

あまり問題ではありません。あなたを幸せにするものは何でも働きます。Pythonプロジェクトは単純なものになる可能性があるため、多くの愚かなルールはありません。

• /scriptsまたは/binその種のコマンドラインインターフェースのもののために
• /tests あなたのテストのために
• /lib C言語ライブラリ用
• /doc ほとんどのドキュメント
• /apidoc Epydocで生成されたAPIドキュメントの場合。

また、最上位のディレクトリには、README、Config、その他を含めることができます。

難しい選択は、/srcツリーを使用するかどうかです。Pythonはの区別を持っていない/src、/libと、/binJavaやCのように持っています。

トップレベルの/srcディレクトリは一部の人にとって無意味と見なされているため、トップレベルのディレクトリはアプリケーションのトップレベルのアーキテクチャになる可能性があります。

• /foo
• /bar
• /baz

これらすべてを「name-of-my-product」ディレクトリの下に置くことをお勧めします。したがって、という名前のアプリケーションを作成している場合、quuxこのすべてのものを含むディレクトリはという名前になり /quuxます。

別のプロジェクトのPYTHONPATHを含める/path/to/quux/fooと、QUUX.fooモジュールを再利用できます。

私の場合、Komodo Editを使用しているので、IDE cuftは単一の.KPFファイルです。実際にはそれを最上位/quuxディレクトリに置き、SVNへの追加は省略します。

ジャン=ポール・Calderone者によるPythonプロジェクトのファイルシステムの構造：

Project/
|-- bin/
|   |-- project
|
|-- project/
|   |-- test/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |   
|   |-- __init__.py
|   |-- main.py
|
|-- setup.py
|-- README

Jean-Paul Calderoneによるこのブログ投稿は、Freenodeの#pythonの回答として一般的に提供されています。

Pythonプロジェクトのファイルシステム構造

行う：

• プロジェクトに関連する名前をディレクトリに付けます。たとえば、プロジェクトの名前が「Twisted」の場合、ソースファイルのトップレベルディレクトリに名前を付けますTwisted。リリースするときは、バージョン番号のサフィックスを含める必要がありますTwisted-2.5。
• ディレクトリTwisted/binを作成し、実行ファイルがあればそこに配置します。.pyそれらがPythonソースファイルであっても、拡張子を付けないでください。プロジェクトの他の場所で定義されたメイン関数のインポートと呼び出しを除いて、コードをコードに含めないでください。（わずかなしわ：Windowsでは、インタープリターはファイル拡張子によって選択されるため、Windowsユーザーは実際には.py拡張子を必要とします。そのため、Windows用にパッケージ化するときに、それを追加することができます。残念ながら、簡単なdistutilsトリックはありません私はこのプロセスを自動化することを知っています。POSIXでは.py拡張子が唯一のイボであるので、Windowsでは欠落は実際のバグですが、ユーザーベースにWindowsユーザーが含まれている場合は、.pyどこでも拡張子。）
• プロジェクトが単一のPythonソースファイルとして表現できる場合は、それをディレクトリに配置し、プロジェクトに関連する名前を付けます。たとえば、Twisted/twisted.py。複数のソースファイルが必要な場合は、代わりに（Twisted/twisted/空のを使用してTwisted/twisted/__init__.py）パッケージを作成し、そこにソースファイルを配置します。たとえば、Twisted/twisted/internet.py。
• 単体テストをパッケージのサブパッケージに入れます（注-これは、上記の単一のPythonソースファイルオプションがトリックだったということを意味します- 単体テストには常に少なくとも1つの他のファイルが必要です）。たとえば、Twisted/twisted/test/。もちろん、でパッケージにしてくださいTwisted/twisted/test/__init__.py。のようなファイルにテストを配置しますTwisted/twisted/test/test_internet.py。
• 気分が良ければ、それぞれソフトウェアを追加Twisted/READMEしTwisted/setup.pyて説明し、インストールします。

してはいけないこと：

• srcまたはと呼ばれるディレクトリにソースを置きますlib。これにより、インストールしないと実行が困難になります。
• テストをPythonパッケージの外に置きます。これにより、インストールされているバージョンに対してテストを実行することが困難になります。
• そのパッケージの作成だけであり__init__.py、その後にすべてのあなたのコードを配置します__init__.py。パッケージの代わりにモジュールを作るだけで、より簡単になります。
• ユーザーがそれらを含むディレクトリをインポートパスに（PYTHONPATHまたはその他のメカニズムを介して）追加することなく、Pythonがモジュールまたはパッケージをインポートできるようにする魔法のハックを考え出してください。すべてのケースを正しく処理するわけではなく、ソフトウェアが環境で動作しない場合、ユーザーはあなたに腹を立てます。

Pythonプロジェクトを正しい方法でオープンソーシングするをご覧ください。

その優れた記事のプロジェクトレイアウトの一部を抜粋してみましょう。

プロジェクトを設定するときは、レイアウト（またはディレクトリ構造）を正しく理解することが重要です。賢明なレイアウトとは、潜在的な貢献者がコードの一部を探すために永遠に費やす必要がないことを意味します。ファイルの場所は直感的です。私たちは既存のプロジェクトを扱っているので、おそらく何かを移動する必要があるでしょう。

上から始めましょう。ほとんどのプロジェクトには、多数の最上位ファイル（setup.py、README.md、requirements.txtなど）があります。次に、すべてのプロジェクトが持つべき3つのディレクトリがあります。

• プロジェクトドキュメントを含むdocsディレクトリ
• 実際のPythonパッケージを格納するプロジェクトの名前が付けられたディレクトリ
• 2つの場所のいずれかにあるテストディレクトリ
  • テストコードとリソースを含むパッケージディレクトリの下
  • スタンドアロンの最上位ディレクトリとしてファイルをどのように編成するかをよりよく理解するために、ここに私のプロジェクトの1つであるsandmanのレイアウトの簡単なスナップショットを示します。

$ pwd
~/code/sandman
$ tree
.
|- LICENSE
|- README.md
|- TODO.md
|- docs
|   |-- conf.py
|   |-- generated
|   |-- index.rst
|   |-- installation.rst
|   |-- modules.rst
|   |-- quickstart.rst
|   |-- sandman.rst
|- requirements.txt
|- sandman
|   |-- __init__.py
|   |-- exception.py
|   |-- model.py
|   |-- sandman.py
|   |-- test
|       |-- models.py
|       |-- test_sandman.py
|- setup.py

ご覧のとおり、最上位のファイル、docsディレクトリ（sphinxが生成したドキュメントを置く空のディレクトリ）、sandmanディレクトリ、sandmanの下にtestディレクトリがあります。

「Python Packaging Authority」にはサンプルプロジェクトがあります：

https://github.com/pypa/sampleproject

これは、Python Packaging User Guideのチュートリアルのパッケージ化と配布プロジェクトに関するチュートリアルの補助として存在するサンプルプロジェクトです。

python_boilerplateテンプレートを使用してプロジェクトを開始してみてください。これは主にベストプラクティスに従っていますが（例：ここにあるもの）、ある時点でプロジェクトを複数の卵に分割したいと思った場合に適しています（そして、最も単純なプロジェクト以外では、私を信じてください。一般的な状況は、ローカルで変更されたバージョンの誰かのライブラリを使用する必要がある場合です）。

• ソースはどこに置きますか？

  • かなり大きなプロジェクトの場合、ソースをいくつかの卵に分割することは理にかなっています。各卵は、個別のsetuptools-layoutとしてに配置されPROJECT_ROOT/src/<egg_name>ます。

• アプリケーションの起動スクリプトはどこに配置しますか？

  • 理想的なオプションは、アプリケーションの起動スクリプトをentry_point卵の1つとして登録することです。

• IDEプロジェクトをどこに配置しますか？

  • IDEによって異なります。それらの多くはPROJECT_ROOT/.<something>、プロジェクトのルートに自分のものを保持していますが、これは問題ありません。

• ユニット/受け入れテストはどこに置きますか？

  • 各卵は、そのPROJECT_ROOT/src/<egg_name>/testsディレクトリに保持されているテストの個別のセットを持っています。私は個人的にpy.testそれらを実行するために使用することを好みます。

• 設定ファイルなどのPython以外のデータはどこに配置しますか？

  • 場合によります。Python以外のデータにはさまざまなタイプがあります。
    • 「リソース」、つまり卵内にパッケージ化する必要があるデータ。このデータは、パッケージの名前空間内のどこかにある対応するeggディレクトリに送られます。からのpkg_resourcesパッケージを介してsetuptools、またはPython 3.7以降importlib.resources、標準ライブラリのモジュールを介して使用できます。
    • 「Config-files」、つまりプロジェクトのソースファイルの外部と見なされる非Pythonファイルですが、アプリケーションの実行開始時にいくつかの値で初期化する必要があります。開発中、私はそのようなファイルをに保持することを好みますPROJECT_ROOT/config。展開にはさまざまなオプションがあります。Windowsの場合%APP_DATA%/<app-name>/config、Linuxの場合、/etc/<app-name>または/opt/<app-name>/config。
    • 生成されたファイル、つまり、実行中にアプリケーションによって作成または変更される可能性のあるファイル。私はそれらをPROJECT_ROOT/var開発中、および/varLinuxの展開中は保持したいと思います。
• pyd / soバイナリ拡張モジュール用のC ++などの非Pythonソースをどこに置きますか？
  • に PROJECT_ROOT/src/<egg_name>/native

ドキュメンテーションは通常、PROJECT_ROOT/docまたはに含まれますPROJECT_ROOT/src/<egg_name>/doc（これは、卵の一部を個別の大きなプロジェクトと見なすかどうかによって異なります）。PROJECT_ROOT/buildout.cfgとのようなファイルに追加の設定がいくつかありPROJECT_ROOT/setup.cfgます。

私の経験では、それは反復の問題です。データとコードをどこにでも置くと思います。とにかく、あなたは間違っているでしょう。しかし、物事がどのように形作られるのかについて正確に理解できれば、この種の推測を行うためのはるかに優れた立場になります。

拡張ソースに関しては、pythonのディレクトリと他のさまざまな言語のディレクトリを含むトランクの下にコードディレクトリがあります。個人的には、次回、拡張コードを独自のリポジトリーに入れてみる傾向があります。

そうは言っても、私は最初のポイントに戻ります。あまり大きな取引をしないでください。それはあなたのために働くように見えるどこかにそれを置きます。機能しないものが見つかった場合は、変更することができます（変更する必要があります）。

Python以外のデータはpackage_data、setuptoolsのサポートを使用してPythonモジュール内にバンドルするのが最適です。名前空間パッケージを使用して、複数のプロジェクトが使用できる共有名前空間を作成することを強くお勧めします-パッケージを配置するJavaの規則com.yourcompany.yourproject（および共有できるcom.yourcompany.utils名前空間。

ブランチとマージを再作成します。十分なソース管理システムを使用している場合、名前変更によってもマージを処理します。バザールはこれが特に得意です。

ここでの他のいくつかの答えに反して、私はsrcディレクトリをトップレベルに持つことで+1しています（docそして、test横にディレクトリがあります）。ドキュメントディレクトリツリーの特定の規則は、使用しているものによって異なります。たとえばSphinxには、クイックスタートツールがサポートする独自の規則があります。

setuptoolsとpkg_resourcesを活用してください。これにより、他のプロジェクトがコードの特定のバージョンに依存することがはるかに容易になります（さらに、を使用している場合、複数のバージョンを異なる非コードファイルと共に同時にインストールすることができますpackage_data）。