引入模組
********

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" 的實例。

   The module's "__file__" attribute will be set to the code object's
   "co_filename".

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

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

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

   在 3.12 版的變更: The setting of "__cached__" and "__loader__" is
   deprecated. See "ModuleSpec" for alternatives.

   在 3.15 版的變更: "__cached__" is no longer set.

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 版本開始.*

   Like "PyImport_ExecCodeModuleEx()", but the path to any compiled
   file via *cpathname* is used appropriately when non-"NULL".  Of the
   three functions, this is the preferred one to use.

   在 3.3 版被加入.

   在 3.12 版的變更: Setting "__cached__" is deprecated. See
   "ModuleSpec" for alternatives.

   在 3.15 版的變更: "__cached__" no longer set.

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)

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

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()

   Return a *strong reference* to the current lazy imports filter, or
   "NULL" if none exists. This function always succeeds.

   在 3.15 版被加入.

int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)

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

   This function always returns "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.

   Return "0" on success and "-1" with an exception set otherwise.

   在 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.

   enumerator PyImport_LAZY_NONE

      Disable lazy imports entirely. Even explicit "lazy" statements
      become eager imports.

   在 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* must be a "ModuleSpec" object.

   *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.)

   On error, return NULL with an exception set.

   在 3.15 版被加入.
