python 軟件目錄結構規范 與 模塊導入

為什么要規范軟件目錄結構？

1. 可讀性高: 不熟悉這個項目的代碼的人，一眼就能看懂目錄結構，知道程序啟動腳本是哪個，測試目錄在哪兒，配置文件在哪兒等等。從而非常快速的了解、跟進這個項目。
2. 可維護性高: 定義好組織規則后，維護者就能很明確地知道，新增的哪個文件和代碼應該放在什么目錄之下。這個好處是，隨着時間的推移，代碼/配置的規模增加，項目結構不會混亂，仍然能夠組織良好。

所以，在實際項目開發過程中，良好的目錄結構是十分必要的。即使追求個人風格，也要在遵循基本的規范的基礎上，否則編寫的代碼只有自己願意看，這與在代碼編寫過程中必要的注釋是相同的。

目錄組織方式

假設項目名為foo，必要的目錄結構如下所示：

Foo/
|-- bin/
|   |-- foo
|
|-- foo/
|   |-- tests/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |
|   |-- __init__.py
|   |-- main.py
|
|-- docs/
|   |-- conf.py
|   |-- abc.rst
|
|-- setup.py
|-- requirements.txt
|-- README

簡要解釋一下:

1. bin/: 存放項目的一些可執行文件，當然你可以起名script/之類的也行。
2. foo/: 存放項目的所有源代碼。(1) 源代碼中的所有模塊、包都應該放在此目錄。不要置於頂層目錄。(2) 其子目錄tests/存放單元測試代碼； (3) 程序的入口最好命名為main.py。
3. docs/: 存放一些文檔，配置文件等。
4. setup.py: 安裝、部署、打包的腳本。
5. requirements.txt: 存放軟件依賴的外部Python包列表，這只是一個txt文件。
6. README: 項目說明文件。

關於配置文件：

此處配置文件conf.py並未直接放於源碼目錄下，而是放置在docs/目錄下，模塊的配置應該是靈活的，不受外界配置文件的影響，所以不應當在代碼中直接import conf 來使用配置文件，可以通過給main.py啟動參數指定配置路徑的方式來讓程序讀取配置內容。

 關於setup.py

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

整合打包時應核對requirements中所記錄的python包列表與實際使用的Python包是否吻合，包括使用包的版本

關於requirements.txt

這個文件存在的目的是:

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

　　requirements.txt中存放軟件依賴的外部Python包列表最好和開發過程中軟件實際使用的Python包保持實時同步，這樣在最后打包setup.py文件時才不會有遺漏。

關於ReadMe

這個同setup.py一樣，是每個項目都應該有的一個文件，目的是能簡要描述該項目的信息，讓讀者快速了解這個項目。

它需要說明以下幾個事項:

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

ReadMe的作用就好像是干練的用戶使用手冊說明，這樣的文檔多在項目完結的時候進行撰寫。

 

由於軟件目錄結構的存在，不可避免的會存在跨目錄導入模塊的情況。

模塊導入詳解

先了解幾個概念：

1. 模塊(python file)：本質是.py結尾的python文件。
2. 包(python package)：本質是目錄(也就是上文介紹的目錄結構規范)，在包中編寫模塊，組織模塊，每創建一個python package都會在自動生成一個__init__.py文件。

導入方法：

1. 導入模塊方法：

# 基本導入模塊
import sys
# 同時導入多個模塊
import sys, copy, numpy, pandas
# 同時導入多個模塊並部分重命名
import sys, numpy as np, pandas as pd, tensorflow as tf

#從某個包中導入某個模塊
from tensorflow.contrib import rnn

　　import只能導入當前目錄，標准庫以及第三方庫中的模塊。在import時，還可以直接導入該模塊中的某個變量或者是方法，即import XXX.xxx  (xxx可以是變量或是方法)

　　2.  多級目錄導入方法：

需要了解兩個模塊：

• sys模塊
• os模塊

# 多級目錄導入方法：
import sys, os
sys.path()   # 返回執行當前文件執行搜索的所有路徑
BaseDir = os.path.abspath(__file__)  # 獲取當前文件的路徑
addDir = os.path.dirname(os.path.dirname(BaseDir))  # 獲取父目錄地址
sys.path.append(addDir) #將改地址添加至默認搜索路徑中
from logs import logger  # 從包中導入模塊

　　sys.path():其返回值是一個列表，內包含搜索的所有路徑。

　　sys.path.append() : 是將目標路徑追加至列表的末尾，也就是說，在搜索模塊時，會先在當前目錄進行搜索，進而到標准庫，第三方庫中進行搜索，如果都沒有改模塊，才會到追加的這個路徑中進行搜索。如果標准庫或第三方庫中存在同名的模塊，將不能訪問到添加路徑下的模塊。

　　sys.path.insert(): 會把路徑加入到python系統路徑列表的最前邊