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 函数的名称可以是你喜欢的任何名称，因为它们永远不会在扩展模块之外看到。它们被定义为 static 函数。

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


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

这是 module 模块中一个名为 func 的 Python 函数。您将把指向 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 按位 OR 运算此标志。
    • 这也可以具有 METH_NOARGS 值，表示您不想接受任何参数。
  • mml_doc − 这是函数的文档字符串，如果不这样做，则可能为 NULL 想写一个。

此表需要以 sentinel 终止，该 sentinel 由相应成员的 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 值。将上面的代码保存在 你好.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 是 PyObject*，它是 C 函数的第二个参数。这里的 format 是一个 C 字符串，用于描述强制和可选参数。

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

Code C type 意义
c char 长度为 1 的 Python 字符串变为 C 字符。
d double Python 浮点数变为 C 双精度。
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* 中没有嵌入 null 的 Python 字符串。
s# char*+int 任何 Python 字符串到 C 地址和长度。
t# char*+int 只读单段缓冲区到 C 地址和长度。
u Py_UNICODE* C 中没有嵌入 null 的 Python Unicode。
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）。
(...) as per ... Python 序列被视为每个项目的一个参数。
|   以下参数是可选的。
:   格式为 end，后跟错误消息的函数名称。
;   格式为 end，后跟整个错误消息文本。

返回值

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* 结果是一个新引用。

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

Code C type 意义
c char C char 变为长度为 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& convert+void* 任意转换
s char* C 以 0 结尾的 char* 更改为 Python 字符串，或 NULL 更改为 None。
s# char*+int C char* 和 length 设置为 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）。
(...) as per ... 从 C 值构建 Python 元组。
[...] as per ... 从 C 值构建 Python 列表。
{...} as per ... 从 C 值构建 Python 字典，交替键和值。

代码 {...} 从偶数个 C 值（交替键和值）构建字典。

例如，Py_BuildValue（“{issi}”，23，“zig”，“zag”，42） 返回类似于 Python 的 {23：'zig'，'zag'：42} 的字典

打印本页
上一页
下一页