使用 C 语言进行 Python 扩展编程

你使用任何编译语言(如 C、C++ 或 Java)编写的任何代码都可以集成或导入到另一个 Python 脚本中。此代码被视为“扩展”。

Python 扩展模块只不过是一个普通的 C 库。在 Unix 机器上，这些库通常以 .so (对于共享对象)。在 Windows 机器上，你通常会看到 .dll (用于动态链接库)。

编写扩展的学习前提

要开始编写扩展，你将需要 Python 头文件。

在 Unix 机器上，这通常需要安装开发人员特定的包，例如 python2.5-dev .
Windows 用户在使用二进制 Python 安装程序时将这些标头作为包的一部分。

此外，假设你对 C 或 C++ 有很好的了解，可以使用 C 编程编写任何 Python 扩展。

先看一个 Python 扩展

第一次查看 Python 扩展模块时，你需要将代码分为四部分：

头文件 Python.h .
你要作为模块接口公开的 C 函数。
将 Python 开发人员看到的函数名称映射到扩展模块内的 C 函数的表。
一个初始化函数。

头文件 Python.h

你需要包括 Python.h C 源文件中的头文件，它使你可以访问用于将模块挂接到解释器的内部 Python API。

确保在你可能需要的任何其他标头之前包含 Python.h。你需要遵循包含要从 Python 调用的函数。

C 函数

函数的 C 实现的签名总是采用以下三种形式之一：

static PyObject *MyFunction( PyObject *self, PyObject *args );

static PyObject *MyFunctionWithKeywords(PyObject *self,
                                            PyObject *args,
                                            PyObject *kw);

static PyObject *MyFunctionWithNoArgs( PyObject *self );

前面的每个声明都返回一个 Python 对象。没有这样的东西 void Python 中的函数与 C 中的函数相同。如果你不希望函数返回值，请返回 Python 的 C 等效项 None 价值。 Python 头文件定义了一个宏 Py_RETURN_NONE，它为我们做这件事。

你的 C 函数的名称可以是你喜欢的任何名称，因为它们在扩展模块之外永远不会出现。它们被定义为 static 功能。

你的 C 函数通常通过将 Python 模块和函数名称组合在一起来命名，如下所示：

static PyObject *module_func(PyObject *self, PyObject *args) {
    /* Do your stuff here. */
    Py_RETURN_NONE;
}

这是一个名为的 Python 函数 func 模块内部 module .你将把指向 C 函数的指针放入源代码中通常出现的模块的方法表中。

方法对照表

这个方法表是一个简单的 PyMethodDef 结构数组。那个结构看起来是这样的：

struct PyMethodDef {
    char *ml_name;
    PyCFunction ml_meth;
    int ml_flags;
    char *ml_doc;
};

下面是这个结构体成员的描述：

ml_name ：这是Python解释器在Python程序中使用时所呈现的函数名称。
ml_meth ：这必须是一个函数的地址，该函数具有上一节中描述的任何一个签名。
ml_flags ：这告诉解释器 ml_meth 正在使用三个签名中的哪一个。
- 该标志的值通常为 METH_VARARGS。
- 如果你想允许关键字参数进入你的函数，这个标志可以与 METH_KEYWORDS 进行按位或运算。
- 这也可以具有 METH_NOARGS 值，表示你不想接受任何参数。
ml_doc ：这是函数的文档字符串，如果你不想写，可以为NULL。

该表需要使用一个标记来终止，该标记由相应成员的 NULL 和 0 值组成。

例子

对于上面定义的函数，我们有如下方法映射表：

static PyMethodDef module_methods[] = {
    { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
    { NULL, NULL, 0, NULL }
};

初始化函数

扩展模块的最后一部分是初始化函数。该函数在模块加载时由 Python 解释器调用。需要给函数命名 init Module , where Module 是模块的名称。

初始化函数需要从你将要构建的库中导出。 Python 头文件定义 PyMODINIT_FUNC 以包含适当的咒语，以便在我们正在编译的特定环境中发生这种情况。你所要做的就是在定义函数时使用它。

你的 C 初始化函数一般有以下整体结构：

PyMODINIT_FUNC initModule() {
    Py_InitModule3(func, module_methods, "docstring...");
}

这里是描述 Py_InitModule3 功能：

func ：这是要导出的函数。
module _methods ：这是上面定义的映射表名。
文档字符串 ：这是你想在你的扩展中给出的评论。

把这一切放在一起看起来像下面这样：

#include <Python.h>

static PyObject *module_func(PyObject *self, PyObject *args) {
    /* Do your stuff here. */
    Py_RETURN_NONE;
}

static PyMethodDef module_methods[] = {
    { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
    { NULL, NULL, 0, NULL }
};

PyMODINIT_FUNC initModule() {
    Py_InitModule3(func, module_methods, "docstring...");
}

例子

一个利用上述所有概念的简单示例：

#include <Python.h>

static PyObject* helloworld(PyObject* self) {
    return Py_BuildValue("s", "Hello, Python extensions!!");
}

static char helloworld_docs[] =
    "helloworld( ): Any message you want to put here!!\n";

static PyMethodDef helloworld_funcs[] = {
    {"helloworld", (PyCFunction)helloworld,
        METH_NOARGS, helloworld_docs},
        {NULL}
};

void inithelloworld(void) {
    Py_InitModule3("helloworld", helloworld_funcs,
                        "Extension module example!");
}

Here the Py_BuildValue 函数用于构建 Python 值。将上述代码保存在 hello.c 文件中。我们将看到如何编译和安装这个模块以从 Python 脚本中调用。

构建和安装扩展

The distutils package 使得以标准方式分发 Python 模块(纯 Python 模块和扩展模块)变得非常容易。模块以源代码形式分发，并通过通常称为的安装脚本构建和安装 setup.py 如下。

对于上述模块，你需要准备以下 setup.py 脚本：

from distutils.core import setup, Extension
setup(name='helloworld', version='1.0',  \
        ext_modules=[Extension('helloworld', ['hello.c'])])

现在，使用以下命令，它将执行所有需要的编译和链接步骤，使用正确的编译器和链接器命令和标志，并将生成的动态库复制到适当的目录中：

$ python setup.py install

在基于 Unix 的系统上，你很可能需要以 root 身份运行此命令才能获得写入站点包目录的权限。这在 Windows 上通常不是问题。

导入扩展

安装扩展后，你可以在 Python 脚本中导入并调用该扩展，如下所示：

#!/usr/bin/python
import helloworld

print helloworld.helloworld()

这将产生以下结果：

Hello, Python extensions!!

传递函数参数

由于你很可能希望定义接受参数的函数，因此你可以为你的 C 函数使用其他签名之一。例如，下面的函数，它接受一些参数，将被定义为：

static PyObject *module_func(PyObject *self, PyObject *args) {
    /* Parse args and do something interesting here. */
    Py_RETURN_NONE;
}

包含新函数条目的方法表如下所示：

static PyMethodDef module_methods[] = {
    { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
    { "func", module_func, METH_VARARGS, NULL },
    { NULL, NULL, 0, NULL }
};

你可以使用 API PyArg_ParseTuple 函数从传递给 C 函数的一个 PyObject 指针中提取参数。

PyArg_ParseTuple 的第一个参数是 args 参数。这是你将成为的对象 parsing .第二个参数是一个格式字符串，描述你希望它们出现的参数。每个参数由格式字符串中的一个或多个字符表示，如下所示。

static PyObject *module_func(PyObject *self, PyObject *args) {
    int i;
    double d;
    char *s;

    if (!PyArg_ParseTuple(args, "ids", &i, &d, &s)) {
        return NULL;
    }
   
    /* Do something interesting here. */
    Py_RETURN_NONE;
}

编译新版本的模块并导入它使你能够使用任意数量的任意类型的参数调用新函数：

module.func(1, s="three", d=2.0)
module.func(i=1, d=2.0, s="three")
module.func(s="three", d=2.0, i=1)

你可能会想出更多的变化。

The PyArg_ParseTuple Function

这是标准签名 PyArg_ParseTuple 功能：

int PyArg_ParseTuple(PyObject* tuple,char* format,...)

此函数返回 0 表示错误，不等于 0 的值表示成功。 tuple 是 PyObject*，它是 C 函数的第二个参数。这里 format 是一个描述强制和可选参数的 C 字符串。

这是格式代码的列表 PyArg_ParseTuple 功能：

Code	C type	Meaning
c	char	长度为 1 的 Python 字符串变为 C 字符。
d	double	Python float 变成了 C double。
f	float	Python 浮点数变成了 C 浮点数。
i	int	Python int 变成了 C int。
l	long	Python int 变成了 C long。
L	long long	Python int 变成 C long long
O	PyObject*	获取对 Python 参数的非 NULL 借用引用。
s	char*	没有嵌入 C char* 的空值的 Python 字符串。
s#	字符*+整数	任何 Python 字符串到 C 地址和长度。
t#	字符*+整数	只读单段缓冲区到 C 地址和长度。
u	Py_UNICODE*	Python Unicode 没有嵌入到 C 中的空值。
u#	Py_UNICODE*+int	任何 Python Unicode C 地址和长度。
w#	字符*+整数	读/写单段缓冲区到 C 地址和长度。
z	char*	与 s 一样，也接受 None(将 C char* 设置为 NULL)。
z#	字符*+整数	与 s# 一样，也接受 None(将 C char* 设置为 NULL)。
(...)	按照 ...	Python 序列被视为每个项目的一个参数。
\|		以下参数是可选的。
:		格式结束，后跟错误消息的函数名称。
;		格式结束，后跟整个错误消息文本。

返回值

Py_BuildValue 接受一个格式字符串，很像 PyArg_ParseTuple 做。不是传入正在构建的值的地址，而是传入实际值。下面是一个展示如何实现添加功能的示例：

static PyObject *foo_add(PyObject *self, PyObject *args) {
    int a;
    int b;

    if (!PyArg_ParseTuple(args, "ii", &a, &b)) {
        return NULL;
    }
    return Py_BuildValue("i", a + b);
}

如果用 Python 实现，它会是这样的：

def add(a, b):
    return (a + b)

你可以从函数中返回两个值，如下所示，这将在 Python 中使用列表进行捕获。

static PyObject *foo_add_subtract(PyObject *self, PyObject *args) {
    int a;
    int b;

    if (!PyArg_ParseTuple(args, "ii", &a, &b)) {
        return NULL;
    }
    return Py_BuildValue("ii", a + b, a - b);
}

如果用 Python 实现，它会是这样的：

def add_subtract(a, b):
    return (a + b, a - b)

The Py_BuildValue Function

这是标准签名 Py_BuildValue 功能：

PyObject* Py_BuildValue(char* format,...)

Here format 是一个 C 字符串，用于描述要构建的 Python 对象。以下论据 Py_BuildValue 是从中构建结果的 C 值。这 PyObject* 结果是一个新的参考。

下表列出了常用的代码字符串，其中零个或多个连接成字符串格式。

Code	C type	Meaning
c	char	一个 C 字符变成一个长度为 1 的 Python 字符串。
d	double	C double 变成 Python 浮点数。
f	float	C 浮点数变成了 Python 浮点数。
i	int	C int 变成 Python int。
l	long	C long 变成 Python int。
N	PyObject*	传递一个 Python 对象并窃取一个引用。
O	PyObject*	传递一个 Python 对象并像往常一样对其进行 INCREF。
O&	转换+无效*	任意转换
s	char*	C 以 0 结尾的 char* 到 Python 字符串，或 NULL 到 None。
s#	字符*+整数	C char* 和长度为 Python 字符串，或 NULL 为无。
u	Py_UNICODE*	C 范围的、以 null 结尾的字符串到 Python Unicode，或 NULL 到 None。
u#	Py_UNICODE*+int	C 范围的字符串和长度到 Python Unicode，或 NULL 到 None。
w#	字符*+整数	读/写单段缓冲区到 C 地址和长度。
z	char*	与 s 一样，也接受 None(将 C char* 设置为 NULL)。
z#	字符*+整数	与 s# 一样，也接受 None(将 C char* 设置为 NULL)。
(...)	按照 ...	从 C 值构建 Python 元组。
[...]	按照 ...	从 C 值构建 Python 列表。
{...}	按照 ...	从 C 值、交替键和值构建 Python 字典。

代码 {...} 从偶数个 C 值(交替键和值)构建字典。例如，Py_BuildValue("{issi}",23,"zig","zag",42) 返回类似于 Python 的 {23:'zig','zag':42} 的字典。

< 上一篇（Python GUI 编程 (Tkinter)）

Python教程

Python进阶