web-dev-qa-db-ja.com

Pythonアプリケーションに最適なプロジェクト構造は何ですか?

あなたがPythonで自明ではないエンドユーザデスクトップ(Webではない)アプリケーションを開発したいと想像してください。プロジェクトのフォルダ階層を構成するための最善の方法は何ですか?

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

特に:

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

あまり問題ではありません。あなたを幸せにするものは何でもうまくいくでしょう。 Pythonプロジェクトは単純なものになることがあるので、愚かな規則はそれほど多くありません。

  • そのような種類のコマンドラインインターフェースのための/scriptsまたは/bin
  • テスト用の/tests
  • C言語ライブラリ用の/lib
  • ほとんどのドキュメントでは/doc
  • Epydocが生成したAPIドキュメントの/apidoc

そしてトップレベルディレクトリはREADME、Configそしてwhatnotを含むことができます。

難しい選択は/srcツリーを使うかどうかです。 JavaやCのように、Pythonは/src/lib、および/binを区別しません。

最上位の/srcディレクトリは意味がないと見なされることがあるので、最上位ディレクトリをアプリケーションの最上位アーキテクチャにすることができます。

  • /foo
  • /bar
  • /baz

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

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

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

339
S.Lott

Jean-Paul Calderone氏の Pythonプロジェクトのファイルシステム構造によると

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

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

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

行う:

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

しないでください。

  • ソースをsrcまたはlibというディレクトリに置きます。これがインストールせずに実行するのを難しくします。
  • テストをPythonパッケージの外側に置きます。これはインストールされたバージョンに対してテストを実行することを難しくします。
  • only __init__.pyがあるパッケージを作成してから、すべてのコードを__init__.pyに入れます。パッケージではなくモジュールを作成するだけで、簡単です。
  • ユーザがモジュールやパッケージを含むディレクトリを自分のインポートパスに追加することなく(PYTHONPATHまたは他の何らかの方法で)Pythonがモジュールやパッケージをインポートできるようにするために、魔法のハックを考え出してください。あなたは not を正しく扱うでしょうし、あなたのソフトウェアが彼らの環境では動かないとき、ユーザはあなたに腹を立てるでしょう。
201
Adrian

オープンソースのPythonプロジェクトを正しい方法で開く

その素晴らしい記事の プロジェクトのレイアウト の部分を抜粋してみましょう。

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

上から始めましょう。ほとんどのプロジェクトには、いくつかのトップレベルファイル(setup.py、README.md、requirements.txtなど)があります。すべてのプロジェクトが持つべき3つのディレクトリがあります。

  • プロジェクトのドキュメントを含むdocsディレクトリ
  • 実際のPythonパッケージを格納するプロジェクトの名前で名付けられたディレクトリ
  • 2か所のうちの1つにあるテストディレクトリ
    • テストコードとリソースを含むパッケージディレクトリの下
    • スタンドアロンの最上位ディレクトリとしてファイルの整理方法を理解するために、私のプロジェクトの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ディレクトリがあります。

104
David C. Bishop

"Python Packaging Authority"にはサンプルプロジェクトがあります。

https://github.com/pypa/sampleproject

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

25
guettli

python_boilerplate テンプレートを使用してプロジェクトを開始してみてください。これは主にベストプラクティス(例えば [ここ] )に従いますが、ある時点で自分のプロジェクトを複数のEggに分割する意思がある場合(そして最も単純なプロジェクト以外では私を信じて)に適しています。一般的な状況の1つは、ローカルで修正されたバージョンの他の人のライブラリを使用する必要がある場合です。

  • どこにソースを置きますか?

    • かなり大規模なプロジェクトでは、ソースをいくつかの卵に分割するのが合理的です。それぞれの卵はPROJECT_ROOT/src/<Egg_name>の下に別々のsetuptools-layoutとして入ります。
  • アプリケーション起動スクリプトはどこに置きますか。

    • 理想的な選択肢は、アプリケーション起動スクリプトを卵の1つにentry_pointとして登録することです。
  • IDEプロジェクトの要所はどこにありますか。

    • IDEに依存します。彼らの多くは自分のものをプロジェクトのルートのPROJECT_ROOT/.<something>に入れていますが、これで問題ありません。
  • あなたはユニット/受け入れテストをどこに置きますか?

    • それぞれの卵はPROJECT_ROOT/src/<Egg_name>/testsディレクトリに保存された別々のテストのセットを持っています。私は個人的にそれらを実行するためにpy.testを使うことを好みます。
  • 設定ファイルなどの非Pythonデータはどこに置きますか?

    • 場合によります。 Python以外のデータにはさまざまな種類があります。
      • "Resources"、すなわち、Egg内にパッケージ化する必要があるデータ。このデータは、パッケージ名前空間内のどこかにある、対応するEggディレクトリに入ります。それはpkg_resourcesパッケージを通して使うことができます。
      • "Config-files"、つまり、プロジェクトのソースファイルの外部と見なされるが、アプリケーションの実行開始時にいくつかの値で初期化される必要がある非Pythonファイル。開発中、私はそのようなファイルをPROJECT_ROOT/configに保存することを好みます。展開にはさまざまなオプションがあります。 Windowsでは%APP_DATA%/<app-name>/config、Linuxでは/etc/<app-name>または/opt/<app-name>/configを使用できます。
      • 生成ファイル、すなわち、実行中にアプリケーションによって作成または変更される可能性があるファイル。開発中はPROJECT_ROOT/varに、Linux展開中は/varの下に置いておくことをお勧めします。
  • pyd/soバイナリー拡張モジュール用のC++などの非Pythonソースをどこに置きますか?
    • PROJECT_ROOT/src/<Egg_name>/native

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

16
KT.

私の経験では、それは繰り返しの問題です。データとコードは、どこに行っても構わないと思う場所に配置してください。たぶん、あなたはとにかく間違っているでしょう。しかし、物事がどのように形成されるのかを正確に把握できれば、これらの種類の推測を行うのに適した立場になります。

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

とは言っても、私は私の最初のポイントに戻ります。それをあまり大きくしないでください。あなたのために働くように思われるどこかにそれを置きなさい。うまく動かないものが見つかった場合は、それを変更することができます(そして変更すべきです)。

14
Jason Baker

Python以外のデータは、 setuptoolspackage_dataサポートを使用して、Pythonモジュール内にバンドルするのが最善です。私が強くお勧めすることの1つは、名前空間パッケージを使用して複数のプロジェクトが使用できる共有名前空間を作成することです。これは、パッケージをcom.yourcompany.yourprojectに配置するという(および共有com.yourcompany.utils名前空間を持つことができる)Javaの慣例によく似ています。

あなたが十分に良いソース管理システムを使っているならば、それは名前を変更してもマージを処理するでしょう。 Bazaar これは特に得意です。

ここで他のいくつかの答えに反して、私はsrcディレクトリをトップレベルにすることについて+1します(doctestディレクトリを一緒にして)。ドキュメンテーションディレクトリツリーのための特定のコンベンションはあなたが使用しているものによって異なります。たとえば、 Sphinx には、クイックスタートツールがサポートする独自の規則があります。

Setuptoolsとpkg_resourcesを利用してください。これは他のプロジェクトがあなたのコードの特定のバージョンに頼ることをはるかに容易にします(そしてあなたがpackage_dataを使っているならば、複数のバージョンが異なる非コードファイルと共に同時にインストールされることを)。

7
Charles Duffy