Importing Modules

• PyObject * PyImport_ImportModule(const char ** name *)
  • 返回值：新参考.

这是下面PyImport_ImportModuleEx()的简化接口，将* globals 和 locals 参数设置为NULL并将 level 设置为 0.当 name *参数包含一个点时(当它指定包的子模块时)， * fromlist 参数设置为列表['*']，以便返回值是命名模块，而不是包含它的顶级包。 (不幸的是，当 name *实际上指定了子包而不是子模块时，这会产生额外的副作用：加载包__all__变量中指定的子模块.)返回对导入的模块或NULL的新引用，并带有异常集失败。导入模块失败不会将模块留在sys.modules中。

此函数始终使用绝对导入。

• PyObject * PyImport_ImportModuleNoBlock(const char ** name *)
  • 返回值：新参考.

此函数是PyImport_ImportModule()的不推荐使用的别名。

在版本 3.3 中更改：此Function曾经在另一个线程持有导入锁时立即失败。不过在 Python 3.3 中，出于大多数目的，锁定方案已切换为按模块锁定，因此不再需要此函数的特殊行为。

• PyObject * PyImport_ImportModuleEx(const char *name ，PyObject globals *，PyObject *locals ，PyObject fromlist *)
  • 返回值：新参考.

导入模块。最好pass参考内置的 Python 函数import()来描述。

返回值是对导入的模块或顶级包或NULL的新引用，但在失败时设置了 exception。就像import()一样，当请求包的子模块时，返回值通常是顶级包，除非给出了非空的* fromlist *。

导入失败会删除不完整的模块对象，例如PyImport_ImportModule()。

• PyObject * PyImport_ImportModuleLevelObject(PyObject *name ，PyObject globals *，PyObject *locals ，PyObject fromlist *，int * level *)
  • 返回值：新参考.

导入模块。最好pass参考内置的 Python 函数import()来描述，因为标准import()函数直接调用此函数。

返回值是对导入的模块或顶级包或NULL的新引用，但在失败时设置了 exception。就像import()一样，当请求包的子模块时，返回值通常是顶级包，除非给出了非空的* fromlist *。

版本 3.3 中的新Function。

• PyObject * PyImport_ImportModuleLevel(const char *name ，PyObject globals *，PyObject *locals ，PyObject fromlist *，int * level *)
  • 返回值：新参考.

与PyImport_ImportModuleLevelObject()相似，但名称是 UTF-8 编码的字符串，而不是 Unicode 对象。

在版本 3.3 中进行了更改：* level *的负值不再被接受。

• PyObject * PyImport_Import(PyObject *名称)
  • 返回值：新参考.

这是一个更高级别的接口，它调用当前的“导入钩子函数”(显式* level *为 0，表示绝对导入)。它从当前全局变量的__builtins__调用import()函数。这意味着可以使用当前环境中安装的任何导入钩子来完成导入。

此函数始终使用绝对导入。

• PyObject * PyImport_ReloadModule(PyObject ** m *)
  • 返回值：新参考.

重新加载模块。返回对重新加载的模块的新引用，或者返回NULL，并在失败时设置异常(在这种情况下该模块仍然存在)。

• PyObject * PyImport_AddModuleObject(PyObject *名称)
  • *返回值：借用参考。

返回与模块名称相对应的模块对象。 * name *参数的形式可以为package.module。首先检查模块词典中是否有模块词典，如果没有，则创建一个新的模块并将其插入模块词典中。返回NULL，并在失败时设置 exception。

版本 3.3 中的新Function。

• PyObject * PyImport_AddModule(const char ** name *)
  • *返回值：借用参考。

与PyImport_AddModuleObject()相似，但名称是 UTF-8 编码的字符串，而不是 Unicode 对象。

• PyObject * PyImport_ExecCodeModule(const char *name ，PyObject co *)
  • 返回值：新参考.

给定模块名称(可能是package.module的形式)和从 Python 字节码文件读取或从内置函数compile()获得的代码对象，加载模块。返回对模块对象的新引用，如果发生错误，则返回NULL，并设置一个异常。即使在 ImportingPyImport_ExecCodeModule()时* name 已经在sys.modules中，也会在错误情况下从sys.modules中删除 name *。将未完全初始化的模块留在sys.modules中是危险的，因为此类模块的导入无法知道模块对象是未知状态(并且就模块作者的意图而言可能已损坏)。

如果尚未设置模块的spec和loader，则将使用适当的值进行设置。规范的加载器将设置为模块的__loader__(如果已设置)，否则将设置为SourceFileLoader的实例。

模块的file属性将设置为代码对象的co_filename。如果适用，还将设置cached。

如果模块已经导入，则此Function将重新加载该模块。有关重新加载模块的预期方法，请参见PyImport_ReloadModule()。

如果* name *指向格式为package.module的点名，则仍不会创建任何尚未创建的包结构。

另请参见PyImport_ExecCodeModuleEx()和PyImport_ExecCodeModuleWithPathnames()。

• PyObject * PyImport_ExecCodeModuleEx(const char *name ，PyObject co *，const char ** pathname *)
  • 返回值：新参考.

类似于PyImport_ExecCodeModule()，但是如果模块对象的file属性不是NULL，则设置为* pathname *。

另请参见PyImport_ExecCodeModuleWithPathnames()。

• PyObject * PyImport_ExecCodeModuleObject(PyObject *name ，PyObject co *，PyObject *pathname ，PyObject cpathname *)
  • 返回值：新参考.

类似于PyImport_ExecCodeModuleEx()，但是如果模块对象的cached属性不是NULL，则设置为* cpathname *。在这三个Function中，这是首选使用的Function。

版本 3.3 中的新Function。

• PyObject * PyImport_ExecCodeModuleWithPathnames(const char *name ，PyObject co *，const char *pathname ，const char cpathname *)
  • 返回值：新参考.

类似于PyImport_ExecCodeModuleObject()，但是* name ， pathname 和 cpathname 是 UTF-8 编码的字符串。如果前者设置为NULL，还try从 cpathname 中找出 pathname *的值。

3.2 版中的新Function。

在版本 3.3 中进行了更改：如果仅提供字节码路径，则使用imp.source_from_cache()计算源路径。

• 长PyImport_GetMagicNumber()
  • 返回 Python 字节码文件(也称为.pyc文件)的幻数。幻数应该以小尾数字节 Sequences 出现在字节码文件的前四个字节中。错误返回-1。

在版本 3.3 中更改：失败时返回值-1。

• const char * PyImport_GetMagicTag()
  • 返回 PEP 3147格式的 Python 字节码文件名的魔术标记字符串。请记住，sys.implementation.cache_tag处的值是 Authority 性的，应代替此函数使用。

3.2 版中的新Function。

• PyObject* PyImport_GetModuleDict ( )
  • *返回值：借用参考。

返回用于模块 Management 的字典(也称为sys.modules)。请注意，这是每个解释器变量。

• PyObject * PyImport_GetModule(PyObject *名称)
  • 返回值：新参考.

返回具有给定名称的已导入模块。如果尚未导入模块，则返回NULL，但不设置错误。返回NULL并在查找失败的情况下设置错误。

3.7 版中的新Function。

• PyObject * PyImport_GetImporter(PyObject ** path *)
  • 返回值：新参考.

返回sys.path/pkg.__path__项* path *的查找器对象，可能是从sys.path_importer_cache字典中获取的。如果尚未缓存，请遍历sys.path_hooks直到找到可以处理路径项的钩子。如果没有钩子，则返回None；这告诉我们的调用者基于路径的查找器找不到此路径项的查找器。将结果缓存在sys.path_importer_cache中。返回对查找器对象的新引用。

• 无效_PyImport_Init()

  • 初始化导入机制。仅限内部使用。

• 无效PyImport_Cleanup()

  • 清空模块表。仅限内部使用。

• 无效_PyImport_Fini()

  • finally确定导入机制。仅限内部使用。

• int PyImport_ImportFrozenModuleObject(PyObject ** name *)

  • 返回值：新参考.

加载名为* name *的冻结模块。如果成功返回1，如果找不到该模块则返回0，如果初始化失败则返回-1并设置一个异常。要成功加载导入的模块，请使用PyImport_ImportModule()。 (请注意使用错误的名称-如果该函数已经导入，则它将重新加载该模块.)

版本 3.3 中的新Function。

在版本 3.4 中进行了更改：不再在模块上设置__file__属性。

• int PyImport_ImportFrozenModule(const char ** name *)

  • 与PyImport_ImportFrozenModuleObject()相似，但名称是 UTF-8 编码的字符串，而不是 Unicode 对象。

• 结构_frozen

  • 这是冻结模块 Descriptors 的结构类型定义，由 freeze Util 生成(请参见 Python 源代码发布中的Tools/freeze/)。在Include/import.h中找到的定义是：

struct _frozen {
    const char *name;
    const unsigned char *code;
    int size;
};

• const struct _frozen * PyImport_FrozenModules

  • 该指针被初始化为指向struct _frozen条记录的数组，并以成员均为NULL或零的成员终止。导入冻结的模块后，将在此表中对其进行搜索。第三方代码可以以此来提供动态创建的冻结模块集合。

• int PyImport_AppendInittab(const char **name ，PyObject ( initfunc *)(void))

  • 将单个模块添加到现有内置模块表中。这是围绕PyImport_ExtendInittab()的便捷包装，如果无法扩展表，则返回-1。可以使用名称* name 导入新模块，并使用函数 initfunc *作为首次try导入时调用的初始化函数。应该在Py_Initialize()之前调用。

• 结构_inittab

  • 描述内置模块列表中单个条目的结构。这些结构中的每一个都为解释器中内置的模块提供名称和初始化Function。名称是 ASCII 编码的字符串。嵌入 Python 的程序可以将这些结构的数组与PyImport_ExtendInittab()结合使用，以提供其他内置模块。该结构在Include/import.h中定义为：

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

• int PyImport_ExtendInittab(结构_inittab ** newtab *)
  • 将模块集合添加到内置模块表中。 * newtab *数组必须以一个前哨条目结尾，其中name字段包含NULL；无法提供前哨值可能会导致内存故障。成功时返回0，如果无法分配足够的内存来扩展内部表，则返回-1。发生故障时，不会将任何模块添加到内部表中。这应该在Py_Initialize()之前调用。