Python封裝應用程序的最佳項目結構是什麼?

Python封裝應用程序的最佳項目結構是什麼?

轉載來源於stackoverflow：https://stackoverflow.com/questions/193161/what-is-the-best-project-structure-for-a-python-application

和http://www.cnblogs.com/alex3714/articles/5765046.html#3719169

 

開發一個終端用戶桌面應用（非網頁），最佳的項目文件夾層次結構是怎樣的？

理想的項目文件夾層次結構的主要特徵是易於維護，友好的ide，合適的源代碼的控制分支/合併，輕鬆生成安裝包。

 

注意點：

1. Where do you put the source?
2. Where do you put application startup scripts?
3. Where do you put the IDE project cruft?
4. Where do you put the unit/acceptance tests?
5. Where do you put non-Python data such as config files?
6. Where do you put non-Python sources such as C++ for pyd/so binary extension modules?

 

 

Project/      # When you do releases, you should include a version number suffix: Twisted-2.5.

|-- bin/       存放項目的一些可執行文件，固然你能夠起名script/之類的也行。

|   |-- project  不要在它們中添加任何代碼，除非對項目中其餘地方定義的一個主函數調用和調用。

|

|-- project/      存放項目的全部源代碼。(1) 源代碼中的全部模塊、包都應該放在此目錄。不要置於頂層目錄。 

|   |-- test/       (2) 其子目錄tests/存放單元測試代碼；

|   |   |-- __init__.py

|   |   |-- test_main.py

|   |  

|   |-- __init__.py

|   |-- main.py    (3) 程序的入口最好命名爲main.py。

|   |  

|-- docs/   存放一些文檔。

|   |-- conf.py    

|   |-- abc.rst

|

|-- setup.py   安裝、部署、打包的腳本。

|-- requirements  存放軟件依賴的外部Python包列表

|-- README   項目說明文件。

 

 

Do:

• name the directory something related to your project. For example, if your project is named "Twisted", name the top-level directory for its source files Twisted. When you do releases, you should include a version number suffix: Twisted-2.5.
• create a directory Twisted/bin and put your executables there, if you have any. Don't give them a .py extension, even if they are Python source files. Don't put any code in them except an import of and call to a main function defined somewhere else in your projects. (Slight wrinkle: since on Windows, the interpreter is selected by the file extension, your Windows users actually do want the .py extension. So, when you package for Windows, you may want to add it. Unfortunately there's no easy distutils trick that I know of to automate this process. Considering that on POSIX the .py extension is a only a wart, whereas on Windows the lack is an actual bug, if your userbase includes Windows users, you may want to opt to just have the .py extension everywhere.)
• If your project is expressable as a single Python source file, then put it into the directory and name it something related to your project. For example, Twisted/twisted.py. If you need multiple source files, create a package instead (Twisted/twisted/, with an empty Twisted/twisted/__init__.py) and place your source files in it. For example, Twisted/twisted/internet.py.
• put your unit tests in a sub-package of your package (note - this means that the single Python source file option above was a trick - you always need at least one other file for your unit tests). For example, Twisted/twisted/test/. Of course, make it a package with Twisted/twisted/test/__init__.py. Place tests in files like Twisted/twisted/test/test_internet.py.
• add Twisted/README and Twisted/setup.py to explain and install your software, respectively, if you're feeling nice.

 

Don't:

• put your source in a directory called src or lib. This makes it hard to run without installing.不要將源代碼的目錄命名爲src或lib。這會致使安裝困難。
• put your tests outside of your Python package. This makes it hard to run the tests against an installed version.不要將tests文件放在python包以外，不然會致使在安裝的版本上運行測試出現問題。
• create a package that only has a __init__.py and then put all your code into __init__.py. Just make a module instead of a package, it's simpler.不要建立一個只有一個__init__的包，而且將全部的代碼都放在這個包裏面。而是應該建立一個模塊而不是包，相對於建立包，建立模塊管理更加簡單。
• try to come up with magical hacks to make Python able to import your module or package without having the user add the directory containing it to their import path (either via PYTHONPATH or some other mechanism). You will not correctly handle all cases and users will get angry at you when your software doesn't work in their environment. 嘗試想一些方法使得Python可以不須要用戶設置添加目錄到導入環境中，經過Python路徑或其餘機制自動的導入項目中的模塊和包。若是你的軟件不能正確地處理全部的狀況，當你的軟件在他們的環境中不工做時，用戶會很是生氣。

 

setup.py

通常來講，用setup.py來管理代碼的打包、安裝、部署問題。業界標準的寫法是用Python流行的打包工具setuptools來管理這些事情。這種方式廣泛應用於開源項目中。不過這裏的核心思想不是用標準化的工具來解決這些問題，而是說，一個項目必定要有一個安裝部署工具，能快速便捷的在一臺新機器上將環境裝好、代碼部署好和將程序運行起來。

setup.py能夠將這些事情自動化起來，提升效率、減小出錯的機率。"複雜的東西自動化，能自動化的東西必定要自動化。"是一個很是好的習慣。

setuptools的文檔比較龐大，剛接觸的話，可能不太好找到切入點。學習技術的方式就是看他人是怎麼用的，能夠參考一下Python的一個Web框架，flask是如何寫的: setup.py

固然，簡單點本身寫個安裝腳本（deploy.sh）替代setup.py也何嘗不可。

 

 

requirements.txt

這個文件存在的目的是:

1. 方便開發者維護軟件的包依賴。將開發過程當中新增的包添加進這個列表中，避免在setup.py安裝依賴時漏掉軟件包。
2. 方便讀者明確項目使用了哪些Python包。

這個文件的格式是每一行包含一個包依賴的說明，一般是flask>=0.10這種格式，要求是這個格式能被pip識別，這樣就能夠簡單的經過 pip install -r requirements.txt來把全部Python包依賴都裝好了。具體格式說明： 點這裏。

 

 

README   項目說明文件。

它須要說明如下幾個事項:

1. 軟件定位，軟件的基本功能。
2. 運行代碼的方法: 安裝環境、啓動命令等。
3. 簡要的使用說明。
4. 代碼目錄結構說明，更詳細點能夠說明軟件的基本原理。
5. 常見問題說明。

 

 

關於配置文件的使用方法

注意，在上面的目錄結構中，沒有將conf.py放在源碼目錄下，而是放在docs/目錄下。

不少項目對配置文件的使用作法是:

1. 配置文件寫在一個或多個python文件中，好比此處的conf.py。
2. 項目中哪一個模塊用到這個配置文件就直接經過import conf這種形式來在代碼中使用配置。

這種作法我不太贊同:

1. 這讓單元測試變得困難（由於模塊內部依賴了外部配置）
2. 另外一方面配置文件做爲用戶控制程序的接口，應當能夠由用戶自由指定該文件的路徑。
3. 程序組件可複用性太差，由於這種貫穿全部模塊的代碼硬編碼方式，使得大部分模塊都依賴conf.py這個文件。

因此，我認爲配置的使用，更好的方式是，

1. 模塊的配置都是能夠靈活配置的，不受外部配置文件的影響。
2. 程序的配置也是能夠靈活控制的。

可以佐證這個思想的是，用過nginx和mysql的同窗都知道，nginx、mysql這些程序均可以自由的指定用戶配置。

因此，不該當在代碼中直接import conf來使用配置文件。上面目錄結構中的conf.py，是給出的一個配置樣例，不是在寫死在程序中直接引用的配置文件。能夠經過給main.py啓動參數指定配置路徑的方式來讓程序讀取配置內容。固然，這裏的conf.py你能夠換個相似的名字，好比settings.py。或者你也可使用其餘格式的內容來編寫配置文件，好比settings.yaml之類的。