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

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__" 属性来重命名一个模块。

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()" 函数
   。


模块定义
========

使用 C API 创建的模块通常是用 "PySlot" 结构体的数组来定义的，它提供了
一个模块应当如何被创建的“描述”。 请参阅 定位槽位 获取有关槽位的更多通
用信息。

在 3.15 版本发生变更: Previously, a "PyModuleDef" struct was necessary
to define modules. The older way of defining modules is still
available: consult either the Module definition struct section or
earlier versions of this documentation if you plan to support earlier
Python versions.

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

Unless specified otherwise, the same slot ID may not be repeated in an
array of slots.


Metadata slots
--------------

Py_mod_name
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" for the name of the new module, as a NUL-terminated
   UTF8-encoded "const char *".

   Note that modules are typically created using a "ModuleSpec", and
   when they are, the name from the spec will be used instead of
   "Py_mod_name". However, it is still recommended to include this
   slot for introspection and debugging purposes.

   Added in version 3.15: Use "PyModuleDef.m_name" instead to support
   previous versions.

Py_mod_doc
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" for the docstring of the new module, as a NUL-terminated
   UTF8-encoded "const char *".

   Usually it is set to a variable created with "PyDoc_STRVAR".

   Added in version 3.15: Use "PyModuleDef.m_doc" instead to support
   previous versions.


Feature slots
-------------

Py_mod_abi
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" whose value points to a "PyABIInfo" structure describing
   the ABI that the extension is using.

   A suitable "PyABIInfo" variable can be defined using the
   "PyABIInfo_VAR" macro, as in:

      PyABIInfo_VAR(abi_info);

      static PySlot mymodule_slots[] = {
         PySlot_DATA(Py_mod_abi, &abi_info),
         ...
      };

   When creating a module, Python checks the value of this slot using
   "PyABIInfo_Check()".

   This slot is required, except for modules created from
   "PyModuleDef".

   Added in version 3.15.

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

   "Slot ID" whose value is one of:

   Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

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

   Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

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

   Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

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

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

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

   Added in version 3.12.

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

   "Slot ID" whose value is one of:

   Py_MOD_GIL_USED

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

   Py_MOD_GIL_NOT_USED

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

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

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

   Added in version 3.13.


Creation and initialization slots
---------------------------------

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

   "Slot ID" for a function that creates the module object itself. The
   function must have the signature:

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

   The function will be called with:

   * *spec*: a "ModuleSpec"-like object, meaning that any attributes
     defined for "importlib.machinery.ModuleSpec" have matching
     semantics. However, any of the attributes may be missing.

   * *def*: "NULL", or the module definition if the module is created
     from one.

   The function should return a new module object, or set an error and
   return "NULL".

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

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

   There is no requirement for the returned object to be an instance
   of "PyModule_Type". However, some slots may only be used with
   "PyModule_Type" instances; in particular:

   * "Py_mod_exec",

   * module state slots ("Py_mod_state_*"),

   * "Py_mod_token".

   Added in version 3.5.

   在 3.15 版本发生变更: The *slots* argument may be a
   "ModuleSpec"-like object, rather than a true "ModuleSpec" instance.
   Note that previous versions of CPython did not enforce this.The
   *def* argument may now be "NULL", since modules are not necessarily
   made from definitions.

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

   "Slot ID" for a function that will *execute*, or initialize, the
   module. This function does the equivalent to executing the code of
   a Python module: typically, it adds classes and constants to the
   module. The signature of the function is:

   int exec_module(PyObject *module)

   See the 支持函数 section for some useful functions to call.

   For backwards compatibility, the "PyModuleDef.m_slots" array may
   contain multiple "Py_mod_exec" slots; these are processed in the
   order they appear in the array. Elsewhere (that is, in arguments to
   "PyModule_FromSlotsAndSpec()" and in return values of
   "PyModExport_*<name>*"), repeating the slot is not allowed.

   Added in version 3.5.

   在 3.15 版本发生变更: Repeated "Py_mod_exec" slots are disallowed,
   except in "PyModuleDef.m_slots".

Py_mod_methods
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" for a table of module-level functions, as an array of
   "PyMethodDef" values suitable as the *functions* argument to
   "PyModule_AddFunctions()".

   Like other slot IDs, a slots array may only contain one
   "Py_mod_methods" entry. To add functions from multiple
   "PyMethodDef" arrays, call "PyModule_AddFunctions()" in the
   "Py_mod_exec" function.

   The table must be statically allocated (or otherwise guaranteed to
   outlive the module object).

   Added in version 3.15: Use "PyModuleDef.m_methods" instead to
   support previous versions.


Module state
============

Extension modules can have *module state* -- a piece of memory that is
allocated on module creation, and freed when the module object is
deallocated. The module state is specified using dedicated slots.

A typical use of module state is storing an exception type -- or
indeed *any* type object defined by the module --

Unlike the module's Python attributes, Python code cannot replace or
delete data stored in module state.

Keeping per-module information in attributes and module state, rather
than in static globals, makes module objects *isolated* and safer for
use in multiple sub-interpreters. It also helps Python do an orderly
clean-up when it shuts down.

Extensions that keep references to Python objects as part of module
state must implement "Py_mod_state_traverse" and "Py_mod_state_clear"
functions to avoid reference leaks.

To retrieve the state from a given module, use the following
functions:

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
   "Py_mod_state_size".

   On error, return "NULL" with an exception set. Use
   "PyErr_Occurred()" to tell this case apart from missing module
   state.

int PyModule_GetStateSize(PyObject *module, Py_ssize_t *result)
    * 属于 稳定 ABI 自 3.15 版起.*

   Set **result* to the size of *module*'s state, as specified using
   "Py_mod_state_size" (or "PyModuleDef.m_size"), and return 0.

   On error, set **result* to -1, and return -1 with an exception set.

   Added in version 3.15.


Slots for defining module state
-------------------------------

The following "slot IDs"  are available for defining the module state.

Py_mod_state_size
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" for the size of the module state, in bytes.

   Setting the value 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.

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

   Use "PyModule_GetStateSize()" to retrieve the size of a given
   module.

   Added in version 3.15: Use "PyModuleDef.m_size" instead to support
   previous versions.

Py_mod_state_traverse
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" for a traversal function to call during GC traversal of
   the module object.

   The signature of the function, and meanings of the arguments, is
   similar as for "PyTypeObject.tp_traverse":

   int traverse_module_state(PyObject *module, visitproc visit, void *arg)

   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 the state
   size ("Py_mod_state_size") is greater than 0 and the module state
   (as returned by "PyModule_GetState()") is "NULL".

   Added in version 3.15: Use "PyModuleDef.m_size" instead to support
   previous versions.

Py_mod_state_clear
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" for a clear function to call during GC clearing of the
   module object.

   The signature of the function is:

   int clear_module_state(PyObject *module)

   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 the state
   size ("Py_mod_state_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 the
   "Py_mod_state_free" function is called directly.

   Added in version 3.15: Use "PyModuleDef.m_clear" instead to support
   previous versions.

Py_mod_state_free
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" for a function to call during deallocation of the module
   object.

   The signature of the function is:

   int free_module_state(PyObject *module)

   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 the state
   size ("Py_mod_state_size") is greater than 0 and the module state
   (as returned by "PyModule_GetState()") is "NULL".

   Added in version 3.15: Use "PyModuleDef.m_free" instead to support
   previous versions.


Module token
------------

Each module may have an associated *token*: a pointer-sized value
intended to identify of the module state's memory layout. This means
that if you have a module object, but you are not sure if it “belongs”
to your extension, you can check using code like this:

   PyObject *module = <the module in question>

   void *module_token;
   if (PyModule_GetToken(module, &module_token) < 0) {
       return NULL;
   }
   if (module_token != your_token) {
       PyErr_SetString(PyExc_ValueError, "unexpected module")
       return NULL;
   }

   // This module's state has the expected memory layout; it's safe to cast
   struct my_state state = (struct my_state*)PyModule_GetState(module)

A module's token -- and the *your_token* value to use in the above
code -- is:

* For modules created with "PyModuleDef": the address of that
  "PyModuleDef";

* For modules defined with the "Py_mod_token" slot: the value of that
  slot;

* For modules created from an "PyModExport_*" export hook: the slots
  array that the export hook returned (unless overridden with
  "Py_mod_token").

Py_mod_token
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" for the module token.

   If you use this slot to set the module token (rather than rely on
   the default), you must ensure that:

   * 指针的寿命比类长，所以当类存在时，指针不能用于其他用途。

   * 它“属于”类所在的扩展模块，因此它不会与其他扩展冲突。

   * If the token points to a "PyModuleDef" struct, the module should
     behave as if it was created from that "PyModuleDef". In
     particular, the module state must have matching layout and
     semantics.

   Modules created from "PyModuleDef" always use the address of the
   "PyModuleDef" as the token. This means that "Py_mod_token" cannot
   be used in "PyModuleDef.m_slots".

   Added in version 3.15.

int PyModule_GetToken(PyObject *module, void **result)
    * 属于 稳定 ABI 自 3.15 版起.*

   Set **result* to the module token for *module* and return 0.

   On error, set **result* to NULL, and return -1 with an exception
   set.

   Added in version 3.15.

See also "PyType_GetModuleByToken()".


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

The following functions may be used to create an extension module
dynamically, rather than from an extension's export hook.

PyObject *PyModule_FromSlotsAndSpec(const PySlot *slots, PyObject *spec)
    *返回值：新的引用。** 属于 稳定 ABI 自 3.15 版起.*

   Create a new module object, given an array of slots and the
   "ModuleSpec" *spec*.

   The *slots* argument must point to an array of "PySlot" structures,
   terminated by an entry with slot ID of 0 (typically written as
   "PySlot_END"). The array must include a "Py_mod_abi" entry.

   The *spec* argument may be any "ModuleSpec"-like object, as
   described in "Py_mod_create" documentation. Currently, the *spec*
   must have a "name" attribute.

   On success, return the new module. On error, return "NULL" with an
   exception set.

   Note that this does not process the module's execution slot
   ("Py_mod_exec"). Both "PyModule_FromSlotsAndSpec()" and
   "PyModule_Exec()" must be called to fully initialize a module. (See
   also 多阶段初始化.)

   Added in version 3.15.

int PyModule_Exec(PyObject *module)
    * 属于 稳定 ABI 自 3.15 版起.*

   Execute the "Py_mod_exec" slot(s) of *module*.

   On success, return 0. On error, return -1 with an exception set.

   For clarity: If *module* has no slots, for example if it uses
   legacy single-phase initialization, this function does nothing and
   returns 0.

   Added in version 3.15.


Module definition struct
========================

Traditionally, extension modules were defined using a *module
definition* as the “description" of how a module should be created.
Rather than using an array of slots directly, the definition has
dedicated members for most common functionality, and allows additional
slots as an extension mechanism.

This way of defining modules is still available and there are no plans
to remove it.

type PyModuleDef
    * 属于 稳定 ABI (see below).*

   The module definition struct, which holds 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 defined this way.

   The struct, including all members, is part of the Stable ABI for
   non-free-threaded builds ("abi3"). In the Stable ABI for free-
   threaded builds ("abi3t"), this struct is opaque, and unusable in
   practice; see 模块定义 for a replacement.

   PyModuleDef_Base m_base

      Always initialize this member to "PyModuleDef_HEAD_INIT":

      type PyModuleDef_Base
          * 属于 稳定 ABI (see below).*

         The type of "PyModuleDef.m_base".

         The struct is part of the Stable ABI for non-free-threaded
         builds ("abi3"). In the Stable ABI for Free-Threaded Builds
         ("abi3t"), this struct is opaque, and unusable in practice.

      PyModuleDef_HEAD_INIT

         The required initial value for "PyModuleDef.m_base".

   const char *m_name

      Corresponds to the "Py_mod_name" slot.

   const char *m_doc

      These members correspond to the "Py_mod_doc" slot. Setting this
      to NULL is equivalent to omitting the slot.

   Py_ssize_t m_size

      Corresponds to the "Py_mod_state_size" slot. Setting this to
      zero is equivalent to omitting the slot.

      When using legacy single-phase initialization or when creating
      modules dynamically using "PyModule_Create()" or
      "PyModule_Create2()", "m_size" may be set to -1. This indicates
      that the module does not support sub-interpreters, because it
      has global state.

   PyMethodDef *m_methods

      Corresponds to the "Py_mod_methods" slot. Setting this to NULL
      is equivalent to omitting the slot.

   PyModuleDef_Slot *m_slots

      An array of additional slots, terminated by a "{0, NULL}" entry.
      Note that the entries use the older "PyModuleDef_Slot"
      structure, rather than "PySlot".

      If the array contains slots corresponding to "PyModuleDef"
      members, the values must match. For example, if you use
      "Py_mod_name" in "m_slots", "PyModuleDef.m_name" must be set to
      the same pointer (not just an equal string).

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

         inquiry m_reload

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

         Older structure defining additional slots of a module.

         Note that a "PyModuleDef_Slot" array may be included in a
         "PySlot" array using "Py_mod_slots", and vice versa using
         "Py_slot_subslots".

         Each "PyModuleDef_Slot" structure "modslot" is interpreted as
         the following "PySlot" structure:

            (PySlot){
               .sl_id=modslot.slot,
               .sl_flags=PySlot_INTPTR | sub_static,
               .sl_ptr=modslot.value
            }

         where "sub_static" is "PySlot_STATIC" if the slot requires
         the flag (such as for "Py_mod_methods"), or if this flag is
         present on the "parent" "Py_mod_slots" slot (if any).

         int slot

            Corresponds to "PySlot.sl_id".

         void *value

            Corresponds to "PySlot.sl_ptr".

         Added in version 3.5.

   traverseproc m_traverse
   inquiry m_clear
   freefunc m_free

      These members correspond to the "Py_mod_state_traverse",
      "Py_mod_state_clear", and "Py_mod_state_free" slots,
      respectively.

      Setting these members to NULL is equivalent to omitting the
      corresponding slots.

      在 3.9 版本发生变更: "m_traverse", "m_clear" and "m_free"
      functions are no longer called before the module state is
      allocated.

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

   "PyModuleDef" 对象的类型。

Py_mod_slots
    * 属于 稳定 ABI 自 3.15 版起.*

   "Slot ID" that works like "Py_slot_subslots", except it specifies
   an array of "PyModuleDef_Slot" structures.

   Added in version 3.15.

The following API can be used to create modules from a "PyModuleDef"
struct:

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.

   自 3.16.0a0 (unreleased) 版起已处于 Soft deprecated 状态: Prefer
   "PyModule_FromSlotsAndSpec()" in new code.

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.

   自 3.16.0a0 (unreleased) 版起已处于 Soft deprecated 状态: Prefer
   "PyModule_FromSlotsAndSpec()" in new code.

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

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

   Added in version 3.5.

   自 3.16.0a0 (unreleased) 版起已处于 Soft deprecated 状态: To run a
   module's own execution slots, prefer "PyModule_Exec()", which works
   on modules that were not created from a "PyModuleDef" structure.

PYTHON_API_VERSION
PYTHON_API_STRING

   The C API version, as an integer ("1013") and string (""1013""),
   respectively. Defined for backwards compatibility.

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

PYTHON_ABI_VERSION
PYTHON_ABI_STRING

   Defined as "3" and ""3"", respectively, for backwards
   compatibility.

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


支持函数
========

The following functions are provided to help initialize a module
object. They are intended for a module's execution slot
("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.
