匯入模組

PyObject *PyImport_ImportModule(const char *name)

返回值: 新引用。 穩定ABI 的一部分。

這是 PyImport_Import() 的一個包裝，它接受 const char* 作為引數，而不是 PyObject*。

PyObject *PyImport_ImportModuleNoBlock(const char *name)

返回值: 新引用。 穩定ABI 的一部分。

此函式是 PyImport_ImportModule() 的已棄用別名。

在 3.3 版本中變更: 此函式曾在使用匯入鎖被其他執行緒佔用時立即失敗。但在 Python 3.3 中，鎖定方案在大多數情況下切換到按模組鎖定，因此此函式的特殊行為不再需要。

自 3.13 版本棄用，並將在 3.15 版本中移除: 請改用 PyImport_ImportModule()。

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)

返回值: 新引用。 自 3.7 版本起成為 穩定ABI 的一部分。

匯入模組。最好透過引用內建的 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 的一部分。

這是一個更高級別的介面，它呼叫當前的“匯入鉤子函式”（顯式 level 為 0，表示絕對匯入）。它呼叫當前全域性變數的 __builtins__ 中的 __import__() 函式。這意味著匯入是使用當前環境中安裝的任何匯入鉤子完成的。

此函式始終使用絕對匯入。

PyObject *PyImport_ReloadModule(PyObject *m)

返回值: 新引用。 穩定ABI 的一部分。

重新載入模組。返回重新載入模組的新引用，如果失敗則為 NULL 並設定異常（模組在此情況下仍然存在）。

PyObject *PyImport_AddModuleRef(const char *name)

返回值: 新引用。 自 3.13 版本起成為 穩定ABI 的一部分。

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

name 引數可以是 package.module 形式。首先檢查模組字典中是否存在，如果不存在，則建立一個新模組並將其插入模組字典中。

成功時返回模組的 強引用。如果失敗則返回 NULL 並設定異常。

模組名稱 name 從 UTF-8 解碼。

此函式不載入或匯入模組；如果模組尚未載入，您將獲得一個空模組物件。使用 PyImport_ImportModule() 或其變體之一匯入模組。如果 name 的點分名稱暗示的包結構不存在，則不會建立它們。

在 3.13 版本加入。

PyObject *PyImport_AddModuleObject(PyObject *name)

返回值: 借用引用。 自 3.7 版本起成為 穩定ABI 的一部分。

類似於 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 在進入 PyImport_ExecCodeModule() 時已經存在於 sys.modules 中，也會從 sys.modules 中移除 name。將未完全初始化的模組留在 sys.modules 中是危險的，因為此類模組的匯入無法知道模組物件處於未知（並且相對於模組作者的意圖可能已損壞）狀態。

如果尚未設定，模組的 __spec__ 和 __loader__ 將使用適當的值設定。spec 的載入器將設定為模組的 __loader__（如果已設定），否則設定為 SourceFileLoader 的例項。

模組的 __file__ 屬性將設定為程式碼物件的 co_filename。如果適用，__cached__ 也會被設定。

如果模組已被匯入，此函式將重新載入模組。請參閱 PyImport_ReloadModule() 以瞭解重新載入模組的預期方式。

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

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

在 3.12 版本中變更: 設定 __cached__ 和 __loader__ 已棄用。請參閱 ModuleSpec 以瞭解替代方案。

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)

返回值: 新引用。 自 3.7 版本起成為 穩定ABI 的一部分。

類似於 PyImport_ExecCodeModuleEx()，但如果 cpathname 非 NULL，模組物件的 __cached__ 屬性將設定為 cpathname。在這三個函式中，這是首選函式。

在 3.3 版本加入。

在 3.12 版本中變更: 設定 __cached__ 已棄用。請參閱 ModuleSpec 以瞭解替代方案。

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 檔案）的魔數。魔數應以小端位元組順序存在於位元組碼檔案的前四個位元組中。出錯時返回 -1。

在 3.3 版本中變更: 失敗時返回 -1。

const char *PyImport_GetMagicTag()

作為 穩定 ABI 的一部分。

返回 PEP 3147 格式 Python 位元組碼檔名的魔術標籤字串。請記住，sys.implementation.cache_tag 中的值是權威的，應使用它而不是此函式。

在 3.2 版本加入。

PyObject *PyImport_GetModuleDict()

返回值: 借用引用。 穩定ABI 的一部分。

返回用於模組管理的字典（即 sys.modules）。請注意，這是一個每個直譯器變數。

PyObject *PyImport_GetModule(PyObject *name)

返回值: 新引用。 自 3.8 版本起成為 穩定ABI 的一部分。

返回具有給定名稱的已匯入模組。如果模組尚未匯入，則返回 NULL 但不設定錯誤。如果查詢失敗，則返回 NULL 並設定錯誤。

在 3.7 版本加入。

PyObject *PyImport_GetImporter(PyObject *path)

返回值: 新引用。 穩定ABI 的一部分。

返回 sys.path/pkg.__path__ 項 path 的查詢器物件，可能透過從 sys.path_importer_cache 字典中獲取它。如果尚未快取，則遍歷 sys.path_hooks，直到找到可以處理該路徑項的鉤子。如果沒有找到鉤子，則返回 None；這會告訴呼叫者 基於路徑的查詢器 無法為此路徑項找到查詢器。將結果快取在 sys.path_importer_cache 中。返回查詢器物件的新引用。

int PyImport_ImportFrozenModuleObject(PyObject *name)

自 3.7 版本起成為 穩定ABI 的一部分。

載入名為 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 或零的記錄終止。匯入凍結模組時，在此表中搜索。第三方程式碼可以利用這一點提供動態建立的凍結模組集合。

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)

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

int PyImport_ExtendInittab(struct _inittab *newtab)

向內建模組表新增一組模組。newtab 陣列必須以一個哨兵條目結束，該條目的 name 欄位為 NULL；未能提供哨兵值可能導致記憶體故障。成功時返回 0，如果無法分配足夠的記憶體來擴充套件內部表則返回 -1。如果失敗，則不會向內部表新增任何模組。這必須在 Py_Initialize() 之前呼叫。

如果 Python 多次初始化，則必須在每次 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 版本加入。