《Python高手之路（第3版）》——1.2 項目布局

本節書摘來自異步社群《python高手之路（第3版）》一書中的第1章，第1.2節，作者［法］julien danjou，王飛龍 譯，更多章節内容可以通路雲栖社群“異步社群”公衆号檢視。

項目結構應該保持簡單，審慎地使用包和層次結構：過深的層次結構在目錄導航時将如同夢魇，但過平的層次結構則會讓項目變得臃腫。

一個常犯的錯誤是将單元測試放在包目錄的外面。這些測試實際上應該被包含在軟體的子包中，以便：

不會偶爾被setuptools（或者其他打包庫）作為tests頂層子產品自動安裝；

能夠被安裝，且被其他包用于建構自己的單元測試。

圖1-1展示了一個項目的标準檔案層次結構。

<code>setup.py</code>是python安裝腳本的标準名稱。在安裝時，它會通過python分發工具（distutils）進行包的安裝。也可以通過<code>readme.rst</code>（或者<code>readme.txt</code>或其他合适的名字）為使用者提供重要資訊。<code>requirements.txt</code>應該包含python包所需要的依賴包，也就是說，所有這些包都會預先通過<code>pip</code>這樣的工具進行安裝，以保證你的包能正常工作。還可以包含<code>test-requirements.txt</code>，它隻列出運作測試套件所需要的依賴包。最後，<code>docs</code>檔案夾應該包括<code>restructuredtext</code>格式的文檔，以便能夠被sphinx處理（參見5.1節）。

包中還經常需要包含一些額外的資料，如圖檔、shell腳本等。不過，關于這類檔案如何儲存并沒有一個統一的标準。是以放到任何覺得合适的地方都可以。

下面這些頂層目錄也經常出現。

<code>etc</code>用來存放配置檔案的樣例。

<code>tools</code>用來存放與工具有關的shell腳本。

<code>bin</code>用來存放将被<code>setup.py</code>安裝的二進制腳本。

<code>data</code>用來存放其他類型的檔案，如媒體檔案。

一個常見的設計問題是根據将要存儲的代碼的類型來建立檔案或子產品。使用<code>functions.py</code>或者<code>exceptions.py</code>這樣的檔案是很糟糕的方式。這種方式對代碼的組織毫無幫助，隻能讓讀代碼的人在多個檔案之間毫無理由地來回切換。

此外，應該避免建立那種隻有一個<code>__init__.py</code>檔案的目錄，例如，如果<code>hooks.py</code>夠用的話就不要建立<code>hooks/__init__.py</code>。如果建立目錄，那麼其中就應該包含屬于這一分類/子產品的多個python檔案。