為 Python 寫一個 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 會在同名二進位檔案中（

.so<ModuleName>）搜尋  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",// namesizeof(MyClassObject) + sizeof(MyClass),// basicsize0,// itemsizePy_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, // flagsMyClass_slots // slots};

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

typedef struct {PyObject_HEADint 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++ 扩展非常有用

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 deallocationreturn 0;}

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

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

VSCode 和 VSCodium LLDB 扩展

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

VSCodium 有一个集成的调试器。

用 C++ 扩展 Python

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

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

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

以上是為 Python 寫一個 C++ 擴充模組的詳細內容。更多資訊請關注PHP中文網其他相關文章！