Python/C API扩展开发指南：用C/C++扩展Python功能

Python/C API扩展开发指南：用C/C++扩展Python功能

cpython cpython: 是Python编程语言的官方源代码仓库，包含Python解释器和标准库的实现。 项目地址: https://gitcode.com/gh_mirrors/cp/cpython

为什么需要扩展Python

Python作为一门高级语言，虽然功能强大，但在某些场景下需要与底层系统交互或追求极致性能时，原生Python代码可能无法满足需求。这时我们可以通过C/C++扩展Python，实现：

1. 创建新的内置对象类型
2. 直接调用C库函数和系统调用
3. 提升关键代码段的执行效率

Python提供了完善的C API，开发者只需包含Python.h头文件即可访问Python运行时系统的各种功能。

扩展开发基础

准备工作

每个扩展模块都需要包含以下基础结构：

#define PY_SSIZE_T_CLEAN
#include <Python.h>

这个头文件必须在所有标准头文件之前包含，因为它可能定义一些会影响标准头文件的预处理宏。

简单示例：系统命令调用

让我们创建一个名为spam的模块，提供调用系统命令的功能：

static PyObject* spam_system(PyObject* self, PyObject* args) {
    const char* command;
    int sts;
    
    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    
    sts = system(command);
    return PyLong_FromLong(sts);
}

这个函数展示了扩展开发的基本模式：

1. 解析Python传入的参数
2. 执行核心功能
3. 将结果转换为Python对象返回

参数解析

PyArg_ParseTuple是参数解析的核心函数，其格式字符串支持多种类型：

• "s"：字符串
• "i"：整数
• "f"：浮点数
• "O"：任意Python对象

错误处理机制

异常处理原则

Python扩展中的错误处理遵循以下约定：

1. 函数失败时应设置异常并返回错误值（NULL或-1）
2. 异常信息存储在解释器的线程状态中
3. 错误应逐层传递，不要重复设置异常

常用异常设置函数

• PyErr_SetString：用字符串描述设置异常
• PyErr_SetFromErrno：根据errno设置异常
• PyErr_SetObject：用Python对象设置异常

自定义异常

模块可以定义自己的异常类型：

static PyObject* SpamError = NULL;

static int spam_module_exec(PyObject* m) {
    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    if (PyModule_AddObjectRef(m, "SpamError", SpamError) < 0) {
        return -1;
    }
    return 0;
}

模块初始化和方法表

方法表定义

每个模块需要定义方法表，描述模块提供的函数：

static PyMethodDef spam_methods[] = {
    {"system", spam_system, METH_VARARGS, "Execute a shell command."},
    {NULL, NULL, 0, NULL}  // 哨兵
};

调用约定标志：

• METH_VARARGS：仅位置参数
• METH_KEYWORDS：支持关键字参数
• METH_VARARGS | METH_KEYWORDS：同时支持

模块初始化

模块初始化函数命名必须为PyInit_<模块名>：

PyMODINIT_FUNC PyInit_spam(void) {
    return PyModuleDef_Init(&spam_module);
}

PyMODINIT_FUNC宏确保函数具有正确的返回类型和链接规范。

嵌入式Python中的模块初始化

在嵌入式Python环境中，模块初始化函数不会自动调用，需要手动添加到初始化表：

int main(int argc, char* argv[]) {
    PyImport_AppendInittab("spam", PyInit_spam);
    // 其他初始化代码...
}

最佳实践建议

1. 内存管理：注意引用计数，避免内存泄漏
2. 异常安全：确保在任何错误路径上都正确清理资源
3. 类型安全：严格检查参数类型
4. 文档注释：为每个函数添加清晰的文档字符串
5. 兼容性：考虑不同Python版本的API差异

通过遵循这些原则和模式，开发者可以创建高效、稳定的Python扩展模块，充分发挥C/C++的性能优势，同时保持Python的易用性。

cpython cpython: 是Python编程语言的官方源代码仓库，包含Python解释器和标准库的实现。 项目地址: https://gitcode.com/gh_mirrors/cp/cpython