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之類的。