5. 導入系統(tǒng)?

5.2.1. 常規(guī)包?

Python 定義了兩種類型的包，常規(guī)包 和 命名空間包。 常規(guī)包是傳統(tǒng)的包類型，它們在 Python 3.2 及之前就已存在。 常規(guī)包通常以一個包含 __init__.py 文件的目錄形式實現(xiàn)。 當一個常規(guī)包被導入時，這個 __init__.py 文件會隱式地被執(zhí)行，它所定義的對象會被綁定到該包命名空間中的名稱。__init__.py 文件可以包含與任何其他模塊中所包含的 Python 代碼相似的代碼，Python 將在模塊被導入時為其添加額外的屬性。

例如，以下文件系統(tǒng)布局定義了一個最高層級的 parent 包和三個子包:

parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py

導入 parent.one 將隱式地執(zhí)行 parent/__init__.py 和 parent/one/__init__.py。 后續(xù)導入 parent.two 或 parent.three 則將分別執(zhí)行 parent/two/__init__.py 和 parent/three/__init__.py。

5.2.2. 命名空間包?

命名空間包是由多個 部分 構成的，每個部分為父包增加一個子包。 各個部分可能處于文件系統(tǒng)的不同位置。 部分也可能處于 zip 文件中、網(wǎng)絡上，或者 Python 在導入期間可以搜索的其他地方。 命名空間包并不一定會直接對應到文件系統(tǒng)中的對象；它們有可能是無實體表示的虛擬模塊。

命名空間包的 __path__ 屬性不使用普通的列表。 而是使用定制的可迭代類型，如果其父包的路徑 (或者最高層級包的 sys.path) 發(fā)生改變，這種對象會在該包內(nèi)的下一次導入嘗試時自動執(zhí)行新的對包部分的搜索。

命名空間包沒有 parent/__init__.py 文件。 實際上，在導入搜索期間可能找到多個 parent 目錄，每個都由不同的部分所提供。 因此 parent/one 的物理位置不一定與 parent/two 相鄰。 在這種情況下，Python 將為頂級的 parent 包創(chuàng)建一個命名空間包，無論是它本身還是它的某個子包被導入。

另請參閱 PEP 420 了解對命名空間包的規(guī)格描述。

5.3.1. 模塊緩存?

在導入搜索期間首先會被檢查的地方是 sys.modules。 這個映射起到緩存之前導入的所有模塊的作用（包括其中間路徑）。 因此如果之前導入過 foo.bar.baz，則 sys.modules 將包含 foo, foo.bar 和 foo.bar.baz 條目。 每個鍵的值就是相應的模塊對象。

在導入期間，會在 sys.modules 查找模塊名稱，如存在則其關聯(lián)的值就是需要導入的模塊，導入過程完成。 然而，如果值為 None，則會引發(fā) ModuleNotFoundError。 如果找不到指定模塊名稱，Python 將繼續(xù)搜索該模塊。

sys.modules 是可寫的。刪除鍵可能不會破壞關聯(lián)的模塊（因為其他模塊可能會保留對它的引用），但它會使命名模塊的緩存條目無效，導致 Python 在下次導入時重新搜索命名模塊。鍵也可以賦值為 None ，強制下一次導入模塊導致 ModuleNotFoundError 。

但是要小心，因為如果你還保有對某個模塊對象的引用，同時停用其在 sys.modules 中的緩存條目，然后又再次導入該名稱的模塊，則前后兩個模塊對象將 不是 同一個。 相反地，importlib.reload() 將重用 同一個 模塊對象，并簡單地通過重新運行模塊的代碼來重新初始化模塊內(nèi)容。

5.3.2. 查找器和加載器?

如果指定名稱的模塊在 sys.modules 找不到，則將發(fā)起調(diào)用 Python 的導入?yún)f(xié)議以查找和加載該模塊。 此協(xié)議由兩個概念性模塊構成，即 查找器 和 加載器。 查找器的任務是確定是否能使用其所知的策略找到該名稱的模塊。 同時實現(xiàn)這兩種接口的對象稱為 導入器 —— 它們在確定能加載所需的模塊時會返回其自身。

Python 包含了多個默認查找器和導入器。 第一個知道如何定位內(nèi)置模塊，第二個知道如何定位凍結模塊。 第三個默認查找器會在 import path 中搜索模塊。 import path 是一個由文件系統(tǒng)路徑或 zip 文件組成的位置列表。 它還可以擴展為搜索任意可定位資源，例如由 URL 指定的資源。

導入機制是可擴展的，因此可以加入新的查找器以擴展模塊搜索的范圍和作用域。

查找器并不真正加載模塊。 如果它們能找到指定名稱的模塊，會返回一個 模塊規(guī)格說明，這是對模塊導入相關信息的封裝，供后續(xù)導入機制用于在加載模塊時使用。

以下各節(jié)描述了有關查找器和加載器協(xié)議的更多細節(jié)，包括你應該如何創(chuàng)建并注冊新的此類對象來擴展導入機制。

5.3.3. 導入鉤子?

導入機制被設計為可擴展；其中的基本機制是 導入鉤子。 導入鉤子有兩種類型: 元鉤子 和 導入路徑鉤子。

元鉤子在導入過程開始時被調(diào)用，此時任何其他導入過程尚未發(fā)生，但 sys.modules 緩存查找除外。 這允許元鉤子重載 sys.path 過程、凍結模塊甚至內(nèi)置模塊。 元鉤子的注冊是通過向 sys.meta_path 添加新的查找器對象，具體如下所述。

導入路徑鉤子是作為 sys.path (或 package.__path__) 過程的一部分，在遇到它們所關聯(lián)的路徑項的時候被調(diào)用。 導入路徑鉤子的注冊是通過向 sys.path_hooks 添加新的可調(diào)用對象，具體如下所述。

5.3.4. 元路徑?

當指定名稱的模塊在 sys.modules 中找不到時，Python 會接著搜索 sys.meta_path，其中包含元路徑查找器對象列表。 這些查找器按順序被查詢以確定它們是否知道如何處理該名稱的模塊。 元路徑查找器必須實現(xiàn)名為 find_spec() 的方法，該方法接受三個參數(shù)：名稱、導入路徑和目標模塊（可選）。 元路徑查找器可使用任何策略來確定它是否能處理指定名稱的模塊。

如果元路徑查找器知道如何處理指定名稱的模塊，它將返回一個說明對象。 如果它不能處理該名稱的模塊，則會返回 None。 如果 sys.meta_path 處理過程到達列表末尾仍未返回說明對象，則將引發(fā) ModuleNotFoundError。 任何其他被引發(fā)異常將直接向上傳播，并放棄導入過程。

元路徑查找器的 find_spec() 方法調(diào)用帶有兩到三個參數(shù)。 第一個是被導入模塊的完整限定名稱，例如 foo.bar.baz。 第二個參數(shù)是供模塊搜索使用的路徑條目。 對于最高層級模塊，第二個參數(shù)為 None，但對于子模塊或子包，第二個參數(shù)為父包 __path__ 屬性的值。 如果相應的 __path__ 屬性無法訪問，將引發(fā) ModuleNotFoundError。 第三個參數(shù)是一個將被作為稍后加載目標的現(xiàn)有模塊對象。 導入系統(tǒng)僅會在重加載期間傳入一個目標模塊。

對于單個導入請求可以多次遍歷元路徑。 例如，假設所涉及的模塊都尚未被緩存，則導入 foo.bar.baz 將首先執(zhí)行頂級的導入，在每個元路徑查找器 (mpf) 上調(diào)用 mpf.find_spec("foo", None, None)。 在導入 foo 之后，foo.bar 將通過第二次遍歷元路徑來導入，調(diào)用 mpf.find_spec("foo.bar", foo.__path__, None)。 一旦 foo.bar 完成導入，最后一次遍歷將調(diào)用 mpf.find_spec("foo.bar.baz", foo.bar.__path__, None)。

有些元路徑查找器只支持頂級導入。 當把 None 以外的對象作為第三個參數(shù)傳入時，這些導入器將總是返回 None。

Python 的默認 sys.meta_path 具有三種元路徑查找器，一種知道如何導入內(nèi)置模塊，一種知道如何導入凍結模塊，還有一種知道如何導入來自 import path 的模塊 (即 path based finder)。

5.4.1. 加載器?

模塊加載器提供關鍵的加載功能：模塊執(zhí)行。 導入機制調(diào)用 importlib.abc.Loader.exec_module() 方法并傳入一個參數(shù)來執(zhí)行模塊對象。 從 exec_module() 返回的任何值都將被忽略。

加載器必須滿足下列要求:

• 如果模塊是一個 Python 模塊（而非內(nèi)置模塊或動態(tài)加載的擴展），加載器應該在模塊的全局命名空間 (module.__dict__) 中執(zhí)行模塊的代碼。

• 如果加載器無法執(zhí)行指定模塊，它應該引發(fā) ImportError，不過在 exec_module() 期間引發(fā)的任何其他異常也會被傳播。

在許多情況下，查找器和加載器可以是同一對象；在此情況下 find_spec() 方法將返回一個規(guī)格說明，其中加載器會被設為 self。

模塊加載器可以選擇通過實現(xiàn) create_module() 方法在加載期間創(chuàng)建模塊對象。 它接受一個參數(shù)，即模塊規(guī)格說明，并返回新的模塊對象供加載期間使用。 create_module() 不需要在模塊對象上設置任何屬性。 如果模塊返回 None，導入機制將自行創(chuàng)建新模塊。

5.4.2. 子模塊?

當使用任意機制 (例如 importlib API, import 及 import-from 語句或者內(nèi)置的 __import__()) 加載一個子模塊時，父模塊的命名空間中會添加一個對子模塊對象的綁定。 例如，如果包 spam 有一個子模塊 foo，則在導入 spam.foo 之后，spam 將具有一個 綁定到相應子模塊的 foo 屬性。 假如現(xiàn)在有如下的目錄結構:

spam/
    __init__.py
    foo.py

and spam/__init__.py has the following line in it:

from .foo import Foo

then executing the following puts name bindings for foo and Foo in the spam module:

>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.Foo
<class 'spam.foo.Foo'>

按照通常的 Python 名稱綁定規(guī)則，這看起來可能會令人驚訝，但它實際上是導入系統(tǒng)的一個基本特性。 保持不變的一點是如果你有 sys.modules['spam'] 和 sys.modules['spam.foo'] (例如在上述導入之后就是如此)，則后者必須顯示為前者的 foo 屬性。

5.4.3. 模塊規(guī)格說明?

導入機制在導入期間會使用有關每個模塊的多種信息，特別是加載之前。 大多數(shù)信息都是所有模塊通用的。 模塊規(guī)格說明的目的是基于每個模塊來封裝這些導入相關信息。

在導入期間使用規(guī)格說明可允許狀態(tài)在導入系統(tǒng)各組件之間傳遞，例如在創(chuàng)建模塊規(guī)格說明的查找器和執(zhí)行模塊的加載器之間。 最重要的一點是，它允許導入機制執(zhí)行加載的樣板操作，在沒有模塊規(guī)格說明的情況下這是加載器的責任。

模塊的規(guī)格說明會作為模塊對象的 __spec__ 屬性對外公開。 有關模塊規(guī)格的詳細內(nèi)容請參閱 ModuleSpec。

5.4.4. 導入相關的模塊屬性?

導入機制會在加載期間會根據(jù)模塊的規(guī)格說明填充每個模塊對象的這些屬性，并在加載器執(zhí)行模塊之前完成。

__name__?

__name__ 屬性必須被設為模塊的完整限定名稱。 此名稱被用來在導入系統(tǒng)中唯一地標識模塊。

__loader__?

__loader__ 屬性必須被設為導入系統(tǒng)在加載模塊時使用的加載器對象。 這主要是用于內(nèi)省，但也可用于額外的加載器專用功能，例如獲取關聯(lián)到加載器的數(shù)據(jù)。

__package__?

模塊的 __package__ 屬性必須設定。 其取值必須為一個字符串，但可以與 __name__ 取相同的值。 當模塊是包時，其 __package__ 值應該設為其 __name__ 值。 當模塊不是包時，對于最高層級模塊 __package__ 應該設為空字符串，對于子模塊則應該設為其父包名。 更多詳情可參閱 PEP 366。

該屬性取代 __name__ 被用來為主模塊計算顯式相對導入，相關定義見 PEP 366。 預期它與 __spec__.parent 具有相同的值。

在 3.6 版更改: __package__ 預期與 __spec__.parent 具有相同的值。

__spec__?

__spec__ 屬性必須設為在導入模塊時要使用的模塊規(guī)格說明。 對 __spec__ 的正確設定將同時作用于 解釋器啟動期間初始化的模塊。 唯一的例外是 __main__，其中的 __spec__ 會 在某些情況下設為 None.

當 __package__ 未定義時， __spec__.parent 會被用作回退項。

3.4 新版功能.

在 3.6 版更改: 當 __package__ 未定義時，__spec__.parent 會被用作回退項。

__path__?

如果模塊為包（不論是正規(guī)包還是命名空間包），則必須設置模塊對象的 __path__ 屬性。 屬性值必須為可迭代對象，但如果 __path__ 沒有進一步的用處則可以為空。 如果 __path__ 不為空，則在迭代時它應該產(chǎn)生字符串。 有關 __path__ 語義的更多細節(jié)將在 下文 中給出。

不是包的模塊不應該具有 __path__ 屬性。

__file__?

__cached__?

__file__ is optional (if set, value must be a string). It indicates the pathname of the file from which the module was loaded (if loaded from a file), or the pathname of the shared library file for extension modules loaded dynamically from a shared library. It might be missing for certain types of modules, such as C modules that are statically linked into the interpreter, and the import system may opt to leave it unset if it has no semantic meaning (e.g. a module loaded from a database).

If __file__ is set then the __cached__ attribute might also be set, which is the path to any compiled version of the code (e.g. byte-compiled file). The file does not need to exist to set this attribute; the path can simply point to where the compiled file would exist (see PEP 3147).

Note that __cached__ may be set even if __file__ is not set. However, that scenario is quite atypical. Ultimately, the loader is what makes use of the module spec provided by the finder (from which __file__ and __cached__ are derived). So if a loader can load from a cached module but otherwise does not load from a file, that atypical scenario may be appropriate.

5.4.5. module.__path__?

根據(jù)定義，如果一個模塊具有 __path__ 屬性，它就是包。

包的 __path__ 屬性會在導入其子包期間被使用。 在導入機制內(nèi)部，它的功能與 sys.path 基本相同，即在導入期間提供一個模塊搜索位置列表。 但是，__path__ 通常會比 sys.path 受到更多限制。

__path__ 必須是由字符串組成的可迭代對象，但它也可以為空。 作用于 sys.path 的規(guī)則同樣適用于包的 __path__，并且 sys.path_hooks (見下文) 會在遍歷包的 __path__ 時被查詢。

包的 __init__.py 文件可以設置或更改包的 __path__ 屬性，而且這是在 PEP 420 之前實現(xiàn)命名空間包的典型方式。 隨著 PEP 420 的引入，命名空間包不再需要提供僅包含 __path__ 操控代碼的 __init__.py 文件；導入機制會自動為命名空間包正確地設置 __path__。

5.4.6. 模塊的 repr?

默認情況下，全部模塊都具有一個可用的 repr，但是你可以依據(jù)上述的屬性設置，在模塊的規(guī)格說明中更為顯式地控制模塊對象的 repr。

如果模塊具有 spec (__spec__)，導入機制將嘗試用它來生成一個 repr。 如果生成失敗或找不到 spec，導入系統(tǒng)將使用模塊中的各種可用信息來制作一個默認 repr。 它將嘗試使用 module.__name__, module.__file__ 以及 module.__loader__ 作為 repr 的輸入，并將任何丟失的信息賦為默認值。

以下是所使用的確切規(guī)則:

• 如果模塊具有 __spec__ 屬性，其中的規(guī)格信息會被用來生成 repr。 被查詢的屬性有 "name", "loader", "origin" 和 "has_location" 等等。

• 如果模塊具有 __file__ 屬性，這會被用作模塊 repr 的一部分。

• 如果模塊沒有 __file__ 但是有 __loader__ 且取值不為 None，則加載器的 repr 會被用作模塊 repr 的一部分。

• 對于其他情況，僅在 repr 中使用模塊的 __name__。

5.4.7. 已緩存字節(jié)碼的失效?

在 Python 從 .pyc 文件加載已緩存字節(jié)碼之前，它會檢查緩存是否由最新的 .py 源文件所生成。 默認情況下，Python 通過在所寫入緩存文件中保存源文件的最新修改時間戳和大小來實現(xiàn)這一點。 在運行時，導入系統(tǒng)會通過比對緩存文件中保存的元數(shù)據(jù)和源文件的元數(shù)據(jù)確定該緩存的有效性。

Python 也支持“基于哈希的”緩存文件，即保存源文件內(nèi)容的哈希值而不是其元數(shù)據(jù)。 存在兩種基于哈希的 .pyc 文件：檢查型和非檢查型。 對于檢查型基于哈希的 .pyc 文件，Python 會通過求哈希源文件并將結果哈希值與緩存文件中的哈希值比對來確定緩存有效性。 如果檢查型基于哈希的緩存文件被確定為失效，Python 會重新生成并寫入一個新的檢查型基于哈希的緩存文件。 對于非檢查型 .pyc 文件，只要其存在 Python 就會直接認定緩存文件有效。 確定基于哈希的 .pyc 文件有效性的行為可通過 --check-hash-based-pycs 旗標來重載。

5.5.1. 路徑條目查找器?

path based finder 會負責查找和加載通過 path entry 字符串來指定位置的 Python 模塊和包。 多數(shù)路徑條目所指定的是文件系統(tǒng)中的位置，但它們并不必受限于此。

作為一種元路徑查找器，path based finder 實現(xiàn)了上文描述的 find_spec() 協(xié)議，但是它還對外公開了一些附加鉤子，可被用來定制模塊如何從 import path 查找和加載。

有三個變量由 path based finder, sys.path, sys.path_hooks 和 sys.path_importer_cache 所使用。 包對象的 __path__ 屬性也會被使用。 它們提供了可用于定制導入機制的額外方式。

sys.path 包含一個提供模塊和包搜索位置的字符串列表。 它初始化自 PYTHONPATH 環(huán)境變量以及多種其他特定安裝和實現(xiàn)的默認設置。 sys.path 條目可指定的名稱有文件系統(tǒng)中的目錄、zip 文件和其他可用于搜索模塊的潛在“位置”（參見 site 模塊），例如 URL 或數(shù)據(jù)庫查詢等。 在 sys.path 中只能出現(xiàn)字符串和字節(jié)串；所有其他數(shù)據(jù)類型都會被忽略。 字節(jié)串條目使用的編碼由單獨的 路徑條目查找器 來確定。

path based finder 是一種 meta path finder，因此導入機制會通過調(diào)用上文描述的基于路徑的查找器的 find_spec() 方法來啟動 import path 搜索。 當要向 find_spec() 傳入 path 參數(shù)時，它將是一個可遍歷的字符串列表 —— 通常為用來在其內(nèi)部進行導入的包的 __path__ 屬性。 如果 path 參數(shù)為 None，這表示最高層級的導入，將會使用 sys.path。

基于路徑的查找器會迭代搜索路徑中的每個條目，并且每次都查找與路徑條目對應的 path entry finder (PathEntryFinder)。 因為這種操作可能很耗費資源（例如搜索會有 stat() 調(diào)用的開銷），基于路徑的查找器會維持一個緩存來將路徑條目映射到路徑條目查找器。 這個緩存放于 sys.path_importer_cache (盡管如此命名，但這個緩存實際存放的是查找器對象而非僅限于 importer 對象)。 通過這種方式，對特定 path entry 位置的 path entry finder 的高耗費搜索只需進行一次。 用戶代碼可以自由地從 sys.path_importer_cache 移除緩存條目，以強制基于路徑的查找器再次執(zhí)行路徑條目搜索 3。

如果路徑條目不存在于緩存中，基于路徑的查找器會迭代 sys.path_hooks 中的每個可調(diào)用對象。 對此列表中的每個 路徑條目鉤子 的調(diào)用會帶有一個參數(shù)，即要搜索的路徑條目。 每個可調(diào)用對象或是返回可處理路徑條目的 path entry finder，或是引發(fā) ImportError。 基于路徑的查找器使用 ImportError 來表示鉤子無法找到與 path entry 相對應的 path entry finder。 該異常會被忽略并繼續(xù)進行 import path 的迭代。 每個鉤子應該期待接收一個字符串或字節(jié)串對象；字節(jié)串對象的編碼由鉤子決定（例如可以是文件系統(tǒng)使用的編碼 UTF-8 或其它編碼），如果鉤子無法解碼參數(shù)，它應該引發(fā) ImportError。

如果 sys.path_hooks 迭代結束時沒有返回 path entry finder，則基于路徑的查找器 find_spec() 方法將在 sys.path_importer_cache 中存入 None (表示此路徑條目沒有對應的查找器) 并返回 None，表示此 meta path finder 無法找到該模塊。

如果 sys.path_hooks 中的某個 path entry hook 可調(diào)用對象的返回值 是 一個 path entry finder，則以下協(xié)議會被用來向查找器請求一個模塊的規(guī)格說明，并在加載該模塊時被使用。

當前工作目錄 -- 由一個空字符串表示 -- 的處理方式與 sys.path 中的其他條目略有不同。 首先，如果發(fā)現(xiàn)當前工作目錄不存在，則 sys.path_importer_cache 中不會存放任何值。 其次，每個模塊查找會對當前工作目錄的值進行全新查找。 第三，由 sys.path_importer_cache 所使用并由 importlib.machinery.PathFinder.find_spec() 所返回的路徑將是實際的當前工作目錄而非空字符串。

5.5.2. 路徑條目查找器協(xié)議?

為了支持模塊和已初始化包的導入，也為了給命名空間包提供組成部分，路徑條目查找器必須實現(xiàn) find_spec() 方法。

find_spec() 接受兩個參數(shù)，即要導入模塊的完整限定名稱，以及（可選的）目標模塊。 find_spec() 返回模塊的完全填充好的規(guī)格說明。 這個規(guī)格說明總是包含“加載器”集合（但有一個例外）。

為了向導入機制提示該規(guī)格說明代表一個命名空間 portion，路徑條目查找器會將 "submodule_search_locations" 設為一個包含該部分的列表。

5.8.1. __main__.__spec__?

根據(jù) __main__ 被初始化的方式，__main__.__spec__ 會被設置相應值或是 None。

當 Python 附加 -m 選項啟動時，__spec__ 會被設為相應模塊或包的模塊規(guī)格說明。 __spec__ 也會在 __main__ 模塊作為執(zhí)行某個目錄，zip 文件或其它 sys.path 條目的一部分加載時被填充。

在 其余的情況 下 __main__.__spec__ 會被設為 None，因為用于填充 __main__ 的代碼不直接與可導入的模塊相對應:

• 交互型提示

• -c 選項

• 從 stdin 運行

• 直接從源碼或字節(jié)碼文件運行

請注意在最后一種情況中 __main__.__spec__ 總是為 None，即使 文件從技術上說可以作為一個模塊被導入。 如果想要讓 __main__ 中的元數(shù)據(jù)生效，請使用 -m 開關。

還要注意即使是在 __main__ 對應于一個可導入模塊且 __main__.__spec__ 被相應地設定時，它們?nèi)詴灰暈?不同的 模塊。 這是由于以下事實：使用 if __name__ == "__main__": 檢測來保護的代碼塊僅會在模塊被用來填充 __main__ 命名空間時而非普通的導入時被執(zhí)行。