# 定义扩展模块

A C extension for CPython is a shared library (for example, a `.so` file on Linux, `.pyd` DLL on Windows), which is loadable into the Python process (for example, it is compiled with compatible compiler settings), and which exports an export hook function (or an old-style initialization function).

要在默认情况下可被导入 (也就是说，通过 `importlib.machinery.ExtensionFileLoader`)，共享库必须在 `sys.path` 中可用，并且必须命名为模块名之后加一个在 `importlib.machinery.EXTENSION_SUFFIXES` 中列出的扩展名。

备注

构建、打包和分发扩展模块最好使用第三方工具完成，并且超出了本文的范围。一个合适的工具是Setuptools，其文档可以在 https://setuptools.pypa.io/en/latest/setuptools.html 上找到。

## Extension export hook

Added in version 3.15: Support for the `PyModExport_<name>` export hook was added in Python 3.15. The older way of defining modules is still available: consult either the PyInit function section or earlier versions of this documentation if you plan to support earlier Python versions.

The export hook must be an exported function with the following signature:

PyModuleDef_Slot *PyModExport_modulename(void)

For modules with ASCII-only names, the export hook must be named `PyModExport_<name>`, with `<name>` replaced by the module's name.

For non-ASCII module names, the export hook must instead be named `PyModExportU_<name>` (note the `U`), with `<name>` encoded using Python's punycode encoding with hyphens replaced by underscores. In Python:

    def hook_name(name):
        try:
            suffix = b'_' + name.encode('ascii')
        except UnicodeEncodeError:
            suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
        return b'PyModExport' + suffix

The export hook returns an array of `PyModuleDef_Slot` entries, terminated by an entry with a slot ID of `0`. These slots describe how the module should be created and initialized.

This array must remain valid and constant until interpreter shutdown. Typically, it should use `static` storage. Prefer using the `Py_mod_create` and `Py_mod_exec` slots for any dynamic behavior.

The export hook may return `NULL` with an exception set to signal failure.

It is recommended to define the export hook function using a helper macro:

PyMODEXPORT_FUNC
  属于 稳定 ABI 自 3.15 版起.

  Declare an extension module export hook. This macro:

  - specifies the PyModuleDef_Slot* return type,

  - 添加平台所需的任何特殊链接声明，以及

  - 对于 C++，将函数声明为 `extern "C"`。

例如,一个名为 `spam` 模块可以这样定义:

    PyABIInfo_VAR(abi_info);

    static PyModuleDef_Slot spam_slots[] = {
        {Py_mod_abi, &abi_info},
        {Py_mod_name, "spam"},
        {Py_mod_init, spam_init_function},
        ...
        {0, NULL},
    };

    PyMODEXPORT_FUNC
    PyModExport_spam(void)
    {
        return spam_slots;
    }

The export hook is typically the only non-`static` item defined in the module's C source.

The hook should be kept short -- ideally, one line as above. If you do need to use Python C API in this function, it is recommended to call `PyABIInfo_Check(&abi_info, "modulename")` first to raise an exception, rather than crash, in common cases of ABI mismatch.

备注

It is possible to export multiple modules from a single shared library by defining multiple export hooks. However, importing them requires a custom importer or suitably named copies/links of the extension file, because Python's import machinery only finds the function corresponding to the filename. See the Multiple modules in one library section in PEP 489 for details.

## 多阶段初始化

The process of creating an extension module follows several phases:

- Python finds and calls the export hook to get information on how to create the module.

- Before any substantial code is executed, Python can determine which capabilities the module supports, and it can adjust the environment or refuse loading an incompatible extension. Slots like `Py_mod_abi`, `Py_mod_gil` and `Py_mod_multiple_interpreters` influence this step.

- By default, Python itself then creates the module object -- that is, it does the equivalent of calling `__new__()` when creating an object. This step can be overridden using the `Py_mod_create` slot.

- Python sets initial module attributes like `__package__` and `__loader__`, and inserts the module object into `sys.modules`.

- Afterwards, the module object is initialized in an extension-specific way -- the equivalent of `__init__()` when creating an object, or of executing top-level code in a Python-language module. The behavior is specified using the `Py_mod_exec` slot.

This is called multi-phase initialization to distinguish it from the legacy (but still supported) single-phase initialization, where an initialization function returns a fully constructed module.

在 3.5 版本发生变更: 增加了对多阶段初始化的支持 (PEP 489)。

## 多个模块实例

By default, extension modules are not singletons. For example, if the `sys.modules` entry is removed and the module is re-imported, a new module object is created and, typically, populated with fresh method and type objects. The old module is subject to normal garbage collection. This mirrors the behavior of pure-Python modules.

额外的模块实例可能会在 子解释器 中或者 Python 运行时重新初始化之后 (`Py_Finalize()` 和 `Py_Initialize()`) 被创建。 在这些情况下，模块实例间共享 Python 对象可能导致程序崩溃或未定义的行为。

为避免这种问题，每个扩展模块的实例都应当是 隔离的: 对一个实例的修改不应隐式地影响其他的实例，以及模块所拥有的全部状态，包括对 Python 对象的引用，都应当是特定模块实例专属的。 请参阅 隔离扩展模块 了解更多的细节和实用的指南。

一个避免这些问题的简单方式是 针对重复的初始化引发一个错误。

所有模块都应当支持 子解释器，否则就要显式地发出缺乏支持的信号 。 这往往是通过隔离或阻止重复的初始化，如上文所述。 一个模块也可以使用 `Py_mod_multiple_interpreters` 槽位将其限制于主解释器中。

## `PyInit` function

自 3.15 版本弃用: This functionality is soft deprecated. It will not get new features, but there are no plans to remove it.

Instead of `PyModExport_modulename()`, an extension module can define an older-style initialization function with the signature:

PyObject *PyInit_modulename(void)

Its name should be `PyInit_<name>`, with `<name>` replaced by the name of the module. For non-ASCII module names, use `PyInitU_<name>` instead, with `<name>` encoded in the same way as for the export hook (that is, using Punycode with underscores).

If a module exports both `PyInit_<name>` and `PyModExport_<name>`, the `PyInit_<name>` function is ignored.

Like with `PyMODEXPORT_FUNC`, it is recommended to define the initialization function using a helper macro:

PyMODINIT_FUNC

  声明一个扩展模块初始化函数。 这个宏：

  - 指定了 PyObject* 返回类型，

  - 添加平台所需的任何特殊链接声明，以及

  - 对于 C++，将函数声明为 `extern "C"`。

Normally, the initialization function (`PyInit_modulename`) returns a `PyModuleDef` instance with non-`NULL` `m_slots`. This allows Python to use multi-phase initialization.

Before it is returned, the `PyModuleDef` instance must be initialized using the following function:

PyObject *PyModuleDef_Init(PyModuleDef *def)
  属于 稳定 ABI 自 3.5 版起.

  确保模块定义是一个正确初始化的 Python 对象，并正确报告其类型以及引用计数。

  返回强制转换为 `PyObject*` 的 def，或者如果出现错误则返回 `NULL`。

  Calling this function is required before returning a `PyModuleDef` from a module initialization function. It should not be used in other contexts.

  请注意 Python 会假定 `PyModuleDef` 结构体是静态分配的。 此函数可以返回一个新引用或借入引用；这个引用不可被释放。

  Added in version 3.5.

例如,一个名为 `spam` 模块可以这样定义:

    static struct PyModuleDef spam_module = {
        .m_base = PyModuleDef_HEAD_INIT,
        .m_name = "spam",
        ...
    };

    PyMODINIT_FUNC
    PyInit_spam(void)
    {
        return PyModuleDef_Init(&spam_module);
    }

### 旧式的单阶段初始化

自 3.15 版本弃用: Single-phase initialization is soft deprecated. It is a legacy mechanism to initialize extension modules, with known drawbacks and design flaws. Extension module authors are encouraged to use multi-phase initialization instead.

However, there are no plans to remove support for it.

In single-phase initialization, the old-style initialization function (`PyInit_modulename`) should create, populate and return a module object. This is typically done using `PyModule_Create()` and functions like `PyModule_AddObjectRef()`.

单阶段初始化与 默认方式 的主要区别如下：

- 单阶段模块本质上是（更准确地说，包含）"单例对象"。

  当模块首次初始化时，Python会保存该模块 `__dict__` 中的内容（通常包括模块的函数和类型等）。

  对于后续导入操作，Python不会再次调用初始化函数，而是创建一个带有新 `__dict__` 的模块对象，并将已保存的内容复制到其中。例如，假设有一个单阶段模块 `_testsinglephase` [1] 定义了函数 `sum` 和异常类 `error`：

      >>> import sys
      >>> import _testsinglephase as one
      >>> del sys.modules['_testsinglephase']
      >>> import _testsinglephase as two
      >>> one is two
      False
      >>> one.__dict__ is two.__dict__
      False
      >>> one.sum is two.sum
      True
      >>> one.error is two.error
      True

  该具体行为应被视为CPython的实现细节。

- 为解决 `PyInit_modulename` 函数不接受 spec 参数的限制，导入机制会保存部分状态，并在 `PyInit_modulename` 调用期间将其应用于首个匹配的模块对象。具体表现为：当导入子模块时，该机制会将父包名称自动前置到模块名前。

  单阶段 `PyInit_modulename` 函数应当尽早创建"其所属"模块对象，该操作需在任何其他模块对象创建之前完成。

- 不支持非ASCII模块命名格式（如 `PyInitU_modulename`）。

- 单阶段模块支持模块查找函数如 `PyState_FindModule()`。

- The module's `PyModuleDef.m_slots` must be NULL.

[1]

`_testsinglephase` 是一个在 CPython 的自我测试套件中使用的内部模块；你的安装版可能包括它也可能不包括它。