# 模块对象

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.