为 Python 写一个 C++ 扩展模块

开发 后端
在本文中,我将向你展示如何编写一个 C++ 扩展模块。使用 C++ 而不是 C,因为大多数编译器通常都能理解这两种语言。

使用 C 扩展为 Python 提供特定功能。

在前一篇文章中,我介绍了 ​​六个 Python 解释器​​。在大多数系统上,CPython 是默认的解释器,而且根据民意调查显示,它还是最流行的解释器。Cpython 的独有功能是使用扩展 API 用 C 语言编写 Python 模块。用 C 语言编写 Python 模块允许你将计算密集型代码转移到 C,同时保留 Python 的易用性。

在本文中,我将向你展示如何编写一个 C++ 扩展模块。使用 C++ 而不是 C,因为大多数编译器通常都能理解这两种语言。我必须提前说明缺点:以这种方式构建的 Python 模块不能移植到其他解释器中。它们只与 CPython 解释器配合工作。因此,如果你正在寻找一种可移植性更好的与 C 语言模块交互的方式,考虑下使用 ​​ctypes​​ 模块。

源代码

和往常一样,你可以在 ​​GitHub​​ 上找到相关的源代码。仓库中的 C++ 文件有以下用途:

  • ​my_py_module.cpp​​: Python 模块​​MyModule​​ 的定义
  • ​my_cpp_class.h​​: 一个头文件 - 只有一个暴露给 Python 的 C++ 类
  • ​my_class_py_type.h/cpp​​: Python 形式的 C++ 类
  • ​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_FUNCPyInit_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​​ 的一个指针。在此函数的第一部分中,​​module​​ 通过 ​​PyModule_Create(...)​​ 创建的。正如你在 ​​module​​ 详述(​​my_py_module​​,同名文件)中看到的,它没有任何特殊的功能。

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

注意,如果其中一个函数返回失败,则必须减少以前创建的复制对象的引用计数,以便解释器删除它们。

指定 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};

它定义了一些基本类型信息,它的大小包括 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 */};

在这里,设置了一些初始化和析构函数的跳转,还有普通的类方法和成员,还可以设置其他功能,如分配初始属性字典,但这是可选的。这些定义通常以一个哨兵结束,包含 ​​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​​,它指向相关的 C++ 函数 ​​MyClass_addOne​​。它充当了一个包装器,它在 C++ 类中调用 ​​addOne()​​ 方法。

在成员表中,只有一个为演示目的而定义的成员。不幸的是,在 ​​PyMemberDef​​ 中使用的 ​​offsetof​​ 不允许添加 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){ // -> 分配成功        // 赋初始值        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 调试器(GDB)对于 Python C 和 C++ 扩展非常有用

Gnu 调试器(GDB)对于 Python C 和 C++ 扩展非常有用

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 有一个集成的调试器。

VSCodium 有一个集成的调试器。

用 C++ 扩展 Python

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

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

最后,你必须自己权衡利弊。如果你决定使用 C 语言来扩展 Python 中的一些功能,你已经看到了如何实现它。

责任编辑:庞桂玉 来源: Linux中国
相关推荐

2011-09-16 10:00:56

C++

2011-11-24 15:08:40

C++

2021-05-28 18:12:51

C++设计

2019-10-29 05:47:15

CC++Python

2010-03-01 09:43:09

Python编程语言

2018-10-31 10:11:24

Python编程语言语音播放

2022-03-22 06:33:49

Python内置模块函数

2010-01-15 18:57:58

C++CLI

2022-03-24 14:42:19

Python编程语言

2021-04-14 07:47:58

PythonC++数组

2017-06-20 12:48:55

React Nativ自定义模块Note.js

2019-05-16 14:50:32

CythonPython编程语言

2010-01-14 11:14:47

C++应用程序

2013-07-18 09:58:18

C++程序员

2021-05-14 10:45:21

PythonNoSQL数据库

2022-06-27 09:54:38

编程语言JavaC++

2017-05-18 12:16:03

LinuxPythonNoSql

2017-06-08 15:53:38

PythonWeb框架

2017-02-13 16:47:13

iOSDSL开发

2021-10-27 11:29:32

框架Web开发
点赞
收藏

51CTO技术栈公众号