引入模組

PyObject *PyImport_ImportModule(const char *name)

回傳值：新的參照。 為 穩定 ABI 的一部分.

這是 PyImport_Import() 的包裝器 (wrapper)，它使用 const char* 作為引數，而不是 PyObject*。

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)

回傳值：新的參照。

引入一個模組。這最好透過參考 Python 內建函式 __import__() 來說明。

回傳值是對引入的模組或頂層套件的新參照，或者是 NULL，失敗時會設定例外。就像 __import__() 一樣，當要求一個套件的子模組時，回傳值通常是頂層套件，除非給定一個非空的 fromlist。

失敗的引入會移除不完整的模組物件，就像 PyImport_ImportModule() 一樣。

PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

回傳值：新的參照。 為 穩定 ABI 的一部分 自 3.7 版本開始.

引入一個模組。這最好透過參考內建的 Python 函式 __import__() 來說明，因為標準的 __import__() 函式會直接呼叫這個函式。

回傳值是對引入的模組或頂層套件的新參照，或者是 NULL，失敗時會設定例外。就像 __import__() 一樣，當要求一個套件的子模組時，回傳值通常是頂層套件，除非給定一個非空的 fromlist。

在 3.3 版被加入.

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

回傳值：新的參照。 為 穩定 ABI 的一部分.

類似於 PyImport_ImportModuleLevelObject()，但名稱是 UTF-8 編碼字串，而不是 Unicode 物件。

在 3.3 版的變更: 不再接受負的 level 值。

PyObject *PyImport_Import(PyObject *name)

回傳值：新的參照。 為 穩定 ABI 的一部分.

這是一個較高階的介面，用來呼叫目前的「引入掛勾函式 (import hook function)」（明確的 level 為 0，表示絕對引入 (absolute import)）。它從目前全域變數的 __builtins__ 中呼叫 __import__() 函式。這表示引入是使用目前環境所安裝的引入掛勾來完成的。

此函式總是使用絕對引入。

PyObject *PyImport_ReloadModule(PyObject *m)

回傳值：新的參照。 為 穩定 ABI 的一部分.

重新載入一個模組。回傳重新載入模組的新參照，或在失敗時回傳 NULL 並設定例外（在這種情況下模組仍然存在）。

PyObject *PyImport_AddModuleRef(const char *name)

回傳值：新的參照。 為 穩定 ABI 的一部分 自 3.13 版本開始.

回傳與模組名稱對應的模組物件。

name 引數的形式可以是 package.module。首先檢查模組字典中是否有，如果沒有，則建立新的模組並插入模組字典中。

成功時回傳模組的強參照。失敗時回傳 NULL 並設定例外。

模組名稱 name 是以 UTF-8 解碼。

這個函式不會載入或引入模組；如果模組尚未載入，你將會得到一個空的模組物件。使用 PyImport_ImportModule() 或其變體來引入一個模組。如果尚未存在，則不會建立由 name 的點名稱 (dotted name) 所隱含的套件結構。

在 3.13 版被加入.

PyObject *PyImport_AddModuleObject(PyObject *name)

回傳值：借用參照。 為 穩定 ABI 的一部分 自 3.7 版本開始.

類似於 PyImport_AddModuleRef()，但是會回傳一個借用參照且 name 為 Python 的 str 物件。

在 3.3 版被加入.

PyObject *PyImport_AddModule(const char *name)

回傳值：借用參照。 為 穩定 ABI 的一部分.

類似於 PyImport_AddModuleRef()，但是會回傳一個借用參照。

PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)

回傳值：新的參照。 為 穩定 ABI 的一部分.

給定一個模組名稱（可能為 package.module 的形式），以及一個從 Python 位元組碼檔讀取或從內建函式 compile() 取得的程式碼物件，載入模組。回傳模組物件的新參照，如果發生錯誤，則回傳 NULL 並設定例外。在出錯的情況下，name 會從 sys.modules 中移除，即使 name 在進入 PyImport_ExecCodeModule() 時已經在 sys.modules 中。在 sys.modules 中留下未完全初始化的模組是很危險的，因為這種模組的引入無法知道模組物件處於未知狀態（且相對於模組作者的意圖，很可能已經損壞）。

如果尚未設定，模組的 __spec__ 和 __loader__ 將會被設定為適當的值。規格的載入器將被設定為模組的 __loader__（如果有設定），否則將被設定為 SourceFileLoader 的實例。

模組的 __file__ 屬性將會設定為程式碼物件的 co_filename。

如果模組已經被引入，這個函式會重新載入模組。請參閱 PyImport_ReloadModule() 以取得重新載入模組的預期方法。

如果 name 指向形式為 package.module 的點名稱，則任何尚未建立的套件結構仍不會被建立。

另請參閱 PyImport_ExecCodeModuleEx() 及 PyImport_ExecCodeModuleWithPathnames()。

在 3.12 版的變更: __cached__ 和 __loader__ 的設定已被棄用。請參閱 ModuleSpec 以取得替代方案。

在 3.15 版的變更: 不會再設定 __cached__ 屬性。

PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)

回傳值：新的參照。 為 穩定 ABI 的一部分.

類似於 PyImport_ExecCodeModule()，但是如果 pathname 不是 NULL，模組物件的 __file__ 屬性會被設定為 pathname。

另請參閱 PyImport_ExecCodeModuleWithPathnames()。

PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)

回傳值：新的參照。 為 穩定 ABI 的一部分 自 3.7 版本開始.

類似於 PyImport_ExecCodeModuleEx()，但是如果 cpathname 不是 NULL，會適當地使用透過 cpathname 給定的任何已編譯檔案路徑。在這三個函式中，這是首選的函式。

在 3.3 版被加入.

在 3.12 版的變更: 設定 __cached__ 已被棄用。請參閱 ModuleSpec 以取得替代方案。

在 3.15 版的變更: 不會再設定 __cached__ 屬性。

PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)

回傳值：新的參照。 為 穩定 ABI 的一部分.

類似於 PyImport_ExecCodeModuleObject()，但是 name、pathname 和 cpathname 是 UTF-8 編碼的字串。如果 pathname 被設定為 NULL，也會嘗試從 cpathname 中找出 pathname 的值應該是什麼。

在 3.2 版被加入.

在 3.3 版的變更: 如果只提供了位元組碼路徑，則在計算原始碼路徑時使用 imp.source_from_cache()。

在 3.12 版的變更: 不再使用已被移除的 imp 模組。

long PyImport_GetMagicNumber()

為 穩定 ABI 的一部分.

回傳 Python 位元組碼檔案（也稱為 .pyc 檔案）的魔術數字（magic number）。魔術數字應該出現在位元組碼檔案的前四個位元組，以小端序（little-endian）位元組順序排列。錯誤時會回傳 -1。

在 3.3 版的變更: 當失敗時回傳 -1。

const char *PyImport_GetMagicTag()

為 穩定 ABI 的一部分.

回傳 PEP 3147 格式 Python 位元組碼檔名的魔術標籤字串。請記住，sys.implementation.cache_tag 的值是權威的，應該使用它來取代這個函式。

在 3.2 版被加入.

PyObject *PyImport_GetModuleDict()

回傳值：借用參照。 為 穩定 ABI 的一部分.

回傳用於模組管理的字典（也稱為 sys.modules）。請注意，這是一個針對每個直譯器的變數 (per-interpreter variable)。

PyObject *PyImport_GetModule(PyObject *name)

回傳值：新的參照。 為 穩定 ABI 的一部分 自 3.8 版本開始.

回傳已以給定名稱引入的模組。如果模組尚未引入，則會回傳 NULL 但不會設定錯誤。如果查找失敗，則回傳 NULL 並設定錯誤。

在 3.7 版被加入.

PyObject *PyImport_GetImporter(PyObject *path)

回傳值：新的參照。 為 穩定 ABI 的一部分.

回傳 sys.path/pkg.__path__ 項 path 的查找器物件 (finder object)，可能的方式是從 sys.path_importer_cache 字典取得。如果它還沒有被快取，就遍歷 sys.path_hooks 直到找到可以處理路徑項的掛勾。如果沒有掛勾可以處理，則回傳 None；這會告訴我們的呼叫者 path based finder 找不到這個路徑項的查找器。將結果快取到 sys.path_importer_cache。回傳查找器物件的新參照。

int PyImport_ImportFrozenModuleObject(PyObject *name)

為 穩定 ABI 的一部分 自 3.7 版本開始.

載入一個名為 name 的凍結模組。成功則回傳 1，找不到模組則回傳 0，初始化失敗則回傳 -1 並設定例外。要在成功載入時存取引入的模組，請使用 PyImport_ImportModule()。（請注意這個名稱並不恰當 --- 如果模組已經被引入，這個函式會重新載入模組）。

在 3.3 版被加入.

在 3.4 版的變更: 不會再於模組設定 __file__ 屬性。

int PyImport_ImportFrozenModule(const char *name)

為 穩定 ABI 的一部分.

類似於 PyImport_ImportFrozenModuleObject()，但名稱是 UTF-8 編碼字串，而不是 Unicode 物件。

struct _frozen

這是由 freeze 工具程式產生的凍結模組描述器的結構型別定義（請參閱 Python 原始碼發行版中的 Tools/freeze/）。它的定義在 Include/import.h 中，為：

struct _frozen {
    const char *name;
    const unsigned char *code;
    int size;
    bool is_package;
};

在 3.11 版的變更: 新的 is_package 欄位指出模組是否為套件。這取代了將 size 欄位設定為負值的方式。

const struct _frozen *PyImport_FrozenModules

這個指標會被初始化為指向一個 _frozen 記錄的陣列，以一個其成員都是 NULL 或 0 的記錄為結尾。當一個凍結的模組被引入時，它會在這個表格中被搜尋。第三方程式碼可以利用這一點來提供一個動態建立的凍結模組集合。

int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))

為 穩定 ABI 的一部分.

新增單一模組到現有的內建模組表格。這是 PyImport_ExtendInittab() 的便利包裝器，如果表格無法擴充會回傳 -1。新的模組可以用 name 的名稱引入，並使用函式 initfunc 作為第一次嘗試引入時呼叫的初始化函式。這應該在 Py_Initialize() 之前呼叫。

struct _inittab

描述內建模組列表中單一項目的結構。嵌入 Python 的程式可以使用這些結構的陣列與 PyImport_ExtendInittab() 結合來提供額外的內建模組。這個結構包含兩個成員：

const char *name

模組名稱，為 ASCII 編碼的字串。

PyObject *(*initfunc)(void)

內建於直譯器中的模組的初始化函式。

Note that the inittab uses "PyInit" initialization functions; there is currently no way to include "PyModExport_" export hooks.

int PyImport_ExtendInittab(struct _inittab *newtab)

新增一個模組集合到內建模組表格。newtab 陣列必須以包含 NULL 的 name 欄位的哨兵項目（sentinel entry）結尾；如果沒有提供哨兵值，可能會導致記憶體錯誤。成功時會回傳 0，如果沒有足夠的記憶體可以分配來擴充內部表格則回傳 -1。在失敗的情況下，沒有模組會被加入內部表格。這個函式必須在 Py_Initialize() 之前呼叫。

如果 Python 被多次初始化，PyImport_AppendInittab() 或 PyImport_ExtendInittab() 必須在每次 Python 初始化之前被呼叫。

struct _inittab *PyImport_Inittab

Python 初始化所使用的內建模組表格。請勿直接使用它，請改用 PyImport_AppendInittab() 與 PyImport_ExtendInittab()。

PyObject *PyImport_ImportModuleAttr(PyObject *mod_name, PyObject *attr_name)

回傳值：新的參照。

引入模組 mod_name 並取得其屬性 attr_name。

名稱必須是 Python str 物件。

結合 PyImport_Import() 和 PyObject_GetAttr() 的輔助函式。例如，如果找不到模組，它會引發 ImportError，如果屬性不存在，則會引發 AttributeError。

在 3.14 版被加入.

PyObject *PyImport_ImportModuleAttrString(const char *mod_name, const char *attr_name)

回傳值：新的參照。

類似於 PyImport_ImportModuleAttr()，但名稱是 UTF-8 編碼字串，而不是 Python str 物件。

在 3.14 版被加入.

PyImport_LazyImportsMode PyImport_GetLazyImportsMode()

Gets the current lazy imports mode.

在 3.15 版被加入.

PyObject *PyImport_GetLazyImportsFilter()

回傳目前延遲引入過濾器的強參照，如果不存在則回傳 NULL。此函式總是會成功。

在 3.15 版被加入.

int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)

類似於 PyImport_ImportModuleAttr()，但名稱是 UTF-8 編碼字串，而不是 Python str 物件。

此函式總是回傳 0。

在 3.15 版被加入.

int PyImport_SetLazyImportsFilter(PyObject *filter)

Sets the current lazy imports filter. The filter should be a callable that will receive (importing_module_name, imported_module_name, [fromlist]) when an import can potentially be lazy. The imported_module_name value is the resolved module name, so lazy from .spam import eggs passes package.spam. The callable must return True if the import should be lazy and False otherwise.

成功時回傳 0，否則回傳 -1 並設定例外。

在 3.15 版被加入.

type PyImport_LazyImportsMode

Enumeration of possible lazy import modes.

enumerator PyImport_LAZY_NORMAL

Respect the lazy keyword in source code. This is the default mode.

enumerator PyImport_LAZY_ALL

Make all imports lazy by default.

在 3.15 版被加入.

PyObject *PyImport_CreateModuleFromInitfunc(PyObject *spec, PyObject *(*initfunc)(void))

This function is a building block that enables embedders to implement the create_module() step of custom static extension importers (e.g. of statically-linked extensions).

spec 必須是一個 ModuleSpec 物件。

initfunc must be an initialization function, the same as for PyImport_AppendInittab().

On success, create and return a module object. This module will not be initialized; call PyModule_Exec() to initialize it. (Custom importers should do this in their exec_module() method.)

If the spec's name is dotted and initfunc creates the module using only the last component of the name, the module's __name__ is set to the full name from the spec.

On error, return NULL with an exception set.

在 3.15 版被加入.