为 Python 编写 C++ 扩展模块

使用 C 扩展使某些功能在 Python 中可用。
1 位读者喜欢这个。
Coding on a computer

在我之前的一篇文章中,我概述了 六个 Python 解释器。在大多数系统中,CPython 解释器是默认的,并且我上一篇文章的投票也表明 CPython 是最受欢迎的。CPython 的一个特点是能够使用 CPython 的扩展 API 用 C 编写 Python 模块。用 C 编写 Python 模块允许你将计算密集型代码移动到 C,同时保持 Python 的易于访问性。

在本文中,我将向你展示如何编写一个扩展模块。我没有使用纯 C,而是使用了 C++,因为大多数编译器通常都理解这两种语言。我必须提前提到一个主要的缺点:以这种方式构建的 Python 模块不能移植到其他解释器。它们只能与 CPython 解释器一起使用。因此,如果你正在寻找一种更便携的方式与 C 库交互,请考虑使用 ctypes 模块。

源代码

像往常一样,你可以在 GitHub 上找到相关的源代码。存储库中的 C++ 文件具有以下用途

  • my_py_module.cpp: Python 模块 *MyModule* 的定义
  • my_cpp_class.h: 一个仅包含头文件的 C++ 类,它将被暴露给 Python
  • my_class_py_type.h/cpp: 我们的 C++ 类的 Python 表示
  • pydbg.cpp: 用于调试目的的单独应用程序

你在本文中构建的 Python 模块没有任何实际用途,但它是一个很好的例子。

构建模块

在查看源代码之前,你可以检查该模块是否在你的系统上编译。 我使用 CMake 来创建构建配置,因此你的系统上必须安装 CMake。为了配置和构建模块,你可以让 Python 运行该过程

$ python3 setup.py build

或者手动运行该过程

$ cmake -B build
$ cmake --build build

之后,你在 /build 子目录中会有一个名为 MyModule.so 的文件。

定义一个扩展模块

首先,查看 my_py_module.cpp,特别是函数 PyInit_MyModule

PyMODINIT_FUNC
PyInit_MyModule(void) {
    PyObject* module = PyModule_Create(&my_module);
    
    PyObject *myclass = PyType_FromSpec(&spec_myclass);
    if (myclass == NULL){
        return NULL;
    }
    Py_INCREF(myclass);
    
    if(PyModule_AddObject(module, "MyClass", myclass) < 0){
        Py_DECREF(myclass);
        Py_DECREF(module);
        return NULL;
    }
    return module;
}

这是本示例中最关键的代码,因为它充当 CPython 的入口点。通常,当 Python C 扩展被编译并作为共享对象二进制文件提供时,CPython 会在同名的二进制文件 (<ModuleName>.so) 中搜索函数 PyInit_<ModuleName>,并在尝试导入它时执行它。

所有 Python 类型,无论是声明还是实例,都作为指向 PyObject 的指针公开。在这个函数的第一个部分,模块的根定义通过运行 PyModule_Create(...) 来创建。正如你在模块规范 (my_module, 同一个文件) 中看到的那样,它没有任何特殊的功能。

之后,调用 PyType_FromSpec 来为自定义类型 MyClass 创建 Python 堆类型 定义。堆类型对应于一个 Python 类。然后将类型定义分配给模块 MyModule。

请注意,如果其中一个函数失败,则必须减少先前创建的 PyObject 的引用计数,以便它们被解释器删除。

指定 Python 类型

类型 MyClass 的规范在 my_class_py_type.h 中作为一个 PyType_Spec 的实例找到

static PyType_Spec spec_myclass = {
    "MyClass",                                  // name
    sizeof(MyClassObject) + sizeof(MyClass),    // basicsize
    0,                                          // itemsize
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,   // flags
    MyClass_slots                               // slots
};

此结构定义了该类的一些基本类型信息。 传递给 size 的值由 Python 表示 (MyClassObject) 的大小和普通 C++ 类 (MyClass) 的大小组成。 MyClassObject 定义如下

typedef struct {
    PyObject_HEAD
    int         m_value;
    MyClass*    m_myclass;
} MyClassObject;

Python 表示基本上是 PyObject 类型,由宏 PyObject_HEAD 定义,以及一些附加成员。成员 m_value 作为普通类成员公开,而成员 m_myclass 只能从 C++ 代码内部访问。

PyType_Slot 定义了一些附加功能

static PyType_Slot MyClass_slots[] = {
    {Py_tp_new,     (void*)MyClass_new},
    {Py_tp_init,    (void*)MyClass_init},
    {Py_tp_dealloc, (void*)MyClass_Dealloc},
    {Py_tp_members, MyClass_members},
    {Py_tp_methods, MyClass_methods},
    {0, 0} /* Sentinel */
};

在这里,一些初始化和反初始化函数的跳转地址被设置,以及普通的类方法和成员。 也可以设置附加功能,例如分配初始属性字典,但这是可选的。 这些定义通常以一个 sentinel 结尾,它由 NULL 值组成。

为了完成类型规范,这是方法和成员表

static PyMethodDef MyClass_methods[] = {
    {"addOne", (PyCFunction)MyClass_addOne, METH_NOARGS,  PyDoc_STR("Return an incrmented integer")},
    {NULL, NULL} /* Sentinel */
};

static struct PyMemberDef MyClass_members[] = {
    {"value", T_INT, offsetof(MyClassObject, m_value)},
    {NULL} /* Sentinel */
};

在该方法表中,定义了 Python 方法 addOne,它指向相关的函数 MyClass_addOne。 此函数充当一个包装器。它调用 C++ 类中的 addOne() 方法。

在成员表中,只定义了一个成员用于演示目的。 遗憾的是,PyMemberDefoffsetof 的使用不允许将 C++ 特定类型添加到 MyClassObject。 如果你尝试放置一些 C++ 类型容器(例如 std::optional),编译器会以与内存布局相关的警告的形式对其进行抱怨。

初始化和反初始化

方法 MyClass_new 仅用于为 MyClassObject 提供初始值并为基本类型分配内存

PyObject *MyClass_new(PyTypeObject *type, PyObject *args, PyObject *kwds){
    std::cout << "MtClass_new() called!" << std::endl;

    MyClassObject *self;
    self = (MyClassObject*) type->tp_alloc(type, 0);
    if(self != NULL){ // -> allocation successfull
        // assign initial values
        self->m_value   = 0;
        self->m_myclass = NULL; 
    }
    return (PyObject*) self;
}

实际的初始化发生在 MyClass_init 中,它对应于 Python 中的 __init__() 方法

int MyClass_init(PyObject *self, PyObject *args, PyObject *kwds){
    
    ((MyClassObject *)self)->m_value = 123;
    
    MyClassObject* m = (MyClassObject*)self;
    m->m_myclass = (MyClass*)PyObject_Malloc(sizeof(MyClass));

    if(!m->m_myclass){
        PyErr_SetString(PyExc_RuntimeError, "Memory allocation failed");
        return -1;
    }

    try {
        new (m->m_myclass) MyClass();
    } catch (const std::exception& ex) {
        PyObject_Free(m->m_myclass);
        m->m_myclass = NULL;
        m->m_value   = 0;
        PyErr_SetString(PyExc_RuntimeError, ex.what());
        return -1;
    } catch(...) {
        PyObject_Free(m->m_myclass);
        m->m_myclass = NULL;
        m->m_value   = 0;
        PyErr_SetString(PyExc_RuntimeError, "Initialization failed");
        return -1;
    }

    return 0;
}

如果你希望在初始化期间传递参数,则必须在此处调用 PyArg_ParseTuple。 为了简单起见,在此示例中将忽略在初始化期间传递的所有参数。 在该函数的第一个部分中,PyObject 指针 (self) 被重新解释为指向 MyClassObject 的指针,以便访问我们的其他成员。 此外,C++ 类的内存被分配并且其构造函数被执行。

请注意,必须仔细进行异常处理和内存分配(和释放),以防止内存泄漏。 当引用计数降至零时,MyClass_dealloc 函数会负责释放所有相关的堆内存。 在文档中有一个 专门的章节,介绍 C 和 C++ 扩展的内存管理。

方法包装器

从 Python 类调用相关的 C++ 类方法很容易

PyObject* MyClass_addOne(PyObject *self, PyObject *args){
    assert(self);

    MyClassObject* _self = reinterpret_cast<MyClassObject*>(self);
    unsigned long val = _self->m_myclass->addOne();
    return PyLong_FromUnsignedLong(val);
}

再次,PyObject* 参数 (self) 被转换为 MyClassObject*,以便访问 m_myclass,一个指向 C++ 类实例的指针。 有了这些信息,类的 addOne() 方法被调用,并且结果以 Python 整数对象 的形式返回。

3 种调试方法

出于调试目的,以调试配置编译 CPython 解释器可能是有价值的。 在 官方文档 中可以找到详细的描述。 只要下载预安装的解释器的其他调试符号,就可以按照以下步骤进行操作。

GNU 调试器

当然,古老的 GNU 调试器 (GDB) 在这里也很有用。 我包含了一个 gdbinit 文件,其中定义了一些选项和断点。 还有一个 gdb.sh 脚本,它创建一个调试构建并启动一个 GDB 会话

Gnu Debugger (GDB) is useful for your Python C and C++ extensions.

(Stephan Avenwedde, CC BY-SA 4.0)

GDB 使用脚本文件 main.py 调用 CPython 解释器。 该脚本文件允许你轻松地定义要对 Python 扩展模块执行的所有操作。

C++ 应用程序

另一种方法是将 CPython 解释器嵌入到单独的 C++ 应用程序中。 在存储库中,可以在文件 pydbg.cpp 中找到它

int main(int argc, char *argv[], char *envp[])
{
    Py_SetProgramName(L"DbgPythonCppExtension");
    Py_Initialize();

    PyObject *pmodule = PyImport_ImportModule("MyModule");
    if (!pmodule) {
        PyErr_Print();
        std::cerr << "Failed to import module MyModule" << std::endl;
        return -1;
    }

    PyObject *myClassType = PyObject_GetAttrString(pmodule, "MyClass");
    if (!myClassType) {
        std::cerr << "Unable to get type MyClass from MyModule" << std::endl;
        return -1;
    }

    PyObject *myClassInstance = PyObject_CallObject(myClassType, NULL);

    if (!myClassInstance) {
        std::cerr << "Instantioation of MyClass failed" << std::endl;
        return -1;
    }

    Py_DecRef(myClassInstance); // invoke deallocation
    return 0;
}

使用 高级接口,可以包含扩展模块并对其执行操作。 这允许你在本地 IDE 环境中进行调试。 它还使你可以更精细地控制从扩展模块传递到扩展模块的变量。

缺点是创建额外应用程序的成本很高。

VSCode 和 VSCodium LLDB 扩展

使用像 CodeLLDB 这样的调试器扩展可能是最方便的调试选项。 存储库包含用于构建扩展的 VSCode 或 VSCodium 配置文件(task.json, CMake Tools) 和调用调试器 (launch.json)。 这种方法结合了前面几种方法的优点:在图形化 IDE 中进行调试,在 Python 脚本文件中定义操作,甚至可以在解释器提示符中动态定义操作。

VSCodium features an integrated debugger.

(Stephan Avenwedde, CC BY-SA 4.0)

用 Python 扩展 C++

从 Python 代码可用的所有功能也可以从 C 或 C++ 扩展中获得。 虽然用 Python 编写代码通常被认为很容易,但在 C 或 C++ 中扩展 Python 也可能很痛苦。 另一方面,虽然原生 Python 代码比 C++ 慢,但 C 或 C++ 扩展可以使计算密集型任务提升到原生机器代码的速度。

您还必须考虑使用 ABI。正如文档中所述,稳定的 ABI 提供了一种保持与旧版本 CPython 向后兼容性的方法。

最终,您必须权衡利弊。如果您决定使用 C 扩展来使某些功能在 Python 中可用,那么您已经了解了如何做到这一点。

标签
User profile image.
Stephan 是一位技术爱好者,他喜欢开源,因为它能深入了解事物的运作方式。Stephan 在工业自动化软件(主要为专有领域)中担任全职支持工程师。如果可能,他会从事基于 Python 的开源项目、撰写文章或骑摩托车。

评论已关闭。

Creative Commons License本作品采用知识共享署名-相同方式共享 4.0 国际许可协议进行许可。
© 2025 open-source.net.cn. All rights reserved.