PyTorch封装后端前传: Python C 扩展的实现

我们编写一个简单的 C 函数，然后从 Python 调用它。实现包装器以更好地理解如何使用 C 语言扩展 Python 模块。

fputs()是一个简单的 C 函数，实现功能将字符串写入文件流：

intfputs(constchar *, FILE *)

函数有两个参数：const char * 是字符数组；FILE *是文件流指针。

fputs()将字符数组写入文件流指定的文件，返回一个非负值。如果操作成功，则该值表示写入文件的字节数。如果发生错误，则返回 0。C语言中的实现方法是打开文件 write.txt，把字符 "Hello Python C++!"写入文件。

#include<stdio.h>#include<stdlib.h>#include<unistd.h>intmain(){    FILE *fp = fopen("write.txt", "w");    fputs("Hello Python C++!", fp);    fclose(fp);    return 1;}

上面这个代码 gcc 编译可以运行。

接下来，我们直接使用 Python.h 来封装这个功能。

#include<Python.h>static PyObject *method_fputs(PyObject *self, PyObject *args){    // 声明了希望从 Python 代码接收的参数类型    // 写入文件流的字符串, 要写入的文件的名字    char *str, *filename = NULL;    int bytes_copied = -1;    /* Parse arguments */    // PyArg_ParseTuple()将 从Python接收的参数解析为局部变量    // args 是 PyObject 类型    // "ss"是 标识符, 指明了解析的参数的数据类型    if(!PyArg_ParseTuple(args, "ss", &str, &filename)) {        return NULL;    }    FILE *fp = fopen(filename, "w");    // 在 Python 解释器内的调用    bytes_copied = fputs(str, fp);    fclose(fp);    // PyLong_FromLong()返回PyLongObject是Python中的整型对象    // 输入bytes_copied, 返回PyLong_FromLong 给 Python 解释器      return PyLong_FromLong(bytes_copied);}

这里使用了Python.h 中定义的三个对象或函数，这里主要说明一下 PyObject，其他两个函数已经在上面的代码中注释过：

🐤PyObject

🐤PyArg_ParseTuple()

🐤PyLong_FromLong()

PyObject 用于定义 Python 对象。所有 Python 对象都使用 PyObject 结构体定义的字段。所有对象类型都是这个类型的扩展。PyObject 包含了 Python 解释器需要的信息，将指向对象的指针视为对象。例如，将上述函数的返回类型设置为 PyObject，定义了有效的 Python 类型所需的通用字段，以便 Python 解释器可以识别该类型。

上面已经写好了 Python C 扩展功能的代码。但是，要让模块正常运行，还需要编写模块和方法，如下所示：

static PyMethodDef FputsMethods[] = {    {"fputs", method_fputs, METH_VARARGS, "Python interface for fputs C library function"},    {NULL, NULL, 0, NULL}};static struct PyModuleDef fputsmodule = {    PyModuleDef_HEAD_INIT,    "fputs",    "Python interface for the fputs C library function",    -1,    FputsMethods};

这些变量包含了模块的元信息，这些信息提供给 Python 解释器使用。PyMethodDef 定义调用模块中的方法，需要告知 Python 解释器这些方法的存在。可以使用 PyMethodDef 结构体。这是一个包含 4 个成员的结构体，表示模块中的一个方法。通常 Python C 扩展模块中有多个方法被 Python 解释器调用。所以需要定义一个 PyMethodDef 结构体数组。

结构体中的每个成员都包含以下信息：

🦉"fputs" 这是用户输入以调用这个函数的名称。

🦉method_fputs 是要调用的 C 函数，之前已经定义过。

🦉METH_VARARGS 是一个标志位，用于指定扩展类型方法的调用约定，表示该方法采用标准的位置参数调用惯例。‌‌使用METH_VARARGS时，方法必须定义为PyCFunction类型‌，其函数签名接受两个参数：🪶self 指向方法所属的对象或模块，🪶args 一个元组对象，包含所有位置参数。这些参数使用通常通过PyArg_ParseTuple()或PyArg_UnpackTuple()宏解析，告诉解释器该函数有两个类型为 PyObject* 的参数。

🦉最后一个字符串是说明函数的文档字符串。

PyModuleDef  与 PyMethodDef 保存着 Python C 扩展模块中的方法信息一样， PyModuleDef 结构体保存着模块本身的信息。它不是结构体数组，只是模块定义的单个结构体。

typedef struct PyModuleDef{  PyModuleDef_Base m_base;  const char* m_name;  const char* m_doc;  Py_ssize_t m_size;  PyMethodDef *m_methods;  inquiry m_reload;  traverseproc m_traverse;  inquiry m_clear;  freefunc m_free;}PyModuleDef;

这个结构体共有 9 个成员，但不是所有成员都是必需的。在上面的代码块中，初始化了5个成员：

🦉PyModuleDef_HEAD_INIT 是 Python C API 中用于初始化模块定义结构体PyModuleDef 的宏，它将结构体的 m_base 成员设置为初始值，该值通常包含类型标识符和版本信息，以确保模块定义的正确性。‌它为模块定义结构体设置必要的头部信息，包括类型标识符(如 PyModuleDef_Type)和 API 版本，从而确保模块在创建时能被 Python 解释器正确识别和处理；在模块初始化函数中(如 PyInit_module_name)，通常使用 PyModuleDef_Init() 或 PyModule_Create() 将此结构体转换为模块对象，此时 PyModuleDef_HEAD_INIT 会触发解释器对模块定义的验证。

🦉"fputs"是 Python C 扩展模块的名称。

🦉字符串是模块的文档字符串。设置 NULL 则不使用文档字符串，也可以传参指定文档字符串，使用 const char *。类型为 Py_ssize_t 。还可以使用 PyDoc_STRVAR() 为模块定义文档字符串。

🦉-1 模块的大小(以字节为单位)，通常设置为 -1 表示自动计算。有以下值：

🪶负值表示该模块不支持子解释器。

🪶非负值允许重新初始化模块。指定了模块在每个子解释器会话中需要分配的内存。

🦉FputsMethods 指向 PyMethodDef 结构体数组的指针，用于描述模块中暴露的函数。这是之前定义的 PyMethodDef 结构体数组。

Python C 扩展的模块和方法已经写好了，现在要使用它们了。当 Python 程序第一次 import 模块时，它会调用PyInit_fputs()：

PyMODINIT_FUNC PyInit_fputs(void) {    return PyModule_Create(&fputsmodule);}

PyMODINIT_FUNC 是 CPython C API 中的一个宏，声明扩展模块的初始化函数，该函数必须命名为 PyInit_ 加模块名(如 PyInit_fputs)，并返回一个 PyObject* 指针，通常指向新创建的模块对象。‌主要作用是作为 Python 解释器与 C 扩展模块之间的入口点‌，当 Python 代码导入模块时，解释器会查找并调用此函数来完成模块的初始化，包括定义模块方法、创建类型对象等操作；该宏会处理平台相关的链接声明（如在 Windows 上添加 __declspec(dllexport)）并确保函数在 C++ 中使用 extern "C" 链接，以避免名称修饰问题。‌

🏵️ 所以 PyMODINIT_FUNC 作为函数返回类型时，它隐式地执行 3 项操作：

🦉它隐式地将函数的返回类型设置为PyObject*。

🦉它声明了特殊链接。

🦉它将函数声明为 extern "C"。如果使用 C++，它会告诉 C++ 编译器不要对符号进行名称修饰。

🏵️ PyModule_Create() 是 Python C API 中用于创建模块对象的函数，属于ABI的一部分，自 Python 3.5 版本起可用。‌该函数的主要作用是创建模块对象：‌它输入一个模块对象 pyobject* 和一个模块定义结构体 pymoduledef*，并返回一个新的模块对象，类型为PyObject *。填入的参数是传递之前已定义的 fputsmodule 的地址。

我们回顾一下上面的流程。下图展示了模块的组件与 Python 解释器的交互：

当导入 Python C 扩展模块时，PyInit_fputs()是第一个调用的方法。在返回对象指针给 Python 解释器之前，函数会接着调用 PyModule_Create()。这将初始化包含模块元信息的 PyModuleDef 和 PyMethodDef 。在初始函数中会用到它们，需要预先准备好。

这些完成之后，模块对象的指针就会返回给 Python 解释器。下图就是模块的内部运行流程：

PyModule_Create() 返回的模块对象带有指向模块 PyModuleDef 的指针，模块结构有指针指向方法 PyMethodDef。当调用 Python C 扩展模块中定义的方法时，Python 解释器会使用模块对象和携带的指针来执行具体的函数。这并不是 Python 解释器底层的处理方式，但可以了解它的运行方式。还可以访问模块的其他方法和属性，比如模块或方法docstring。这些都定义在各自的结构体中。

现在已经理解了Python解释器调用 fputs() 时会发生什么: 解释器会使用模块对象和模块的方法指针来调用这些方法。

最后，看看解释器是如何处理 Python C 扩展模块的实际执行流程的：

调用 method_fputs() 时, 程序执行以下步骤：

🦉使用 PyArg_ParseTuple() 解析从Python解释器传递的参数

🦉把参数传递给 fputs() 模块的 C 函数

🦉使用用PyLong_FromLong 返回 fputs()的值

总结一下，方法解析传递给模块的参数，发送给 fputs()，返回结果。

在导入模块之前，需要先编译导入它，可以用 Python 包 distutils 或 setuptools 实现。需要编写 setup.py 文件编译安装应用程序。

最小 setup.py 文件实现如下所示：

from distutils.core import setup, Extensiondef main():    setup(name="fputs",          version="1.0.0",          description="Python interface for the fputs C library function",          author="<your name>",          author_email="email@gmail.com",          ext_modules=[Extension("fputs", ["fputsmodule.c"])])if __name__ == "__main__":    main()

setup() 的一个位置参数 ext_modules，是 Extensions 类对象的 list。Extensions 包装了 C/C++ 模块，传入2个参数到构造器里：name 模块名字 和 [filename] 源代码路径的的列表。

自此，使用 Python C APIs 封装、编译 C/C++ 代码或工具的具体方法和步骤就完成了。