模块对象
********

PyTypeObject PyModule_Type
    * 属于 稳定 ABI.*

   这个 "PyTypeObject" 的实例代表 Python 模块类型。它作为
   "types.ModuleType" 被暴露给 Python 程序。

int PyModule_Check(PyObject *p)

   当 *p* 为模块类型的对象，或是模块子类型的对象时返回真值。该函数永远
   有返回值。

int PyModule_CheckExact(PyObject *p)

   当 *p* 为模块类型的对象且不是 "PyModule_Type" 的子类型的对象时返回
   真值。该函数永远有返回值。

PyObject *PyModule_NewObject(PyObject *name)
    *返回值：新的引用。** 属于 稳定 ABI 自 3.7 版起.*

   返回一个新的模块对象，该对象的 "module.__name__" 将设为 *name*。模
   块的 "__name__", "__doc__", "__package__" 和 "__loader__" 属性将被
   填充 (除 "__name__" 外全都设为 "None")。 调用方要负责设置
   "__file__" 属性。

   当发生错误时将返回 "NULL" 并设置一个异常。

   Added in version 3.3.

   在 3.4 版本发生变更: 现在 "__package__" 和 "__loader__" 将被设为
   "None"。

PyObject *PyModule_New(const char *name)
    *返回值：新的引用。** 属于 稳定 ABI.*

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

PyObject *PyModule_GetDict(PyObject *module)
    *返回值：借入的引用。** 属于 稳定 ABI.*

   返回实现 *module* 的命名空间的字典对象；此对象与模块对象的
   "__dict__" 属性相同。如果 *module* 不是一个模块对象（或模块对象的子
   类型），则会引发 "SystemError" 并返回 "NULL"。

   建议扩展使用其他 "PyModule_*" 和 "PyObject_*" 函数而不是直接操纵模
   块的 "__dict__" 属性。

   返回的引用是从模块借入的；它将保持可用直到模块被销毁。

PyObject *PyModule_GetNameObject(PyObject *module)
    *返回值：新的引用。** 属于 稳定 ABI 自 3.7 版起.*

   返回 *module* 的 "__name__" 值。如果模块未提供该值，或者如果它不是
   一个字符串，则会引发 "SystemError" 并返回 "NULL"。

   Added in version 3.3.

const char *PyModule_GetName(PyObject *module)
    * 属于 稳定 ABI.*

   类似于 "PyModule_GetNameObject()" 但返回 "'utf-8'" 编码的名称。

   返回的缓冲区将保持可用直到模块被重命名或销毁。请注意 Python 代码可
   能会通过设置其 "__name__" 属性来重命名一个模块。

void *PyModule_GetState(PyObject *module)
    * 属于 稳定 ABI.*

   Return the "state" of the module, that is, a pointer to the block
   of memory allocated at module creation time, or "NULL".  See
   "PyModuleDef.m_size".

PyModuleDef *PyModule_GetDef(PyObject *module)
    * 属于 稳定 ABI.*

   返回指向模块创建所使用的 "PyModuleDef" 结构体的指针，或者如果模块不
   是使用结构体定义创建的则返回 "NULL"。

   出错时，返回 "NULL" 并设置一个异常。使用 "PyErr_Occurred()" 将这种
   情况与缺少 "PyModuleDef" 区分开来。

PyObject *PyModule_GetFilenameObject(PyObject *module)
    *返回值：新的引用。** 属于 稳定 ABI.*

   返回使用 *module* 的 "__file__" 属性所加载的 *module* 所对应的文件
   名。 如果未定义该属性，或者如果它不是一个字符串，则会引发
   "SystemError" 并返回 "NULL"；在其他情况下将返回一个指向 Unicode 对
   象的引用。

   Added in version 3.2.

const char *PyModule_GetFilename(PyObject *module)
    * 属于 稳定 ABI.*

   类似于 "PyModule_GetFilenameObject()" 但会返回编码为 'utf-8' 的文件
   名。

   返回的缓冲区将保持可用直到模块的 "__file__" 属性被重新赋值或模块被
   销毁。

   自 3.2 版本弃用: "PyModule_GetFilename()" 对于不可编码的文件名会引
   发 "UnicodeEncodeError"，请改用 "PyModule_GetFilenameObject()" 函数
   。


Module definitions
******************

The functions in the previous section work on any module object,
including modules imported from Python code.

Modules defined using the C API typically use a *module definition*,
"PyModuleDef" -- a statically allocated, constant “description" of how
a module should be created.

The definition is usually used to define an extension's “main” module
object (see 定义扩展模块 for details). It is also used to create
extension modules dynamically.

Unlike "PyModule_New()", the definition allows management of *module
state* -- a piece of memory that is allocated and cleared together
with the module object. Unlike the module's Python attributes, Python
code cannot replace or delete data stored in module state.

type PyModuleDef
    * 属于 稳定 ABI （包括所有成员）.*

   The module definition struct, which holds all information needed to
   create a module object. This structure must be statically allocated
   (or be otherwise guaranteed to be valid while any modules created
   from it exist). Usually, there is only one variable of this type
   for each extension module.

   PyModuleDef_Base m_base

      Always initialize this member to "PyModuleDef_HEAD_INIT".

   const char *m_name

      Name for the new module.

   const char *m_doc

      Docstring for the module; usually a docstring variable created
      with "PyDoc_STRVAR" is used.

   Py_ssize_t m_size

      Module state may be kept in a per-module memory area that can be
      retrieved with "PyModule_GetState()", rather than in static
      globals. This makes modules safe for use in multiple sub-
      interpreters.

      This memory area is allocated based on *m_size* on module
      creation, and freed when the module object is deallocated, after
      the "m_free" function has been called, if present.

      Setting it to a non-negative value means that the module can be
      re-initialized and specifies the additional amount of memory it
      requires for its state.

      Setting "m_size" to "-1" means that the module does not support
      sub-interpreters, because it has global state. Negative "m_size"
      is only allowed when using legacy single-phase initialization or
      when creating modules dynamically.

      请参阅 **PEP 3121** 了解详情。

   PyMethodDef *m_methods

      A pointer to a table of module-level functions, described by
      "PyMethodDef" values.  Can be "NULL" if no functions are
      present.

   PyModuleDef_Slot *m_slots

      An array of slot definitions for multi-phase initialization,
      terminated by a "{0, NULL}" entry. When using legacy single-
      phase initialization, *m_slots* must be "NULL".

      在 3.5 版本发生变更: 在 3.5 版之前，此成员总是被设为 "NULL"，并
      被定义为：

         inquiry m_reload

   traverseproc m_traverse

      A traversal function to call during GC traversal of the module
      object, or "NULL" if not needed.

      This function is not called if the module state was requested
      but is not allocated yet. This is the case immediately after the
      module is created and before the module is executed
      ("Py_mod_exec" function). More precisely, this function is not
      called if "m_size" is greater than 0 and the module state (as
      returned by "PyModule_GetState()") is "NULL".

      在 3.9 版本发生变更: No longer called before the module state is
      allocated.

   inquiry m_clear

      A clear function to call during GC clearing of the module
      object, or "NULL" if not needed.

      This function is not called if the module state was requested
      but is not allocated yet. This is the case immediately after the
      module is created and before the module is executed
      ("Py_mod_exec" function). More precisely, this function is not
      called if "m_size" is greater than 0 and the module state (as
      returned by "PyModule_GetState()") is "NULL".

      Like "PyTypeObject.tp_clear", this function is not *always*
      called before a module is deallocated. For example, when
      reference counting is enough to determine that an object is no
      longer used, the cyclic garbage collector is not involved and
      "m_free" is called directly.

      在 3.9 版本发生变更: No longer called before the module state is
      allocated.

   freefunc m_free

      A function to call during deallocation of the module object, or
      "NULL" if not needed.

      This function is not called if the module state was requested
      but is not allocated yet. This is the case immediately after the
      module is created and before the module is executed
      ("Py_mod_exec" function). More precisely, this function is not
      called if "m_size" is greater than 0 and the module state (as
      returned by "PyModule_GetState()") is "NULL".

      在 3.9 版本发生变更: No longer called before the module state is
      allocated.

PyTypeObject PyModuleDef_Type
    * 属于 稳定 ABI 自 3.5 版起.*

   "PyModuleDef" 对象的类型。


Module slots
============

type PyModuleDef_Slot
    * 属于 稳定 ABI （包括所有成员） 自 3.5 版起.*

   int slot

      A slot ID, chosen from the available values explained below.

   void *value

      Value of the slot, whose meaning depends on the slot ID.

   Added in version 3.5.

The available slot types are:

Py_mod_create
    * 属于 稳定 ABI 自 3.5 版起.*

   Specifies a function that is called to create the module object
   itself. The *value* pointer of this slot must point to a function
   of the signature:

   PyObject *create_module(PyObject *spec, PyModuleDef *def)

   The function receives a "ModuleSpec" instance, as defined in **PEP
   451**, and the module definition. It should return a new module
   object, or set an error and return "NULL".

   此函数应当保持最小化。特别地，它不应当调用任意 Python 代码，因为尝
   试再次导入同一个模块可能会导致无限循环。

   Multiple "Py_mod_create" slots may not be specified in one module
   definition.

   如果未指定 "Py_mod_create"，导入机制将使用 "PyModule_New()" 创建一
   个普通的模块对象。名称是获取自 *spec* 而非定义，以允许扩展模块动态
   地调整它们在模块层级结构中的位置并通过符号链接以不同的名称被导入，
   同时共享同一个模块定义。

   There is no requirement for the returned object to be an instance
   of "PyModule_Type". Any type can be used, as long as it supports
   setting and getting import-related attributes. However, only
   "PyModule_Type" instances may be returned if the "PyModuleDef" has
   non-"NULL" "m_traverse", "m_clear", "m_free"; non-zero "m_size"; or
   slots other than "Py_mod_create".

   Added in version 3.5.

Py_mod_exec
    * 属于 稳定 ABI 自 3.5 版起.*

   Specifies a function that is called to *execute* the module. This
   is equivalent to executing the code of a Python module: typically,
   this function adds classes and constants to the module. The
   signature of the function is:

   int exec_module(PyObject *module)

   If multiple "Py_mod_exec" slots are specified, they are processed
   in the order they appear in the *m_slots* array.

   Added in version 3.5.

Py_mod_multiple_interpreters
    * 属于 稳定 ABI 自 3.12 版起.*

   Specifies one of the following values:

   Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

      该模块不支持在子解释器中导入。

   Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

      该模块支持在子解释器中导入，但是它们必须要共享主解释器的 GIL。
      （参见 隔离扩展模块。）

   Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

      该模块支持在子解释器中导入，即使它们有自己的 GIL。 （参见 隔离扩
      展模块。）

   此槽位决定在子解释器中导入此模块是否会失败。

   Multiple "Py_mod_multiple_interpreters" slots may not be specified
   in one module definition.

   如果未指定 "Py_mod_multiple_interpreters"，则导入机制默认为
   "Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED" 值。

   Added in version 3.12.

Py_mod_gil
    * 属于 稳定 ABI 自 3.13 版起.*

   Specifies one of the following values:

   Py_MOD_GIL_USED

      这个模块依赖于全局解释器锁 (GIL) 的存在，并可在无需同步的情况下
      访问全局状态。

   Py_MOD_GIL_NOT_USED

      这个模块可以在不激活 GIL 的情况下安全运行。

   这个槽位会被未配置 "--disable-gil" 的 Python 构建版所忽略。在其他情
   况下，它将决定导入此模块是否会导致 GIL 被自动启用。请参阅 自由线程
   的 CPython 了解详情。

   Multiple "Py_mod_gil" slots may not be specified in one module
   definition.

   如果未指定 "Py_mod_gil"，则导入机制默认为 "Py_MOD_GIL_USED"。

   Added in version 3.13.


动态创建扩展模块
****************

The following functions may be used to create a module outside of an
extension's initialization function. They are also used in single-
phase initialization.

PyObject *PyModule_Create(PyModuleDef *def)
    *返回值：新的引用。*

   根据 *def* 中的定义创建一个新的模块对象。这是一个调用
   "PyModule_Create2()" 的宏，其中 *module_api_version* 设置为
   "PYTHON_API_VERSION"，或者如果使用 受限 API，则设置为
   "PYTHON_ABI_VERSION"。

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)
    *返回值：新的引用。** 属于 稳定 ABI.*

   创建一个新的模块对象，在参数 *def* 中给出定义，设定 API 版本为参数
   *module_api_version*。如果该版本与正在运行的解释器版本不匹配，则会
   触发 "RuntimeWarning"。

   当发生错误时将返回 "NULL" 并设置一个异常。

   此函数不支持槽位。 *def* 的 "m_slots" 成员必须为 "NULL"。

   备注:

     大多数时候应该使用 "PyModule_Create()" 代替使用此函数，除非你确定
     需要使用它。

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
    *返回值：新的引用。*

   这个宏调用 "PyModule_FromDefAndSpec2()"， *module_api_version* 设置
   为 "PYTHON_API_VERSION"，或者如果使用 受限 API，则设置为
   "PYTHON_ABI_VERSION" 常量。

   Added in version 3.5.

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
    *返回值：新的引用。** 属于 稳定 ABI 自 3.7 版起.*

   创建一个新的模块对象，在参数 *def* 和 *spec* 中给出定义，设置 API
   版本为参数 *module_api_version*。如果该版本与正在运行的解释器版本不
   匹配，则会触发 "RuntimeWarning"。

   当发生错误时将返回 "NULL" 并设置一个异常。

   注意，这不会处理执行槽位 ("Py_mod_exec")。 必须调用
   "PyModule_FromDefAndSpec" 和 "PyModule_ExecDef" 来完全初始化模块。

   备注:

     大多数时候应该使用 "PyModule_FromDefAndSpec()" 代替使用此函数，除
     非你确定需要使用它。

   Added in version 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
    * 属于 稳定 ABI 自 3.7 版起.*

   处理在 *def* 中给出的任何执行槽位 ("Py_mod_exec")。

   Added in version 3.5.

PYTHON_API_VERSION

   The C API version. Defined for backwards compatibility.

   目前，该常量在新的 Python 版本中没有更新，并且对于版本控制没有用处
   。这在未来可能会改变。

PYTHON_ABI_VERSION

   Defined as "3" for backwards compatibility.

   目前，该常量在新的 Python 版本中没有更新，并且对于版本控制没有用处
   。这在未来可能会改变。


支持函数
********

The following functions are provided to help initialize a module
state. They are intended for a module's execution slots
("Py_mod_exec"), the initialization function for legacy single-phase
initialization, or code that creates modules dynamically.

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)
    * 属于 稳定 ABI 自 3.10 版起.*

   将一个对象以 *name* 为名称添加到 *module* 中。这是一个便捷函数，可
   在模块的初始化函数中使用。

   如果成功，返回 "0"。如果发生错误，引发异常并返回 "-1"。

   用法示例：

      static int
      add_spam(PyObject *module, int value)
      {
          PyObject *obj = PyLong_FromLong(value);
          if (obj == NULL) {
              return -1;
          }
          int res = PyModule_AddObjectRef(module, "spam", obj);
          Py_DECREF(obj);
          return res;
       }

   为了方便，该函数接受 "NULL" *value* 并设置一个异常。在此情况下，将
   返回 "-1" 并让所引发的异常保持不变。

   这个例子也可以写成不显式地检查 *obj* 是否为 "NULL":

      static int
      add_spam(PyObject *module, int value)
      {
          PyObject *obj = PyLong_FromLong(value);
          int res = PyModule_AddObjectRef(module, "spam", obj);
          Py_XDECREF(obj);
          return res;
       }

   注意在此情况下应当使用 "Py_XDECREF()" 而不是 "Py_DECREF()"，因为
   *obj* 可能为 "NULL"。

   传给该函数的不同 *name* 字符串应当保持在较少的数量，通常是通过仅使
   用静态分配的字符串作为 *name* 来做到这一点。 对于编译时未知的名称，
   建议直接调用 "PyUnicode_FromString()" 和 "PyObject_SetAttr()"。更多
   相关细节，请参阅 "PyUnicode_InternFromString()"，它可在内部用于创建
   键对象。

   Added in version 3.10.

int PyModule_Add(PyObject *module, const char *name, PyObject *value)
    * 属于 稳定 ABI 自 3.13 版起.*

   类似于 "PyModule_AddObjectRef()"，但会“偷取”一个指向 *value* 的引用
   。 它在被调用时可附带一个返回新引用的函数的结果而无需检查其结果或是
   将其保存到一个变量。

   用法示例：

      if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
          goto error;
      }

   Added in version 3.13.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
    * 属于 稳定 ABI.*

   类似于 "PyModule_AddObjectRef()"，但会在成功时偷取一个对 *value* 的
   引用（如果它返回 "0" 值）。

   推荐使用新的 "PyModule_Add()" 或 "PyModule_AddObjectRef()" 函数，因
   为误用 "PyModule_AddObject()" 函数很容易导致引用泄漏。

   备注:

     与其他窃取引用的函数不同，"PyModule_AddObject()" 只在 **成功** 时
     释放对 *value* 的引用。这意味着必须检查它的返回值，调用方代码必须
     在发生错误时手动为 *value* 执行 "Py_XDECREF()"。

   用法示例：

      PyObject *obj = PyBytes_FromString(value);
      if (PyModule_AddObject(module, "spam", obj) < 0) {
          // 如果 'obj' 不为 NULL 且 PyModule_AddObject() 执行失败，
          // 则 'obj' 强引用必须使用 Py_XDECREF() 来删除。
          // 如果 'obj' 为 NULL，则 Py_XDECREF() 不做任何操作。
          Py_XDECREF(obj);
          goto error;
      }
      // PyModule_AddObject() 会偷取一个对 obj 的引用：
      // 这里不需要 Py_XDECREF(obj)。

   自 3.13 版起已处于 Soft deprecated 状态.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
    * 属于 稳定 ABI.*

   将一个整数常量作为 *name* 添加到 *module* 中。这个便捷函数可在模块
   的初始化函数中使用。当发生错误时将返回 "-1" 并设置一个异常，成功时
   则返回 "0"。

   这是一个调用 "PyLong_FromLong()" 和 "PyModule_AddObjectRef()" 的便
   捷函数；请参阅其文档了解详情。

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
    * 属于 稳定 ABI.*

   将一个字符串常量作为 *name* 添加到 *module* 中。这个便捷函数可在模
   块初始化函数中使用。字符串 *value* 必须以 "NULL" 结尾。当发生错误时
   将返回 "-1"，成功时则返回 "0"。

   这是一个调用 "PyUnicode_InternFromString()" 和
   "PyModule_AddObjectRef()" 的便捷函数；请参阅其文档了解详情。

PyModule_AddIntMacro(module, macro)

   将一个整数常量添加到 *module* 中。名称和值取自 *macro*。例如
   "PyModule_AddIntMacro(module, AF_INET)" 将值为 *AF_INET* 的整数常量
   *AF_INET* 添加到 *module* 中。当发生错误时将返回 "-1" 并设置一个异
   常，成功时将返回 "0"。

PyModule_AddStringMacro(module, macro)

   将一个字符串常量添加到*module*模块中。

int PyModule_AddType(PyObject *module, PyTypeObject *type)
    * 属于 稳定 ABI 自 3.10 版起.*

   将一个类型对象添加到 *module* 中。类型对象是通过在内部调用
   "PyType_Ready()" 来最终化的。类型对象的名称取自 "tp_name" 在点号之
   后的部分。当发生错误时将返回 "-1" 并设置一个异常，成功时将返回 "0"
   。

   Added in version 3.9.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
    * 属于 稳定 ABI 自 3.7 版起.*

   将以 "NULL" 结尾的 *functions* 数组中的函数添加到 *module* 中。有关
   单个条目的更多细节，请参阅 "PyMethodDef" 文档（由于缺少共享的模块命
   名空间，在 C 中实现的模块级"函数"通常将模块作为其第一个形参，与
   Python 类的实例方法类似）。

   此函数在从 "PyModuleDef" 创建模块时自动调用（例如使用 多阶段初始化
   、 "PyModule_Create" 或 "PyModule_FromDefAndSpec" 等）。一些模块作
   者可能更喜欢在多个 "PyMethodDef" 数组中定义函数；在这种情况下，他们
   应该直接调用这个函数。

   *functions* 数组必须被静态地分配（或者要保证比模块对象生存得更久）
   。

   Added in version 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)
    * 属于 稳定 ABI 自 3.7 版起.*

   将 *module* 的文档字符串设置为 *docstring*。此函数在使用
   "PyModuleDef" 创建模块时自动调用（例如使用 多阶段初始化、
   "PyModule_Create" 或 "PyModule_FromDefAndSpec" 时）。

   成功时返回 "0"。出错时返回 "-1" 并设置异常。

   Added in version 3.5.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)

   *这是 不稳定 API。它可能在次要版本中不经警告地被更改。*

   指明 *module* 是否支持不带全局解释器锁 (GIL) 运行，使用一个来自
   "Py_mod_gil" 的值。当使用 旧式的单阶段初始化 时它必须在 *module* 的
   初始化函数执行期间被调用。 如果此函数在模块初始化期间未被调用，导入
   机制将假定该模块不支持不带 GIL 运行。此函数仅在配置了 "--disable-
   gil" 的 Python 构建版中可用。当发生错误时将返回 "-1" 并设置一个异常
   ，成功时将返回 "0"。

   Added in version 3.13.


模块查找（单阶段初始化）
========================

遗留的 单阶段初始化 初始化方案创建可以在当前解释器上下文中被查找的单例
模块。这使得仅通过模块定义的引用，就可以检索模块对象。

这些函数不适用于通过多阶段初始化创建的模块，因为可以从一个模块定义创建
多个模块对象。

PyObject *PyState_FindModule(PyModuleDef *def)
    *返回值：借入的引用。** 属于 稳定 ABI.*

   返回当前解释器中由 *def* 创建的模块对象。此方法要求模块对象此前已通
   过 "PyState_AddModule()" 函数附加到解释器状态中。如果找不到相应的模
   块对象，或模块对象还未附加到解释器状态，返回 "NULL"。

int PyState_AddModule(PyObject *module, PyModuleDef *def)
    * 属于 稳定 ABI 自 3.3 版起.*

   将传给函数的模块对象附加到解释器状态。这将允许通过
   "PyState_FindModule()" 来访问该模块对象。

   仅在使用单阶段初始化创建的模块上有效。

   Python 会在使用 单阶段初始化 导入一个模块后自动调用
   "PyState_AddModule"，因此从模块初始化代码中调用它是没有必要的（但也
   没有害处）。显式的调用仅在模块自己的初始化代码后继调用了
   "PyState_FindModule" 的情况下才是必要的。 此函数主要是为了实现替代
   导入机制（或是通过直接调用它，或是通过引用它的实现来获取所需的状态
   更新详情）。

   如果先前使用相同的 *def* 附加了一个模块，则将其替换为新的 *module*
   。

   调用方必须有已附加的线程状态 *attached thread state*。

   出错时返回 "-1" 并设置一个异常，成功时返回 "0"。

   Added in version 3.3.

int PyState_RemoveModule(PyModuleDef *def)
    * 属于 稳定 ABI 自 3.3 版起.*

   从解释器状态中移除由 *def* 创建的模块对象。当发生错误时将返回 "-1"
   并设置一个异常，成功时将返回 "0"。

   调用方必须有已附加的线程状态 *attached thread state*。

   Added in version 3.3.
