目标：易于使用的模块状态

目前，在保持模块隔离的同时，执行 C API 提供的一切是繁琐或不可能的。在PEP 384的推动下，PEP 489和PEP 573（以及未来计划的）中的更改旨在首先使其可能以这种方式构建模块，然后使其容易以这种方式编写新模块并转换旧模块，以便它可以成为自然的默认值。

即使每个模块状态成为默认值，也会存在不同封装级别的用例：每个进程、每个解释器、每个线程或每个任务状态。目标是将这些视为特殊情况：它们应该可能，但扩展作者需要更仔细地考虑它们。

非目标：加速和 GIL

目前正在努力通过使 GIL 成为每个解释器来加速多核 CPU 上的 CPython。虽然隔离解释器有助于这项工作，但即使没有实现加速，默认情况下使用每个模块状态也将是有益的，因为它使支持多个解释器在默认情况下更安全。

隔离的模块对象

开发扩展模块时要记住的关键点是，可以从单个共享库创建多个模块对象。例如

>>> import sys
>>> import binascii
>>> old_binascii = binascii
>>> del sys.modules['binascii']
>>> import binascii  # create a new module object
>>> old_binascii == binascii
False

根据经验法则，这两个模块应该完全独立。所有特定于模块的对象和状态都应该封装在模块对象中，不与其他模块对象共享，并在模块对象被解除分配时进行清理。例外是可能的（参见管理全局状态），但它们将比遵循此经验法则的代码需要更多的思考和对极端情况的关注。

虽然有些模块可以使用较不严格的限制，但隔离模块使得更容易设定适用于各种用例的明确期望（和指南）。

令人惊讶的极端情况

请注意，隔离模块确实会创建一些令人惊讶的极端情况。最值得注意的是，每个模块对象通常不会与其他类似模块共享其类和异常。继续上面的示例，请注意 old_binascii.Error 和 binascii.Error 是单独的对象。在以下代码中，异常未捕获

>>> old_binascii.Error == binascii.Error
False
>>> try:
...     old_binascii.unhexlify(b'qwertyuiop')
... except binascii.Error:
...     print('boo')
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
binascii.Error: Non-hexadecimal digit found

这是意料之中的。请注意，纯 Python 模块的行为方式相同：这是 Python 工作方式的一部分。

目标是使扩展模块在 C 级别安全，而不是使黑客行为直观。手动修改 sys.modules 算作黑客行为。

管理全局状态

有时，Python 模块的状态并非特定于该模块，而是特定于整个进程（或比模块“更全局”的其他内容）。例如

• readline 模块管理终端。
• 在电路板上运行的模块想要控制板载 LED。

在这些情况下，Python 模块应该提供对全局状态的访问，而不是拥有它。如果可能，编写模块时，使其多个副本可以独立访问状态（以及其他库，无论是用于 Python 还是其他语言）。

如果不可能，请考虑显式加锁。

如果需要使用进程全局状态，避免多解释器问题的最简单方法是明确阻止模块在每个进程中多次加载——请参见选择退出：限制每个进程只有一个模块对象。

管理每个模块状态

要使用每个模块状态，请使用PEP 489中引入的多阶段扩展模块初始化。这表示您的模块正确支持多个解释器。

将 PyModuleDef.m_size 设置为正数，以请求模块本地的字节存储量。通常，这将设置为某个模块特定 struct 的大小，该结构可以存储模块的所有 C 级状态。特别是，您应该将指向类（包括异常，但不包括静态类型）和设置（例如 csv 的field_size_limit）的指针放在那里，这些是 C 代码正常运行所需的。

如果模块状态包含 PyObject 指针，则模块对象必须持有对这些对象的引用，并实现模块级钩子 m_traverse、m_clear 和 m_free。它们的工作方式类似于类的 tp_traverse、tp_clear 和 tp_free。添加它们将需要一些工作并使代码更长；这是模块可以干净卸载的代价。

一个具有每个模块状态的模块示例目前作为xxlimited提供；文件底部显示了示例模块初始化。

选择退出：限制每个进程只有一个模块对象

非负的 PyModuleDef.m_size 表示模块正确支持多个解释器。如果您的模块尚未如此，您可以明确地让您的模块每个进程只能加载一次。例如

static int loaded = 0;

static int
exec_module(PyObject* module)
{
    if (loaded) {
        PyErr_SetString(PyExc_ImportError,
                        "cannot load module more than once per process");
        return -1;
    }
    loaded = 1;
    // ... rest of initialization
}

从函数访问模块状态

从模块级函数访问状态很简单。函数将模块对象作为它们的第一个参数；为了提取状态，您可以使用 PyModule_GetState

static PyObject *
func(PyObject *module, PyObject *args)
{
    my_struct *state = (my_struct*)PyModule_GetState(module);
    if (state == NULL) {
        return NULL;
    }
    // ... rest of logic
}

定义堆类型

堆类型可以通过填充 PyType_Spec 结构（类的描述或“蓝图”）并调用 PyType_FromModuleAndSpec() 来构造新的类对象。

该类通常应存储在模块状态（用于从 C 安全访问）和模块的 __dict__（用于从 Python 代码访问）中。

垃圾回收协议

堆类型的实例持有对其类型的引用。这确保了类型在所有实例销毁之前不会被销毁，但可能会导致需要由垃圾回收器打破的引用循环。

为了避免内存泄漏，堆类型的实例必须实现垃圾回收协议。也就是说，堆类型应该

• 具有 Py_TPFLAGS_HAVE_GC 标志。
• 使用 Py_tp_traverse 定义一个遍历函数，该函数访问类型（例如，使用 Py_VISIT(Py_TYPE(self));）。

请参阅文档中关于Py_TPFLAGS_HAVE_GC和tp_traverse <https://docs.pythonlang.cn/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse>的附加注意事项。

如果您的遍历函数委托给其基类（或另一个类型）的 tp_traverse，请确保 Py_TYPE(self) 只被访问一次。请注意，只有堆类型才期望在 tp_traverse 中访问该类型。

例如，如果您的遍历函数包含

base->tp_traverse(self, visit, arg)

……并且 base 可能是一个静态类型，那么它也应该包含

if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {
    // a heap type's tp_traverse already visited Py_TYPE(self)
} else {
    Py_VISIT(Py_TYPE(self));
}

在 tp_new 和 tp_clear 中无需处理类型的引用计数。

从类访问模块状态

如果您的类型对象是使用 PyType_FromModuleAndSpec() 定义的，您可以调用 PyType_GetModule 来获取关联的模块，然后调用 PyModule_GetState 来获取模块的状态。

为了省去一些繁琐的错误处理样板代码，您可以使用 PyType_GetModuleState 将这两个步骤结合起来，结果是

my_struct *state = (my_struct*)PyType_GetModuleState(type);
if (state === NULL) {
    return NULL;
}

从常规方法访问模块状态

从类的访问模块级状态稍微复杂一些，但这要归功于PEP 573中引入的更改。要获取状态，您需要首先获取定义类，然后从它获取模块状态。

最大的障碍是获取“方法被定义在哪个类中”，或者简称为该方法的“定义类”。定义类可以引用它所属的模块。

不要将定义类与 Py_TYPE(self) 混淆。如果方法在您的类型的子类上调用，Py_TYPE(self) 将引用该子类，该子类可能在与您的模块不同的模块中定义。

class Base:
    def get_defining_class(self):
        return __class__

class Sub(Base):
    pass

对于一个方法要获取其“定义类”，它必须使用 METH_METHOD | METH_FASTCALL | METH_KEYWORDS 调用约定和相应的 PyCMethod 签名

PyObject *PyCMethod(
    PyObject *self,               // object the method was called on
    PyTypeObject *defining_class, // defining class
    PyObject *const *args,        // C array of arguments
    Py_ssize_t nargs,             // length of "args"
    PyObject *kwnames)            // NULL, or dict of keyword arguments

一旦有了定义类，调用 PyType_GetModuleState 即可获取其关联模块的状态。

例如

static PyObject *
example_method(PyObject *self,
        PyTypeObject *defining_class,
        PyObject *const *args,
        Py_ssize_t nargs,
        PyObject *kwnames)
{
    my_struct *state = (my_struct*)PyType_GetModuleState(defining_class);
    if (state === NULL) {
        return NULL;
    }
    ... // rest of logic
}

PyDoc_STRVAR(example_method_doc, "...");

static PyMethodDef my_methods[] = {
    {"example_method",
      (PyCFunction)(void(*)(void))example_method,
      METH_METHOD|METH_FASTCALL|METH_KEYWORDS,
      example_method_doc}
    {NULL},
}

从槽方法、获取器和设置器访问模块状态

槽方法——特殊方法的快速 C 等效项，例如 __add__ 的 nb_add 或初始化 的 tp_new——有一个非常简单的 API，不允许传入定义类，这与 PyCMethod 不同。使用 PyGetSetDef 定义的获取器和设置器也是如此。

在这些情况下访问模块状态，请使用 PyType_GetModuleByDef 函数，并传入模块定义。一旦有了模块，调用 PyModule_GetState 获取状态

PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);
my_struct *state = (my_struct*)PyModule_GetState(module);
if (state === NULL) {
    return NULL;
}

PyType_GetModuleByDef 通过搜索MRO（即所有超类）来查找第一个具有相应模块的超类。

模块状态的生命周期

当模块对象被垃圾回收时，其模块状态被释放。对于指向模块状态（或其一部分）的每个指针，您必须持有对模块对象的引用。

通常这不成问题，因为使用 PyType_FromModuleAndSpec 创建的类型及其实例都持有对模块的引用。但是，当您从其他地方（例如外部库的回调）引用模块状态时，您必须小心引用计数。

类型检查

目前（截至 Python 3.10），堆类型没有好的 API 来编写 Py*_Check 函数（例如 str 的 PyUnicode_Check，一个静态类型），因此不容易确保实例具有特定的 C 布局。

元类

目前（截至 Python 3.10），没有好的 API 可以指定堆类型的元类；也就是说，类型对象的 ob_type 字段。

每个类范围

也无法将状态附加到类型。虽然 PyHeapTypeObject 是一个可变大小的对象 (PyVarObject)，但其可变大小的存储目前被槽占用。解决这个问题很复杂，因为继承层次结构中的几个类可能需要保留一些状态。

无损转换为堆类型

堆类型 API 并非设计用于从静态类型进行“无损”转换；也就是说，创建与给定静态类型完全相同的类型。解决此问题的最佳方法可能是编写一份涵盖已知“陷阱”的指南。