Python1.使用C或C++扩展Python

1.1. 一个简单的例子¶

让我们创建一个扩展模块 spam (Monty Python 粉丝最喜欢的食物...) 并且想要创建对应 C 库函数 system() 1 的 Python 接口。 这个函数接受一个以 null 结尾的字符串参数并返回一个整数。 我们希望可以在 Python 中以如下方式调用此函数:

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

首先创建一个 spammodule.c 文件。（传统上，如果一个模块叫 spam，则对应实现它的 C 文件叫 spammodule.c；如果这个模块名字非常长，比如 spammify，则这个模块的文件可以直接叫 spammify.c。）

文件中开始的两行是：

#define PY_SSIZE_T_CLEAN
#include<Python.h>

这会导入 Python API（如果你喜欢，你可以在这里添加描述模块目标和版权信息的注释)。

所有在 Python.h 中定义的用户可见的符号都具有 Py 或 PY 前缀，已在标准头文件中定义的那些除外。 考虑到便利性，也由于其在 Python 解释器中被广泛使用，"Python.h" 还包含了一些标准头文件: <stdio.h>，<string.h>，<errno.h> 和 <stdlib.h>。 如果后面的头文件在你的系统上不存在，它还会直接声明函数 malloc()，free() 和 realloc()。

下面添加C函数到扩展模块，当调用 spam.system(string) 时会做出响应，(我们稍后会看到调用)：

staticPyObject*
spam_system(PyObject*self,PyObject*args)
{
constchar*command;
intsts;
if(!PyArg_ParseTuple(args,"s",&command))
returnNULL;
sts=system(command);
returnPyLong_FromLong(sts);
}

有个直接翻译参数列表的方法(举个例子，单独的 "ls-l" )到要传递给C函数的参数。C函数总是有两个参数，通常名字是 self 和 args 。

对模块级函数， self 参数指向模块对象；对于方法则指向对象实例。

args 参数是指向一个 Python 的 tuple 对象的指针，其中包含参数。 每个 tuple 项对应一个调用参数。 这些参数也全都是 Python 对象 --- 要在我们的 C 函数中使用它们就需要先将其转换为 C 值。 Python API 中的函数 PyArg_ParseTuple() 会检查参数类型并将其转换为 C 值。 它使用模板字符串确定需要的参数类型以及存储被转换的值的 C 变量类型。 细节将稍后说明。

PyArg_ParseTuple() 在所有参数都有正确类型且组成部分按顺序放在传递进来的地址里时，返回真(非零)。其在传入无效参数时返回假(零)。在后续例子里，还会抛出特定异常，使得调用的函数可以理解返回 NULL (也就是例子里所见)。

1.2. 关于错误和异常¶

在 Python 解释器中有一个重要的惯例：当一个函数出错时，它应当设置异常条件并返回错误值（通常为 NULL 指针）。 异常存储于解释器内部的静态全局变量中；如此变量为 NULL 表示未发生异常。 还有第二个全局变量用于保存异常的“关联值”（即 raise 的第二个参数）。 第三个变量包含 Python 代码产生错误情况下的栈回溯信息。 这三个变量是 Python 中 sys.exc_info() 的结果在 C 中的对应物（请参阅 Python 库参考的 sys 模块部分）。 了解它们对于理解错误的传递方式是非常重要的。

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

最常用的就是 PyErr_SetString()。 其参数是异常对象和 C 字符串。 异常对象一般是像 PyExc_ZeroDivisionError 这样的预定义对象。 C 字符串指明异常原因，并被转换为一个 Python 字符串对象存储为异常的“关联值”。

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

你可以通过 PyErr_Occurred() 在不造成破坏的情况下检测是否设置了异常。 这将返回当前异常对象，或者如果未发生异常则返回 NULL。 你通常不需要调用 PyErr_Occurred() 来查看函数调用中是否发生了错误，因为你应该能从返回值中看出来。

当一个函数 f 调用另一个函数 g 时检测到后者出错了，f 应当自己返回一个错误值 (通常为 NULL 或 -1)。 它 不应该 调用某个 PyErr_*() 函数 --- 这类函数已经被 g 调用过了。 f 的调用者随后也应当返回一个错误来提示 它的 调用者，同样 不应该 调用 PyErr_*()，依此类推 --- 错误的最详细原因已经由首先检测到它的函数报告了。 一旦这个错误到达 Python 解释器的主循环，它会中止当前执行的 Python 代码并尝试找出由 Python 程序员所指定的异常处理程序。

（在某些情况下，当模块确实能够通过调用其它 PyErr_*() 函数给出更加详细的错误消息，并且在这些情况是可以这样做的。 但是按照一般规则，这是不必要的，并可能导致有关错误原因的信息丢失：大多数操作会由于种种原因而失败。）

想要忽略由一个失败的函数调用所设置的异常，异常条件必须通过调用 PyErr_Clear() 显式地被清除。 C 代码应当调用 PyErr_Clear() 的唯一情况是如果它不想将错误传给解释器而是想完全由自己来处理它（可能是尝试其他方法，或是假装没有出错）。

每次失败的 malloc() 调用必须转换为一个异常。 malloc() (或 realloc() )的直接调用者必须调用 PyErr_NoMemory() 来返回错误来提示。所有对象创建函数(例如 PyLong_FromLong() )已经这么做了，所以这个提示仅用于直接调用 malloc() 的情况。

还要注意的是，除了 PyArg_ParseTuple() 等重要的例外，返回整数状态码的函数通常都是返回正值或零来表示成功，而以 -1 表示失败，如同 Unix 系统调用一样。

最后，当你返回一个错误指示器时要注意清理垃圾（通过为你已经创建的对象执行 Py_XDECREF() 或 Py_DECREF() 调用）！

选择引发哪个异常完全取决于你的喜好。 所有内置的 Python 异常都有对应的预声明 C 对象，例如 PyExc_ZeroDivisionError，你可以直接使用它们。 当然，你应当明智地选择异常 --- 不要使用 PyExc_TypeError 来表示一个文件无法被打开 (那大概应该用 PyExc_IOError)。 如果参数列表有问题，PyArg_ParseTuple() 函数通常会引发 PyExc_TypeError。 如果你想要一个参数的值必须处于特定范围之内或必须满足其他条件，则适宜使用 PyExc_ValueError。

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

staticPyObject*SpamError;

并且在你的模块的初始化函数 (PyInit_spam()) 中使用一个异常对象来初始化:

PyMODINIT_FUNC
PyInit_spam(void)
{
PyObject*m;
m=PyModule_Create(&spammodule);
if(m==NULL)
returnNULL;
SpamError=PyErr_NewException("spam.error",NULL,NULL);
Py_XINCREF(SpamError);
if(PyModule_AddObject(m,"error",SpamError)<0){
Py_XDECREF(SpamError);
Py_CLEAR(SpamError);
Py_DECREF(m);
returnNULL;
}
returnm;
}

注意异常对象的Python名字是 spam.error 。而 PyErr_NewException() 函数可以创建一个类，其基类为 Exception (除非是另一个类传入以替换 NULL )， 细节参见 内置异常 。

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

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

spam.error 异常可以在扩展模块中抛出，通过 PyErr_SetString() 函数调用，如下：

staticPyObject*
spam_system(PyObject*self,PyObject*args)
{
constchar*command;
intsts;
if(!PyArg_ParseTuple(args,"s",&command))
returnNULL;
sts=system(command);
if(sts<0){
PyErr_SetString(SpamError,"System command failed");
returnNULL;
}
returnPyLong_FromLong(sts);
}

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

sts=system(command);

returnPyLong_FromLong(sts);

Py_INCREF(Py_None);
returnPy_None;

staticPyMethodDefSpamMethods[]={
...
{"system",spam_system,METH_VARARGS,
"Execute a shell command."},
...
{NULL,NULL,0,NULL}/* Sentinel */
};

staticstructPyModuleDefspammodule={
PyModuleDef_HEAD_INIT,
"spam",/* name of module */
spam_doc,/* module documentation, may be NULL */
-1,/* size of per-interpreter state of the module,
                 or -1 if the module keeps state in global variables. */
SpamMethods
};

PyMODINIT_FUNC
PyInit_spam(void)
{
returnPyModule_Create(&spammodule);
}

int
main(intargc,char*argv[])
{
wchar_t*program=Py_DecodeLocale(argv[0],NULL);
if(program==NULL){
fprintf(stderr,"Fatal error: cannot decode argv[0]\n");
exit(1);
}
/* Add a built-in module, before Py_Initialize */
PyImport_AppendInittab("spam",PyInit_spam);
/* Pass argv[0] to the Python interpreter */
Py_SetProgramName(program);
/* Initialize the Python interpreter.  Required. */
Py_Initialize();
/* Optionally import the module; alternatively,
       import can be deferred until the embedded script
       imports it. */
PyImport_ImportModule("spam");
...
PyMem_RawFree(program);
return0;
}

spam spammodule.o

spam spammodule.o -lX11

staticPyObject*my_callback=NULL;
staticPyObject*
my_set_callback(PyObject*dummy,PyObject*args)
{
PyObject*result=NULL;
PyObject*temp;
if(PyArg_ParseTuple(args,"O:set_callback",&temp)){
if(!PyCallable_Check(temp)){
PyErr_SetString(PyExc_TypeError,"parameter must be callable");
returnNULL;
}
Py_XINCREF(temp);/* Add a reference to new callback */
Py_XDECREF(my_callback);/* Dispose of previous callback */
my_callback=temp;/* Remember new callback */
/* Boilerplate to return "None" */
Py_INCREF(Py_None);
result=Py_None;
}
returnresult;
}

intarg;
PyObject*arglist;
PyObject*result;
...
arg=123;
...
/* Time to call the callback */
arglist=Py_BuildValue("(i)",arg);
result=PyObject_CallObject(my_callback,arglist);
Py_DECREF(arglist);

if(result==NULL)
returnNULL;/* Pass error back */
...useresult...
Py_DECREF(result);

PyObject*arglist;
...
arglist=Py_BuildValue("(l)",eventcode);
result=PyObject_CallObject(my_callback,arglist);
Py_DECREF(arglist);
if(result==NULL)
returnNULL;/* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);

PyObject*dict;
...
dict=Py_BuildValue("{s:i}","name",val);
result=PyObject_Call(my_callback,NULL,dict);
Py_DECREF(dict);
if(result==NULL)
returnNULL;/* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);

intPyArg_ParseTuple(PyObject*arg,constchar*format,...);

#define PY_SSIZE_T_CLEAN  /* Make "s#" use Py_ssize_t rather than int. */
#include<Python.h>

intok;
inti,j;
longk,l;
constchar*s;
Py_ssize_tsize;
ok=PyArg_ParseTuple(args,"");/* No arguments */
/* Python call: f() */

ok=PyArg_ParseTuple(args,"s",&s);/* A string */
/* Possible Python call: f('whoops!') */

ok=PyArg_ParseTuple(args,"lls",&k,&l,&s);/* Two longs and a string */
/* Possible Python call: f(1, 2, 'three') */

ok=PyArg_ParseTuple(args,"(ii)s#",&i,&j,&s,&size);
/* A pair of ints and a string, whose size is also returned */
/* Possible Python call: f((1, 2), 'three') */

{
constchar*file;
constchar*mode="r";
intbufsize=0;
ok=PyArg_ParseTuple(args,"s|si",&file,&mode,&bufsize);
/* A string, and optionally another string and an integer */
/* Possible Python calls:
       f('spam')
       f('spam', 'w')
       f('spam', 'wb', 100000) */
}

{
intleft,top,right,bottom,h,v;
ok=PyArg_ParseTuple(args,"((ii)(ii))(ii)",
&left,&top,&right,&bottom,&h,&v);
/* A rectangle and a point */
/* Possible Python call:
       f(((0, 0), (400, 300)), (10, 10)) */
}

{
Py_complexc;
ok=PyArg_ParseTuple(args,"D:myfunction",&c);
/* a complex, also providing a function name for errors */
/* Possible Python call: myfunction(1+2j) */
}

intPyArg_ParseTupleAndKeywords(PyObject*arg,PyObject*kwdict,
constchar*format,char*kwlist[],...);

#define PY_SSIZE_T_CLEAN  /* Make "s#" use Py_ssize_t rather than int. */
#include<Python.h>
staticPyObject*
keywdarg_parrot(PyObject*self,PyObject*args,PyObject*keywds)
{
intvoltage;
constchar*state="a stiff";
constchar*action="voom";
constchar*type="Norwegian Blue";
staticchar*kwlist[]={"voltage","state","action","type",NULL};
if(!PyArg_ParseTupleAndKeywords(args,keywds,"i|sss",kwlist,
&voltage,&state,&action,&type))
returnNULL;
printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
action,voltage);
printf("-- Lovely plumage, the %s -- It's %s!\n",type,state);
Py_RETURN_NONE;
}
staticPyMethodDefkeywdarg_methods[]={
/* The cast of the function is necessary since PyCFunction values
     * only take two PyObject* parameters, and keywdarg_parrot() takes
     * three.
     */
{"parrot",(PyCFunction)keywdarg_parrot,METH_VARARGS|METH_KEYWORDS,
"Print a lovely skit to standard output."},
{NULL,NULL,0,NULL}/* sentinel */
};
staticstructPyModuleDefkeywdargmodule={
PyModuleDef_HEAD_INIT,
"keywdarg",
NULL,
-1,
keywdarg_methods
};
PyMODINIT_FUNC
PyInit_keywdarg(void)
{
returnPyModule_Create(&keywdargmodule);
}

PyObject*Py_BuildValue(constchar*format,...);

Py_BuildValue("")                        None
Py_BuildValue("i", 123)                  123
Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
Py_BuildValue("s", "hello")              'hello'
Py_BuildValue("y", "hello")              b'hello'
Py_BuildValue("ss", "hello", "world")    ('hello', 'world')
Py_BuildValue("s#", "hello", 4)          'hell'
Py_BuildValue("y#", "hello", 4)          b'hell'
Py_BuildValue("()")                      ()
Py_BuildValue("(i)", 123)                (123,)
Py_BuildValue("(ii)", 123, 456)          (123, 456)
Py_BuildValue("(i,i)", 123, 456)         (123, 456)
Py_BuildValue("[i,i]", 123, 456)         [123, 456]
Py_BuildValue("{s:i,s:i}",
              "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
Py_BuildValue("((ii)(ii)) (ii)",
              1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))

void
bug(PyObject*list)
{
PyObject*item=PyList_GetItem(list,0);
PyList_SetItem(list,1,PyLong_FromLong(0L));
PyObject_Print(item,stdout,0);/* BUG! */
}

void
no_bug(PyObject*list)
{
PyObject*item=PyList_GetItem(list,0);
Py_INCREF(item);
PyList_SetItem(list,1,PyLong_FromLong(0L));
PyObject_Print(item,stdout,0);
Py_DECREF(item);
}

void
bug(PyObject*list)
{
PyObject*item=PyList_GetItem(list,0);
Py_BEGIN_ALLOW_THREADS
...someblockingI/Ocall...
Py_END_ALLOW_THREADS
PyObject_Print(item,stdout,0);/* BUG! */
}

modulename.attributename

staticint
PySpam_System(constchar*command)
{
returnsystem(command);
}

staticPyObject*
spam_system(PyObject*self,PyObject*args)
{
constchar*command;
intsts;
if(!PyArg_ParseTuple(args,"s",&command))
returnNULL;
sts=PySpam_System(command);
returnPyLong_FromLong(sts);
}

#include<Python.h>

#define SPAM_MODULE
#include"spammodule.h"

PyMODINIT_FUNC
PyInit_spam(void)
{
PyObject*m;
staticvoid*PySpam_API[PySpam_API_pointers];
PyObject*c_api_object;
m=PyModule_Create(&spammodule);
if(m==NULL)
returnNULL;
/* Initialize the C API pointer array */
PySpam_API[PySpam_System_NUM]=(void*)PySpam_System;
/* Create a Capsule containing the API pointer array's address */
c_api_object=PyCapsule_New((void*)PySpam_API,"spam._C_API",NULL);
if(PyModule_AddObject(m,"_C_API",c_api_object)<0){
Py_XDECREF(c_api_object);
Py_DECREF(m);
returnNULL;
}
returnm;
}

#ifndef Py_SPAMMODULE_H
#define Py_SPAMMODULE_H
#ifdef __cplusplus
extern"C"{
#endif
/* Header file for spammodule */
/* C API functions */
#define PySpam_System_NUM 0
#define PySpam_System_RETURN int
#define PySpam_System_PROTO (const char *command)
/* Total number of C API pointers */
#define PySpam_API_pointers 1
#ifdef SPAM_MODULE
/* This section is used when compiling spammodule.c */
staticPySpam_System_RETURNPySpam_SystemPySpam_System_PROTO;
#else
/* This section is used in modules that use spammodule's API */
staticvoid**PySpam_API;
#define PySpam_System \
 (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])
/* Return -1 on error, 0 on success.
 * PyCapsule_Import will set an exception if there's an error.
 */
staticint
import_spam(void)
{
PySpam_API=(void**)PyCapsule_Import("spam._C_API",0);
return(PySpam_API!=NULL)?0:-1;
}
#endif
#ifdef __cplusplus
}
#endif
#endif /* !defined(Py_SPAMMODULE_H) */

PyMODINIT_FUNC
PyInit_client(void)
{
PyObject*m;
m=PyModule_Create(&clientmodule);
if(m==NULL)
returnNULL;
if(import_spam()<0)
returnNULL;
/* additional initialization can happen here */
returnm;
}