Python 扩展模块隔离指南：从原理到实践

Python 扩展模块隔离指南：从原理到实践

在 Python 开发中，扩展模块的状态管理至关重要。本文聚焦于 Python 扩展模块的隔离技术，深入探讨进程级状态存在的问题，详细介绍模块级状态的优势与实现方法，包括如何管理全局和模块级状态、在函数和类中访问模块状态，以及堆类型相关的知识。通过丰富的示例和清晰的讲解，助力 C-API 扩展维护者编写更安全、可靠的扩展模块，使其在多解释器环境下稳定运行。同时，引入实际项目示例，让读者更直观地理解和应用相关技术。

一、背景

Python 支持在一个进程中运行多个解释器，主要有串行（使用Py_InitializeEx()/Py_FinalizeEx()循环）和并行（使用Py_NewInterpreter()/Py_EndInterpreter()管理子解释器）两种情况。这两种方式常用于将 Python 嵌入到库中。然而，许多 Python 扩展模块（甚至部分标准库模块）过去常使用进程内共享的全局状态（通过 C static变量实现），这就导致本该属于某个解释器的数据被多个解释器共享，容易在多解释器导入同一模块时引发崩溃等边界问题 。

二、进入模块级状态

Python 的 C API 逐渐更好地支持模块级状态，即 C 层级数据关联到模块对象，每个解释器创建自己的模块对象，实现数据分隔。这种方式为处理生命周期和资源归属提供了便利，扩展模块在模块对象创建时初始化，释放时清理。与进程级、解释器级、线程级状态相比，模块级状态是默认选择，其他状态属于特殊情况，使用时需额外关注和测试。

三、隔离的模块对象

在开发扩展模块时，要注意多个模块对象可从单个共享库创建。例如，通过重新导入模块可以创建新的模块对象，且新老模块对象相互独立。这意味着模块专属的对象和状态应封装在模块内部，不与其他模块对象共享，并在模块对象释放时清理。不过，隔离的模块也会产生一些特殊情况，比如不同模块对象的类和异常是独立的，在异常捕获等场景下要特别注意 。

操作	示例	结果	说明
创建新老模块对象对比	import sys; import binascii; old_binascii=binascii; del sys.modules['binascii']; import binascii; old_binascii==binascii	False	新老模块对象不同
不同模块对象异常捕获	try: old_binascii.unhexlify(b'qwertyuiop'); except binascii.Error: print('boo')	异常未被捕获	不同模块对象的异常类是独立的

四、让多解释器下模块保持安全

（一）管理全局状态

有些与 Python 模块相关的状态并非模块专属，而是整个进程或更全局范围共享，如readline模块管理终端、控制板载 LED 的模块等。在这种情况下，模块应提供对全局状态的访问而非拥有它。若无法让多个模块副本独立访问全局状态，可考虑显式加锁。若必须使用进程级全局状态，为避免多解释器问题，可显式阻止模块在一个进程中多次加载。

（二）管理模块级状态

使用多阶段扩展模块初始化来管理模块级状态，表明模块能正确支持多解释器。通过设置PyModuleDef.m_size为正数，为模块请求本地存储，通常设置为存放模块 C 层级状态的struct大小。此外，也可选择将状态保存在模块的__dict__中，但要注意避免用户从 Python 代码修改__dict__导致程序崩溃，若 C 代码不需要模块状态，保存在__dict__中是个不错的选择。如果模块状态包含PyObject指针，模块对象必须持有对这些对象的引用，并实现m_traverse、m_clear和m_free等模块层级的钩子函数 。

（三）回退选项：每个进程限一个模块对象

如果模块还不支持多解释器，可通过设置让模块在每个进程中只能加载一次。例如，使用一个静态变量记录模块是否已加载，在模块加载时进行检查，若已加载则抛出异常阻止再次加载。

五、函数对模块状态的访问

从模块层级的函数访问状态相对直观，函数通过第一个参数获得模块对象，使用PyModule_GetState()提取状态。需要注意的是，若PyModuleDef.m_size为零，PyModule_GetState()可能返回NULL且不设置异常，在模块开发中应避免这种情况 。

六、堆类型

（一）堆类型概述

传统 C 代码中定义的静态类型在进程范围内共享，存在一些局限性，如无法访问模块状态、跨解释器共享时依赖 CPython 的 GIL 等。堆类型则更接近 Python 中class语句创建的类，对于新模块，默认使用堆类型是较好的选择。

（二）将静态类型改为堆类型

静态类型可转换为堆类型，但要注意堆类型 API 并非为实现静态类型的 “无损” 转换而设计，转换过程中可能改变一些细节，如可封存性、继承的槽位等，因此转换后务必测试关键细节。同时要注意堆类型对象默认可变，可使用Py_TPFLAGS_IMMUTABLETYPE旗标防止；堆类型默认可通过 Python 代码初始化，可使用Py_TPFLAGS_DISALLOW_INSTANTIATION旗标防止 。

（三）定义堆类型

通过填充PyType_Spec结构体并调用PyType_FromModuleAndSpec()可创建堆类型，该函数会将模块关联到类，方便从方法访问模块状态。类通常应同时保存在模块状态（便于 C 中安全访问）和模块的__dict__中（便于 Python 代码访问）。

（四）垃圾回收协议

堆类型的实例持有指向其类型的引用，可能导致引用循环，因此需实现垃圾回收协议：设置Py_TPFLAGS_HAVE_GC旗标，并定义使用Py_tp_traverse的遍历函数访问该类型。在 Python 3.8 及更低版本中，遍历函数访问类型的要求有所不同，需特殊处理；委托tp_traverse时要确保Py_TYPE(self)只被访问一次；定义tp_dealloc函数时要正确处理引用计数；堆类型的tp_free槽位必须设为PyObject_GC_Del()且不要重载；避免使用PyObject_New()，优先使用带 GC 感知的函数分配对象 。

操作	要求	示例代码
设置旗标	具有Py_TPFLAGS_HAVE_GC旗标	`my_type.tp_flags	= Py_TPFLAGS_HAVE_GC;`
定义遍历函数	使用Py_tp_traverse访问类型	static int my_traverse(PyObject *self, visitproc visit, void *arg) { Py_VISIT(Py_TYPE(self)); return 0; }
处理 Python 3.8 及更低版本	特殊处理版本兼容性	#if PY_VERSION_HEX < 0x03090000 // 处理低版本逻辑 #else Py_VISIT(Py_TYPE(self)); #endif
委托tp_traverse	确保Py_TYPE(self)只被访问一次	if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) { // 已访问 } else { #if PY_VERSION_HEX >= 0x03090000 Py_VISIT(Py_TYPE(self)); #endif }
定义tp_dealloc	正确处理引用计数	static void my_dealloc(PyObject *self) { PyObject_GC_UnTrack(self);... PyTypeObject* type = Py_TYPE(self); type->tp_free(self); Py_DECREF(type); }
设置tp_free	设为PyObject_GC_Del()且不重载	my_type.tp_free = PyObject_GC_Del;
分配对象	使用带 GC 感知的函数	TYPE* o = typeobj->tp_alloc(typeobj, 0); 或 TYPE* o = PyObject_GC_New(TYPE, typeobj);

七、类对模块状态的访问

使用PyType_FromModuleAndSpec()定义的类型对象，可通过PyType_GetModule()获取关联模块，再用PyModule_GetState()获取模块状态；也可使用PyType_GetModuleState()合并这两步操作。从类的常规方法访问模块状态时，由于 Python 3.9 引入的 API，需先获取方法定义所在的类（注意与Py_TYPE(self)的区别），再调用PyType_GetModuleState()获取状态 。对于槽位方法、读取方法和设置方法（Python 3.11 新增特性），可使用PyType_GetModuleByDef()函数并传入模块定义，获取模块后再用PyModule_GetState()获取状态 。

八、模块状态的生命期

当模块对象被当作垃圾回收时，其模块状态将被释放。通常使用PyType_FromModuleAndSpec()创建的类型及其实例会持有对模块的引用，但在从外部库回调引用模块状态时要格外小心，确保持有对模块对象的引用，避免模块状态提前释放 。

九、未解决的问题

目前围绕模块级状态和堆类型仍存在一些问题。例如，在 Python 3.11 中还无法不依赖 CPython 实现细节将状态关联到单个类型；堆类型 API 无法实现从静态类型的 “无损” 转换 。相关讨论可在 capi-sig 邮件列表进行。

十、实际项目示例：数据库连接管理扩展模块

假设我们正在开发一个数据库连接管理的 Python 扩展模块，用于在多解释器环境下为不同的数据库操作提供连接服务。每个解释器可能会有不同的数据库连接需求，并且这些连接状态需要相互隔离，以确保数据操作的独立性和安全性。

（一）模块级状态管理

#include <Python.h>
#include <stdio.h>

// 定义模块状态结构体
typedef struct {
    int connection_count;
    // 这里可以添加更多与数据库连接相关的状态信息，如连接池等
} MyDBModuleState;

// 模块初始化函数
static struct PyModuleDef mydbmodule = {
    PyModuleDef_HEAD_INIT,
    "mydb",  // 模块名
    NULL,    // 模块文档字符串
    sizeof(MyDBModuleState),  // 为模块状态分配空间
    NULL, NULL, NULL, NULL, NULL
};

PyMODINIT_FUNC PyInit_mydb(void) {
    PyObject *m;
    m = PyModule_Create(&mydbmodule);
    if (m == NULL) {
        return NULL;
    }

    // 初始化模块状态
    MyDBModuleState *state = (MyDBModuleState *)PyModule_GetState(m);
    if (state != NULL) {
        state->connection_count = 0;
    }

    return m;
}

在上述代码中，我们定义了一个MyDBModuleState结构体来存储模块级状态，这里简单记录了数据库连接的数量。在模块初始化时，通过PyModule_GetState获取模块状态并进行初始化。

（二）函数对模块状态的访问

// 定义一个函数用于获取当前连接数量
static PyObject* get_connection_count(PyObject *self, PyObject *args) {
    MyDBModuleState *state = (MyDBModuleState *)PyModule_GetState(self);
    if (state == NULL) {
        Py_RETURN_NONE;
    }
    return PyLong_FromLong(state->connection_count);
}

// 定义模块方法列表
static PyMethodDef mydb_methods[] = {
    {"get_connection_count", (PyCFunction)get_connection_count, METH_NOARGS, "Get the current number of database connections."},
    {NULL, NULL, 0, NULL}
};

// 模块初始化函数（更新）
PyMODINIT_FUNC PyInit_mydb(void) {
    PyObject *m;
    m = PyModule_Create(&mydbmodule);
    if (m == NULL) {
        return NULL;
    }

    // 初始化模块状态
    MyDBModuleState *state = (MyDBModuleState *)PyModule_GetState(m);
    if (state != NULL) {
        state->connection_count = 0;
    }

    // 添加模块方法
    if (PyModule_AddFunctions(m, mydb_methods) < 0) {
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

这里定义了一个get_connection_count函数，通过PyModule_GetState获取模块状态，并返回当前的数据库连接数量。

（三）堆类型的使用与模块状态访问

// 定义一个堆类型用于表示数据库连接对象
typedef struct {
    PyObject_HEAD
    // 这里可以添加连接对象的具体数据成员，如数据库游标等
} MyDBConnection;

// 定义堆类型的方法
static PyObject* mydb_connection_method(PyObject *self, PyObject *args) {
    MyDBModuleState *state = (MyDBModuleState *)PyType_GetModuleState(Py_TYPE(self));
    if (state == NULL) {
        Py_RETURN_NONE;
    }
    // 这里可以根据模块状态进行具体的数据库操作
    state->connection_count++;
    return PyLong_FromLong(state->connection_count);
}

// 定义堆类型的方法列表
static PyMethodDef mydb_connection_methods[] = {
    {"mydb_connection_method", (PyCFunction)mydb_connection_method, METH_NOARGS, "Perform an operation related to the database connection."},
    {NULL, NULL, 0, NULL}
};

// 定义堆类型的类型对象
static PyType_Spec mydb_connection_spec = {
    "mydb.MyDBConnection",  // 类型名称
    sizeof(MyDBConnection), // 类型大小
    0,                      // 基类
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, // 类型标志
    mydb_connection_methods, // 方法列表
    NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL
};

// 模块初始化函数（进一步更新）
PyMODINIT_FUNC PyInit_mydb(void) {
    PyObject *m;
    m = PyModule_Create(&mydbmodule);
    if (m == NULL) {
        return NULL;
    }

    // 初始化模块状态
    MyDBModuleState *state = (MyDBModuleState *)PyModule_GetState(m);
    if (state != NULL) {
        state->connection_count = 0;
    }

    // 添加模块方法
    if (PyModule_AddFunctions(m, mydb_methods) < 0) {
        Py_DECREF(m);
        return NULL;
    }

    // 创建堆类型
    PyObject *mydb_connection_type = PyType_FromModuleAndSpec(m, &mydb_connection_spec);
    if (mydb_connection_type == NULL) {
        Py_DECREF(m);
        return NULL;
    }

    // 将堆类型添加到模块的__dict__中
    if (PyModule_AddObject(m, "MyDBConnection", mydb_connection_type) < 0) {
        Py_DECREF(mydb_connection_type);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

在这个示例中，我们定义了一个MyDBConnection堆类型来表示数据库连接对象。在mydb_connection_method方法中，通过PyType_GetModuleState获取模块状态，并对连接数量进行操作。在模块初始化时，创建了堆类型并将其添加到模块的__dict__中，方便在 Python 代码中使用。

通过这个实际项目示例，我们可以看到如何在多解释器环境下，使用模块级状态和堆类型来管理数据库连接相关的状态和操作，确保不同解释器之间的数据库操作相互隔离，提高系统的稳定性和安全性。

总结

本文围绕 Python 扩展模块在多解释器环境下的状态管理展开，介绍了进程级状态的问题，重点阐述了模块级状态的优势和实现方式，包括管理全局和模块级状态、函数和类对模块状态的访问，以及堆类型相关的知识和操作要点。通过引入数据库连接管理扩展模块的实际项目示例，更直观地展示了相关技术的应用。虽然目前还存在一些未解决的问题，但通过遵循这些原则和方法，C-API 扩展维护者能够编写出更安全、可靠的扩展模块，使其在复杂的多解释器场景中稳定运行。

TAG： Python；扩展模块；模块级状态；堆类型；多解释器；C-API；数据库连接管理

相关学习资源

1. Python 官方文档：本文参考的官方文档，是深入学习的基础资料，提供了详细的技术细节和示例。
2. capi-sig 邮件列表：capi-sig 邮件列表，是讨论 Python C API 相关问题的重要平台，可获取关于模块级状态和堆类型等未解决问题的最新讨论和进展。