使用C/C++扩展Python

来源： 作者： 时间：2007-12-11 Tag： 点击：

翻译:	gashero

如果你会用C，实现Python嵌入模块很简单。利用扩展模块可做很多Python不方便做的事情，他们可以直接调用C库和系统调用。

为了支持扩展，Python API定义了一系列函数、宏和变量，提供了对Python运行时系统的访问支持。Python的C API由C源码组成，并包含 “Python.h” 头文件。

编写扩展模块与你的系统相关，下面会详解。

1 一个简单的例子

下面的例子创建一个叫做 “spam” 的扩展模块，调用C库函数 system() 。这个函数输入一个NULL结尾的字符串并返回整数，可供Python调用方式如下:

>>> import spam
>>> status=spam.system("ls -l")

一个C扩展模块的文件名可以直接是模块名.c 或者是模块名module.c 。第一行应该导入头文件:

#include <Python.h>

这会导入Python API。

Warning

因为Python含有一些预处理定义，所以你必须在所有非标准头文件导入之前导入Python.h 。

Python.h中所有用户可见的符号都有 Py 或 PY 的前缀，除非定义在标准头文件中。为了方便 “Python.h” 也包含了一些常用的标准头文件，包括<stdio.h>，<string.h>，<errno.h>，< stdlib.h>。如果你的系统没有后面的头文件，则会直接定义函数 malloc() 、 free() 和 realloc() 。

下面添加C代码到扩展模块，当调用 “spam.system(string)” 时会做出响应:

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 Py_BuildValue("i",sts);
}

调用方的Python只有一个命令参数字符串传递到C函数。C函数总是有两个参数，按照惯例分别叫做 self 和 args 。

self 参数仅用于用C实现内置方法而不是函数。本例中， self 总是为NULL，因为我们定义的是个函数，不是方法。这一切都是相同的，所以解释器也就不需要刻意区分两种不同的C函数。

args 参数是一个指向Python的tuple对象的指针，包含参数。每个tuple子项对应一个调用参数。这些参数也全都是Python对象，所以需要先转换成C值。函数 PyArg_ParseTuple() 检查参数类型并转换成C值。它使用模板字符串检测需要的参数类型。

PyArg_ParseTuple() 正常返回非零，并已经按照提供的地址存入了各个变量值。如果出错(零)则应该让函数返回NULL以通知解释器出错。

2 关于错误和异常

一个常见惯例是，函数发生错误时，应该设置一个异常环境并返回错误值(NULL)。异常存储在解释器静态全局变量中，如果为NULL，则没有发生异常。异常的第一个参数也需要保存在静态全局变量中，也就是raise的第二个参数。第三个变量包含栈回溯信息。这三个变量等同于Python变量 sys.exc_type 、 sys.exc_value 、 sys.exc_traceback 。这对找到错误是很必要的。

Python API中定义了一些函数来设置这些变量。

最常用的就是 PyErr_SetString() 。参数是异常对象和C字符串。异常对象一般由像 PyExc_ZeroDivisionError 这样的对象来预定义。C字符串指明异常原因，并最终存储在异常的第一个参数里面。

另一个有用的函数是 PyErr_SetFromErrno() ，仅接受一个异常对象，异常描述包含在全局变量 errno 中。最通用的函数还是 PyErr_SetObject() ，包含两个参数，分别为异常对象和异常描述。你不需要使用 Py_INCREF() 来增加传递到其他函数的参数对象的引用计数。

你可以通过 PyErr_Occurred() 获知当前异常，返回当前异常对象，如果确实没有则为NULL。一般来说，你在调用函数时不需要调用 PyErr_Occurred() 检查是否发生了异常，你可以直接检查返回值。

如果调用更下层函数时出错了，那么本函数返回NULL表示错误，并且整个调用栈中只要有一处调用 PyErr_*() 函数设置异常就可以。一般来说，首先发现错误的函数应该设置异常。一旦这个错误到达了Python解释器的主循环，则会中断当前执行代码并追究异常。

有一种情况下，模块可能依靠其他 PyErr_*() 函数给出更加详细的错误信息，并且是正确的。但是按照一般规则，这并不重要，很多操作都会因为种种原因而挂掉。

想要忽略这些函数设置的异常，异常情况必须明确的使用 PyErr_Clear() 来清除。只有在C代码想要自己处理异常而不是传给解释器时才这么做。

每次失败的 malloc() 调用必须抛出一个异常，直接调用 malloc() 或 realloc() 的地方要调用 PyErr_NoMemory() 并返回错误。所有创建对象的函数都已经实现了这个异常的抛出，所以这是每个分配内存都要做的。

还要注意的是 PyArg_ParseTuple() 系列函数的异常，返回一个整数状态码是有效的，0是成功，-1是失败，有如Unix系统调用。

最后，小心垃圾情理，也就是 Py_XDECREF() 和 Py_DECREF() 的调用，会返回的异常。

选择抛出哪个异常完全是你的个人爱好了。有一系列的C对象代表了内置Python异常，例如 PyExc_ZeroDivisionError ，你可以直接使用。当然，你可能选择更合适的异常，不过别使用 PyExc_TypeError 告知文件打开失败(有个更合适的 PyExc_IOError )。如果参数列表有误， PyArg_ParseTuple() 通常会抛出 PyExc_TypeError 。如果参数值域有误， PyExc_ValueError 更合适一些。

你也可以为你的模块定义一个唯一的新异常。需要在文件前部声明一个静态对象变量，如:

static PyObject* SpamError;

然后在模块初始化函数(initspam())里面初始化它，并省却了处理:

PyMODINIT_FUNC
initspam(void) {
    PyObject* m;
    m=Py_InitModule("spam",SpamMethods);
    if (m==NULL)
        return NULL;
    SpamError=PyErr_NewException("spam.error",NULL,NULL);
    Py_INCREF(SpamError);
    PyModule_AddObject(m,"error",SpamError);
}

注意实际的Python异常名字是 spam.error 。 PyErr_NewException() 函数使用Exception为基类创建一个类(除非是使用另外一个类替代NULL)。

同样注意的是创建类保存了SpamError的一个引用，这是有意的。为了防止被垃圾回收掉，否则SpamError随时会成为野指针。

一会讨论 PyMODINIT_FUNC 作为函数返回类型的用法。

3 回到例子

回到前面的例子，你应该明白下面的代码:

if (!PyArg_ParseTuple(args,"s",&command))
    return NULL;

就是为了报告解释器一个异常。如果执行正常则变量会拷贝到本地，后面的变量都应该以指针的方式提供，以方便设置变量。本例中的command会被声明为 “const char* command” 。

下一个语句使用UNIX系统函数system()，传递给他的参数是刚才从 PyArg_ParseTuple() 取出的:

sts=system(command);

我们的 spam.system() 函数必须返回一个PY对象，这可以通过 Py_BuildValue() 来完成，其形式与 PyArg_ParseTuple() 很像，获取格式字符串和C值，并返回新的Python对象:

return Py_BuildValue("i",sts);

在这种情况下，会返回一个整数对象，这个对象会在Python堆里面管理。

如果你的C函数没有有用的返回值，则必须返回None。你可以用 Py_RETUN_NONE 宏来完成:

Py_INCREF(Py_None);
return Py_None;

Py_None 是一个C名字指定Python对象None。这是一个真正的PY对象，而不是NULL指针。

[收藏] [推荐] [评论] [打印] [关闭]

顶一下

上一篇：Python的运算符
下一篇：文件中文编码之间的转换

最新评论共有 4 位网友发表了评论

查看所有评论

发表评论

栏目列表