Python - 扩展进阶

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

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

编写扩展的先决条件

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

在 Unix 机器上，这通常需要安装特定于开发人员的软件包。
Windows 用户在使用二进制 Python 安装程序时，会将这些头文件作为软件包的一部分获得。

此外，假设您精通 C 或 C++，可以使用 C 编程编写任何 Python 扩展。

首先了解 Python 扩展

要首次了解 Python 扩展模块，您需要将代码分成四个部分：

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

头文件 Python.h

您需要在 C 源文件中包含 Python.h 头文件，这使您可以访问用于将模块挂接到解释器的内部 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 对象。Python 中没有像 C 中那样的 void 函数。如果您不希望函数返回值，则返回 Python 的None值的 C 等价物。Python 头文件定义了一个宏 Py_RETURN_NONE，它为我们执行此操作。

C 函数的名称可以是您喜欢的任何名称，因为它们永远不会在扩展模块之外可见。它们被定义为静态函数。

您的 C 函数通常通过组合 Python 模块和函数名称来命名，如下所示：

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

这是一个名为 func 的 Python 函数，位于模块 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 的值，表示您不想接受任何参数。
mml_doc − 这是函数的文档字符串，如果您不想编写，可以为 NULL。

此表需要以哨兵结束，哨兵由相应成员的 NULL 和 0 值组成。

示例

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

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

初始化函数

扩展模块的最后一部分是初始化函数。当加载模块时，Python 解释器会调用此函数。要求函数名为 initModule，其中 Module 是模块的名称。

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

您的 C 初始化函数通常具有以下总体结构：

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

以下是 Py_InitModule3 函数的描述：

func − 这是要导出的函数。
module_methods − 这是上面定义的映射表名称。
docstring − 这是您想要在扩展中提供的注释。

将所有这些放在一起，看起来如下所示：

#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!");
}

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

构建和安装扩展

distutils 包使以标准方式分发 Python 模块（纯 Python 模块和扩展模块）变得非常容易。模块以源代码形式分发，通过通常称为 setup.pyas 的安装脚本进行构建和安装。

对于上述模块，您需要准备以下 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 身份运行此命令才能有权写入 site-packages 目录。这在 Windows 上通常不是问题。

导入扩展

安装扩展后，您将能够在 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 参数。这是您将要解析的对象。第二个参数是格式字符串，描述了您期望参数出现的格式。每个参数在格式字符串中由一个或多个字符表示，如下所示。

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)

您可能还可以想出更多变化。

PyArg_ParseTuple 函数

re 是PyArg_ParseTuple 函数的标准签名：

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

此函数对于错误返回 0，对于成功返回非 0 值。Tuple 是作为 C 函数第二个参数的 PyObject*。这里的 format 是一个 C 字符串，描述了必选和可选参数。

以下是PyArg_ParseTuple 函数的格式代码列表：

代码	C 类型	含义
c	char	长度为 1 的 Python 字符串变为 C char。
d	double	Python float 变为 C double。
f	float	Python float 变为 C float。
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*	没有嵌入空字符的 Python 字符串到 C char*。
s#	char*+int	任何 Python 字符串到 C 地址和长度。
t#	char*+int	只读单段缓冲区到 C 地址和长度。
u	Py_UNICODE*	没有嵌入空字符的 Python Unicode 到 C。
u#	Py_UNICODE*+int	任何 Python Unicode C 地址和长度。
w#	char*+int	读/写单段缓冲区到 C 地址和长度。
z	char*	类似于 s，也接受 None（将 C char* 设置为 NULL）。
z#	char*+int	类似于 s#，也接受 None（将 C char* 设置为 NULL）。
(...)	根据 ...	Python 序列被视为每个项目一个参数。
\|		以下参数是可选的。
:		格式结束，后跟错误消息的函数名称。
;		格式结束，后跟完整的错误消息文本。

返回值

Py_BuildValue 使用与 PyArg_ParseTuple 非常相似的格式字符串。您不是传入要构建的值的地址，而是传入实际的值。以下是一个示例，展示了如何实现 add 函数。

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)

Py_BuildValue 函数

以下是Py_BuildValue 函数的标准签名：

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

这里的 format 是一个 C 字符串，描述了要构建的 Python 对象。Py_BuildValue 的以下参数是构建结果的 C 值。PyObject* 结果是一个新引用。

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

代码	C 类型	含义
c	char	C char 变为长度为 1 的 Python 字符串。
d	double	C double 变为 Python float。
f	float	C float 变为 Python float。
i	int	C int 变为 Python int
l	long	C long 变为 Python int
N	PyObject*	传递 Python 对象并窃取引用。
O	PyObject*	传递 Python 对象并按正常方式 INCREF。
O&	convert+void*	任意转换
s	char*	C 以 0 结尾的 char* 到 Python 字符串，或 NULL 到 None。
s#	char*+int	C char* 和长度到 Python 字符串，或 NULL 到 None。
u	Py_UNICODE*	C 宽的、以 null 结尾的字符串到 Python Unicode，或 NULL 到 None。
u#	Py_UNICODE*+int	C 宽字符串和长度到 Python Unicode，或 NULL 到 None。
w#	char*+int	读/写单段缓冲区到 C 地址和长度。
z	char*	类似于 s，也接受 None（将 C char* 设置为 NULL）。
z#	char*+int	类似于 s#，也接受 None（将 C char* 设置为 NULL）。
(...)	根据 ...	从 C 值构建 Python 元组。
[...]	根据 ...	从 C 值构建 Python 列表。
{...}	根据 ...	从 C 值构建 Python 字典，交替键和值。

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

打印页面