为 Python 写一个 C++ 扩展模块 | Linux 中国

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

本文字数：7993，阅读时长大约： 9分钟

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

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

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

源代码

和往常一样，你可以在 github.com 上找到相关的源代码。仓库中的 C++ 文件有以下用途：

◈my_py_module.cpp: Python 模块MyModule的定义

◈my_cpp_class.h: 一个头文件 - 只有一个暴露给 Python 的 C++ 类

◈my_class_py_type.h/cpp: Python 形式的 C++ 类

◈pydbg.cpp: 用于调试的单独应用程序

本文构建的 Python 模块不会有任何实际用途，但它是一个很好的示例。

构建模块

在查看源代码之前，你可以检查它是否能在你的系统上编译。 opensource.com 来创建构建的配置信息，因此你的系统上必须安装 CMake。为了配置和构建这个模块，可以让 Python 去执行这个过程：

1. $ python3 setup.py build

或者手动执行：

1. $ cmake -B build

2. $ cmake --build build

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

定义扩展模块

首先，看一下my_py_module.cpp文件，尤其是PyInit_MyModule函数：

1. PyMODINIT_FUNC

2. PyInit_MyModule(void) {

3. PyObject* module = PyModule_Create(&my_module);

5. PyObject *myclass = PyType_FromSpec(&spec_myclass);

6. if (myclass == NULL){

7. return NULL;

8. }

9. Py_INCREF(myclass);

11. if(PyModule_AddObject(module, "MyClass", myclass) < 0){

12. Py_DECREF(myclass);

13. Py_DECREF(module);

14. return NULL;

15. }

16. return module;

17. }

这是本例中最重要的代码，因为它是 CPython 的入口点。一般来说，当一个 Python C 扩展被编译并作为共享对象二进制文件提供时，CPython 会在同名二进制文件中（.so）搜索PyInit_函数，并在试图导入时执行它。

无论是声明还是实例，所有 Python 类型都是 docs.python.org 的一个指针。在此函数的第一部分中，module通过PyModule_Create(...)创建的。正如你在module详述（my_py_module，同名文件）中看到的，它没有任何特殊的功能。

之后，调用 docs.python.org 为自定义类型MyClass创建一个 Python docs.python.org 定义。一个堆类型对应于一个 Python 类，然后将它赋值给MyModule模块。

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

指定 Python 类型

MyClass详述在 github.com 中可以找到，它作为 docs.python.org 的一个实例：

1. static PyType_Spec spec_myclass = {

2. "MyClass", // name

3. sizeof(MyClassObject) + sizeof(MyClass), // basicsize

4. 0, // itemsize

5. Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, // flags

6. MyClass_slots // slots

7. };

它定义了一些基本类型信息，它的大小包括 Python 表示的大小（MyClassObject）和普通 C++ 类的大小（MyClass）。MyClassObject定义如下：

1. typedef struct {

2. PyObject_HEAD

3. int m_value;

4. MyClass* m_myclass;

5. } MyClassObject;

Python 表示的话就是 docs.python.org 类型，由PyObject_HEAD宏和其他一些成员定义。成员m_value视为普通类成员，而成员m_myclass只能在 C++ 代码内部访问。

docs.python.org 定义了一些其他功能：

1. static PyType_Slot MyClass_slots[] = {

2. {Py_tp_new, (void*)MyClass_new},

3. {Py_tp_init, (void*)MyClass_init},

4. {Py_tp_dealloc, (void*)MyClass_Dealloc},

5. {Py_tp_members, MyClass_members},

6. {Py_tp_methods, MyClass_methods},

7. {0, 0} /* Sentinel */

8. };

在这里，设置了一些初始化和析构函数的跳转，还有普通的类方法和成员，还可以设置其他功能，如分配初始属性字典，但这是可选的。这些定义通常以一个哨兵结束，包含NULL值。

要完成类型详述，还包括下面的方法和成员表：

1. static PyMethodDef MyClass_methods[] = {

2. {"addOne", (PyCFunction)MyClass_addOne, METH_NOARGS, PyDoc_STR("Return an incrmented integer")},

3. {NULL, NULL} /* Sentinel */

4. };

6. static struct PyMemberDef MyClass_members[] = {

7. {"value", T_INT, offsetof(MyClassObject, m_value)},

8. {NULL} /* Sentinel */

9. };

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

在成员表中，只有一个为演示目的而定义的成员。不幸的是，在 docs.python.org 中使用的 en.cppreference.com 不允许添加 C++ 类型到MyClassObject。如果你试图放置一些 C++ 类型的容器（如 en.cppreference.com），编译器会抱怨一些内存布局相关的警告。

初始化和析构

MyClass_new方法只为MyClassObject提供一些初始值，并为其类型分配内存：

1. PyObject *MyClass_new(PyTypeObject *type, PyObject *args, PyObject *kwds){

2. std::cout << "MtClass_new() called!" << std::endl;

4. MyClassObject *self;

5. self = (MyClassObject*) type->tp_alloc(type, 0);

6. if(self != NULL){ // -> 分配成功

7. // 赋初始值

8. self->m_value = 0;

9. self->m_myclass = NULL;

10. }

11. return (PyObject*) self;

12. }

实际的初始化发生在MyClass_init中，它对应于 Python 中的 docs.python.org 方法：

1. int MyClass_init(PyObject *self, PyObject *args, PyObject *kwds){

3. ((MyClassObject *)self)->m_value = 123;

5. MyClassObject* m = (MyClassObject*)self;

6. m->m_myclass = (MyClass*)PyObject_Malloc(sizeof(MyClass));

8. if(!m->m_myclass){

9. PyErr_SetString(PyExc_RuntimeError, "Memory allocation failed");

10. return -1;

11. }

13. try {

14. new (m->m_myclass) MyClass();

15. } catch (const std::exception& ex) {

16. PyObject_Free(m->m_myclass);

17. m->m_myclass = NULL;

18. m->m_value = 0;

19. PyErr_SetString(PyExc_RuntimeError, ex.what());

20. return -1;

21. } catch(...) {

22. PyObject_Free(m->m_myclass);

23. m->m_myclass = NULL;

24. m->m_value = 0;

25. PyErr_SetString(PyExc_RuntimeError, "Initialization failed");

26. return -1;

27. }

29. return 0;

30. }

如果你想在初始化过程中传递参数，必须在此时调用 docs.python.org。简单起见，本例将忽略初始化过程中传递的所有参数。在函数的第一部分中，PyObject指针（self）被强转为MyClassObject类型的指针，以便访问其他成员。此外，还分配了 C++ 类的内存，并执行了构造函数。

注意，为了防止内存泄漏，必须仔细执行异常处理和内存分配（还有释放）。当引用计数将为零时，MyClass_dealloc函数负责释放所有相关的堆内存。在文档中有一个章节专门讲述关于 C 和 C++ 扩展的内存管理。

包装方法

从 Python 类中调用相关的 C++ 类方法很简单：

1. PyObject* MyClass_addOne(PyObject *self, PyObject *args){

2. assert(self);

4. MyClassObject* _self = reinterpret_cast(self);

5. unsigned long val = _self->m_myclass->addOne();

6. return PyLong_FromUnsignedLong(val);

7. }

同样，PyObject参数（self）被强转为MyClassObject类型以便访问m_myclass，它指向 C++ 对应类实例的指针。有了这些信息，调用addOne()类方法，并且结果以 docs.python.org 返回。

3 种方法调试

出于调试目的，在调试配置中编译 CPython 解释器是很有价值的。详细描述参阅 docs.python.org。只要下载了预安装的解释器的其他调试符号，就可以按照下面的步骤进行操作。

GNU 调试器

当然，老式的 opensource.com 也可以派上用场。源码中包含了一个 github.com 文件，定义了一些选项和断点，另外还有一个 github.com 脚本，它会创建一个调试构建并启动一个 GDB 会话：

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

GDB 使用脚本文件 github.com 调用 CPython 解释器，它允许你轻松定义你想要使用 Python 扩展模块执行的所有操作。

C++ 应用

另一种方法是将 CPython 解释器嵌入到一个单独的 C++ 应用程序中。可以在仓库的 github.com 文件中找到：

1. int main(int argc, char *argv[], char *envp[])

2. {

3. Py_SetProgramName(L"DbgPythonCppExtension");

4. Py_Initialize();

6. PyObject *pmodule = PyImport_ImportModule("MyModule");

7. if (!pmodule) {

8. PyErr_Print();

9. std::cerr << "Failed to import module MyModule" << std::endl;

10. return -1;

11. }

13. PyObject *myClassType = PyObject_GetAttrString(pmodule, "MyClass");

14. if (!myClassType) {

15. std::cerr << "Unable to get type MyClass from MyModule" << std::endl;

16. return -1;

17. }

19. PyObject *myClassInstance = PyObject_CallObject(myClassType, NULL);

21. if (!myClassInstance) {

22. std::cerr << "Instantioation of MyClass failed" << std::endl;

23. return -1;

24. }

26. Py_DecRef(myClassInstance); // invoke deallocation

27. return 0;

28. }

使用 docs.python.org，可以导入扩展模块并对其执行操作。它允许你在本地 IDE 环境中进行调试，还能让你更好地控制传递或来自扩展模块的变量。

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

VSCode 和 VSCodium LLDB 扩展

使用像 github.com 这样的调试器扩展可能是最方便的调试选项。仓库包含了一些 VSCode/VSCodium 的配置文件，用于构建扩展，如 github.com、 github.com 和调用调试器（ github.com）。这种方法结合了前面几种方法的优点：在图形 IDE 中调试，在 Python 脚本文件中定义操作，甚至在解释器提示符中动态定义操作。

VSCodium 有一个集成的调试器。

用 C++ 扩展 Python

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

你还必须考虑 ABI 的使用。稳定的 ABI 提供了一种方法来保持旧版本 CPython 的向后兼容性，如 docs.python.org 所述。

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

via:

作者： 选题： 译者： 校对：

本文由 原创编译， 荣誉推出

LCTT 译者 ：MjSeven

翻译： 175.0 篇

贡献： 1798 天

2018-01-30

2023-01-01

https://linux.cn/lctt/MjSeven

欢迎遵照 CC-BY-SA 协议规定转载，

如需转载，请在文章下留言 “ 转载：公众号名称”，

我们将为您添加白名单，授权“ 转载文章时可以修改”。