# 引入模組

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 版被加入.

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 版被加入.