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

PyObject *PyImport_ImportModule(const char *name)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

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

PyObject *PyImport_ImportModuleNoBlock(const char *name)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   這個函式是 "PyImport_ImportModule()" 的已棄用別名。

   在 3.3 版的變更: 當引入鎖被其他執行緒持有時，這個函式過去會立即失敗
   。但在 Python 3.3 中，鎖機制轉換成針對每個模組的鎖 (per-module
   lock) 來達到大多數目的，所以這個函式的特殊行為就不再需要了。

   自從版本 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)
    *回傳值：新的參照。** 為 穩定 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"。如果適
   用，"__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)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分 自 3.7 版本開始.*

   類似於 "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" 檔案）的魔術數字（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 版被加入.
