Python 3-使用C进行扩展编程

📌 相关文章

📜 Python 3-使用C进行扩展编程

📅 最后修改于: 2020-12-23 05:06:53 🧑 作者: Mango

您可以使用C，C＆plus;或Java等任何编译语言编写的任何代码都可以集成或导入到另一个Python脚本中。此代码被视为“扩展名”。

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

编写扩展的先决条件

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

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

此外，假定您具有C或C＆plus;＆plus;的良好知识。使用C编程编写任何Python扩展。

首先看一下Python扩展

首先看一下Python扩展模块，您需要将代码分为四部分-

头文件Python.h 。
您想作为模块接口公开的C函数。
一张表，映射了您作为Python开发人员的函数名称，将其视为扩展模块中的C函数。
初始化函数。

头文件Python.h

您需要在C源文件中包含Python.h头文件，该文件使您可以访问内部Python API，该内部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函数。如果您不希望函数返回值，请返回C的Python None值。 Python标头定义了一个宏Py_RETURN_NONE，它可以为我们执行此操作。

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

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

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

这是模块模块内部的一个称为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进行按位或运算。
- 它也可以具有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 ，其中Module是模块的名称。

需要从将要构建的库中导出初始化函数。 Python标头定义了PyMODINIT_FUNC，以包括针对我们正在编译的特定环境而发生的适当提示。您需要做的就是在定义函数时使用它。

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

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

这是Py_InitModule3函数的描述-

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

放在一起，看起来像下面的样子：

#include 

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 

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.py as的安装脚本来构建和安装。

对于上述模块，您需要准备以下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脚本中导入并调用该扩展程序-

例

#!/usr/bin/python3
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函数

这是PyArg_ParseTuple函数的标准签名-

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

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

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

Code	C type	Meaning
c	char	A Python string of length 1 becomes a C char.
d	double	A Python float becomes a C double.
f	float	A Python float becomes a C float.
i	int	A Python int becomes a C int.
l	long	A Python int becomes a C long.
L	long long	A Python int becomes a C long long
O	PyObject*	Gets non-NULL borrowed reference to Python argument.
s	char*	Python string without embedded nulls to C char*.
s#	char*+int	Any Python string to C address and length.
t#	char*+int	Read-only single-segment buffer to C address and length.
u	Py_UNICODE*	Python Unicode without embedded nulls to C.
u#	Py_UNICODE*+int	Any Python Unicode C address and length.
w#	char*+int	Read/write single-segment buffer to C address and length.
z	char*	Like s, also accepts None (sets C char* to NULL).
z#	char*+int	Like s#, also accepts None (sets C char* to NULL).
(...)	as per ...	A Python sequence is treated as one argument per item.
\|		The following arguments are optional.
:		Format end, followed by function name for error messages.
;		Format end, followed by entire error message text.

返回值

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)

Py_BuildValue函数

这是Py_BuildValue函数的标准签名-

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

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

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

Code	C type	Meaning
c	char	A C char becomes a Python string of length 1.
d	double	A C double becomes a Python float.
f	float	A C float becomes a Python float.
i	int	A C int becomes a Python int.
l	long	A C long becomes a Python int.
N	PyObject*	Passes a Python object and steals a reference.
O	PyObject*	Passes a Python object and INCREFs it as normal.
O&	convert+void*	Arbitrary conversion
s	char*	C 0-terminated char* to Python string, or NULL to None.
s#	char*+int	C char* and length to Python string, or NULL to None.
u	Py_UNICODE*	C-wide, null-terminated string to Python Unicode, or NULL to None.
u#	Py_UNICODE*+int	C-wide string and length to Python Unicode, or NULL to None.
w#	char*+int	Read/write single-segment buffer to C address and length.
z	char*	Like s, also accepts None (sets C char* to NULL).
z#	char*+int	Like s#, also accepts None (sets C char* to NULL).
(...)	as per ...	Builds Python tuple from C values.
[...]	as per ...	Builds Python list from C values.
{...}	as per ...	Builds Python dictionary from C values, alternating keys and values.

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