匯入模組
********

PyObject *PyImport_ImportModule(const char *name)
    *Return value: New reference.** Part of the Stable ABI.*

   这是下面 "PyImport_ImportModuleEx()" 的简化版接口，将 *globals* 和
   *locals* 参数设为 "NULL" 并将 *level* 设为 0。 当 *name* 参数包含一
   个点号（即指定了一个包的子模块）时，*fromlist* 参数会被设为列表
   "['*']" 这样返回值将为所指定的模块而不像在其他情况下那样为包含模块
   的最高层级包。 （不幸的是，这在 *name* 实际上是指定一个子包而非子模
   块时将有一个额外的副作用：在包的 "__all__" 变量中指定的子模块会被加
   载。） 返回一个对所导入模块的新引用，或是在导入失败时返回 "NULL" 并
   设置一个异常。 模块导入失败同模块不会留 在 "sys.modules" 中。

   该函数总是使用绝对路径导入。

PyObject *PyImport_ImportModuleNoBlock(const char *name)
    *Return value: New reference.** Part of the Stable ABI.*

   该函数是 "PyImport_ImportModule()" 的一个被遗弃的别名。

   3.3 版更變: 在导入锁被另一线程掌控时此函数会立即失败。 但是从
   Python 3.3 起，锁方案在大多数情况下都已切换为针对每个模块加锁，所以
   此函数的特殊行为已无必要。

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
    *Return value: New reference.*

   导入一个模块。 请参阅内置 Python 函数 "__import__()" 获取完善的相关
   描述。

   返回值是一个对所导入模块或最高层级包的新引用，或是在导入失败时则为
   "NULL" 并设置一个异常。 与 "__import__()" 类似，当请求一个包的子模
   块时返回值通常为该最高层级包，除非给出了一个非空的 *fromlist*。

   导入失败将移动不完整的模块对象，就像 "PyImport_ImportModule()" 那样
   。

PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.7.*

   导入一个模块。 关于此函数的最佳说明请参考内置 Python 函数
   "__import__()"，因为标准 "__import__()" 函数会直接调用此函数。

   返回值是一个对所导入模块或最高层级包的新引用，或是在导入失败时则为
   "NULL" 并设置一个异常。 与 "__import__()" 类似，当请求一个包的子模
   块时返回值通常为该最高层级包，除非给出了一个非空的 *fromlist*。

   3.3 版新加入.

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Return value: New reference.** Part of the Stable ABI.*

   类似于 "PyImport_ImportModuleLevelObject()"，但其名称为 UTF-8 编码
   的字符串而不是 Unicode 对象。

   3.3 版更變: 不再接受 *level* 为负数值。

PyObject *PyImport_Import(PyObject *name)
    *Return value: New reference.** Part of the Stable ABI.*

   这是一个调用了当前“导入钩子函数”的更高层级接口（显式指定 *level* 为
   0，表示绝对导入）。 它将发起调用当前全局作用域下 "__builtins__" 中
   的 "__import__()" 函数。 这意味着将使用当前环境下安装的任何导入钩子
   来完成导入。

   该函数总是使用绝对路径导入。

PyObject *PyImport_ReloadModule(PyObject *m)
    *Return value: New reference.** Part of the Stable ABI.*

   重载一个模块。 返回一个指向被重载模块的新引用，或者在失败时返回
   "NULL" 并设置一个异常（在此情况下模块仍然会存在）。

PyObject *PyImport_AddModuleObject(PyObject *name)
    *Return value: Borrowed reference.** Part of the Stable ABI since
   version 3.7.*

   返回对应于某个模块名称的模块对象。 *name* 参数的形式可以为
   "package.module"。 如果存在 modules 字典则首先检查该字典，如果找不
   到，则创建一个新模块并将其插入到 modules 字典。 在失败时返回 "NULL"
   并设置一个异常。

   備註:

     此函数不会加载或导入指定模块；如果模块还未被加载，你将得到一个空
     的模块对象。 请使用 "PyImport_ImportModule()" 或它的某个变体形式
     来导入模块。 *name* 使用带点号名称的包结构如果尚不存在则不会被创
     建。

   3.3 版新加入.

PyObject *PyImport_AddModule(const char *name)
    *Return value: Borrowed reference.** Part of the Stable ABI.*

   类似于 "PyImport_AddModuleObject()"，但其名称为 UTF-8 编码的字符串
   而不是 Unicode 对象。object.

PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)
    *Return value: New reference.** Part of the Stable ABI.*

   给定一个模块名称（可能为 "package.module" 形式）和一个从 Pyhon 字节
   码文件读取或从内置函数 "compile()" 获取的代码对象，加载该模块。 返
   回对该模块对象的新引用，或者如果发生错误则返回 "NULL" 并设置一个异
   常。 在发生错误的情况下 *name* 会从 "sys.modules" 中被移除，即使
   *name* 在进入 "PyImport_ExecCodeModule()" 时已存在于 "sys.modules"
   中。 在 "sys.modules" 中保留未完全初始化的模块是危险的，因为导入这
   样的模块没有办法知道模块对象是否处于一种未知的（对于模块作业的意图
   来说可能是已损坏的）状态。

   模块的 "__spec__" 和 "__loader__" 如果尚未设置的话，将被设置为适当
   的值。 相应 spec 的加载器（如果已设置）将被设为模块的 "__loader__"
   而在其他情况下设为 "SourceFileLoader" 的实例。

   模块的 "__file__" 属性将被设为代码对象的 "co_filename"。 如果适用，
   "__cached__" 也将被设置。

   如果模块已被导入则此函数将重载它。 请参阅 "PyImport_ReloadModule()"
   了解重载模块的预定方式。

   如果 *name* 指向一个形式为 "package.module" 的带点号的名称，则任何
   尚未创建的包结构仍然不会被创建。

   另请参阅 "PyImport_ExecCodeModuleEx()" 和
   "PyImport_ExecCodeModuleWithPathnames()"。

PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
    *Return value: New reference.** Part of the Stable ABI.*

   类似于 "PyImport_ExecCodeModule()"，但如果 *pathname* 不为 "NULL"
   则会被设为模块对象的 "__file__" 属性的值。

   也請見 "PyImport_ExecCodeModuleWithPathnames()"。

PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.7.*

   类似于 "PyImport_ExecCodeModuleEx()"，但如果 *cpathname* 不为
   "NULL" 则会被设为模块对象的 "__cached__" 值。 在三个函数中，这是推
   荐使用的一个。

   3.3 版新加入.

PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
    *Return value: New reference.** Part of the Stable ABI.*

   类似于 "PyImport_ExecCodeModuleObject()"，但 *name*, *pathname* 和
   *cpathname* 为 UTF-8 编码的字符串。如果 *pathname* 也被设为 "NULL"
   则还会尝试根据 *cpathname* 推断出前者的值。

   3.2 版新加入.

   3.3 版更變: 如果只提供了字节码路径则会使用
   "imp.source_from_cache()" 来计算源路径。

long PyImport_GetMagicNumber()
    * Part of the Stable ABI.*

   返回 Python 字节码文件（即 ".pyc" 文件）的魔数。 此魔数应当存在于字
   节码文件的开头四个字节中，按照小端字节序。 出错时返回 "-1"。

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

const char *PyImport_GetMagicTag()
    * Part of the Stable ABI.*

   针对 **PEP 3147** 格式的 Python 字节码文件名返回魔术标签字符串。 请
   记住在 "sys.implementation.cache_tag" 上的值是应当被用来代替此函数
   的更权威的值。

   3.2 版新加入.

PyObject *PyImport_GetModuleDict()
    *Return value: Borrowed reference.** Part of the Stable ABI.*

   返回用于模块管理的字典 (即 "sys.modules")。 请注意这是针对每个解释
   器的变量。

PyObject *PyImport_GetModule(PyObject *name)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.8.*

   返回给定名称的已导入模块。 如果模块尚未导入则返回 "NULL" 但不会设置
   错误。 如果查找失败则返回 "NULL" 并设置错误。

   3.7 版新加入.

PyObject *PyImport_GetImporter(PyObject *path)
    *Return value: New reference.** Part of the Stable ABI.*

   返回针对一个 "sys.path"/"pkg.__path__" 中条目 *path* 的查找器对象，
   可能会通过 "sys.path_importer_cache" 字典来获取。 如果它尚未被缓存
   ，则会遍历 "sys.path_hooks" 直至找到一个能处理该 path 条目的钩子。
   如果没有可用的钩子则返回 "None"；这将告知调用方 *path based finder*
   无法为该 path 条目找到查找器。 结果将缓存到
   "sys.path_importer_cache"。 返回一个指向查找器对象的新引用。

int PyImport_ImportFrozenModuleObject(PyObject *name)
    * Part of the Stable ABI since version 3.7.*

   加载名称为 *name* 的已冻结模块。 成功时返回 "1"，如果未找到模块则返
   回 "0"，如果初始化失败则返回 "-1" 并设置一个异常。 要在加载成功后访
   问被导入的模块，请使用 "PyImport_ImportModule()"。 （请注意此名称有
   误导性 --- 如果模块已被导入此函数将重载它。）

   3.3 版新加入.

   3.4 版更變: "__file__" 属性将不再在模块上设置。

int PyImport_ImportFrozenModule(const char *name)
    * Part of the Stable 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;
      };

const struct _frozen *PyImport_FrozenModules

   This pointer is initialized to point to an array of "_frozen"
   records, terminated by one whose members are all "NULL" or zero.
   When a frozen module is imported, it is searched in this table.
   Third-party code could play tricks with this to provide a
   dynamically created collection of frozen modules.

int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))
    * Part of the Stable ABI.*

   向现有的内置模块表添加一个模块。 这是对 "PyImport_ExtendInittab()"
   的便捷包装，如果无法扩展表则返回 "-1"。 新的模块可使用名称 *name*
   来导入，并使用函数 *initfunc* 作为在第一次尝试导入时调用的初始化函
   数。 此函数应当在 "Py_Initialize()" 之前调用。

struct _inittab

   描述内置模块列表中的一个条目的结构体。 每个结构体都给出了内置在解释
   器中的某个模块的名称和初始化函数。 名称是一个 ASCII 编码的字符串。
   嵌入了 Python 的程序可以使用该结构体的数组来与
   "PyImport_ExtendInittab()" 相结合以提供额外的内置模块。 该结构体在
   "Include/import.h" 中被定义为:

      struct _inittab {
          const char *name;           /* ASCII encoded string */
          PyObject* (*initfunc)(void);
      };

int PyImport_ExtendInittab(struct _inittab *newtab)

   将内置模块表添加一组模块。 *newtab* 数组必须以一个包含以 "NULL" 作
   为 "name" 字段的岗哨条目结束；未能提供岗哨值会导致内存错误。 成功时
   返回 "0" 或者如果无法分配足够内存来扩展内部表则返回 "-1"。 当发生失
   败时，将不会添加模块到内部表。 此函数必须在 "Py_Initialize()" 之前
   调用。

   如果 Python 要被多次初始化，则 "PyImport_AppendInittab()" 或
   "PyImport_ExtendInittab()" 必须在每次 Python 初始化之前调用。
