gashero

扩展和嵌入Python解释器 Extending and Embedding the Python Interpreter

2007年开始使用Python与C的交互编程，那时分享了一篇《使用C/C++扩展Python》 http://gashero.yeax.com/?p=38 。8年过去了，很多技术时过境迁，但Python的扩展和嵌入技术仍然有很强大的生命力。尤其是国内外开始广泛的将Python引入科学计算、计算机视觉、深度学习等领域后。对Python的灵活性以及提高性能有着更高的需求。所以再次把我翻译的最新版本的文档分享出来。总计接近7万字(unicode字符)，已经将原文档接近于翻译完成，剩余部分大多不是必需功能。

扩展和嵌入Python解释器 Extending and Embedding the Python Interpreter

作者:	Guido van Rossum
翻译:	gashero
版本:	Release 2.4.4 2006-10-18
日期:	2007-08-14
地址:	http://docs.python.org/2.5/ext/ext.html

1 使用C/C++扩展Python

1.1 一个简单的例子
1.2 关于错误和异常
1.3 回到例子
1.4 模块方法表和初始化函数
1.5 编译和连接
1.6 在C中调用Python函数
1.7 解析传给扩展模块函数的参数
1.8 解析传给扩展模块函数的关键字参数
1.9 构造任意值
1.10 引用计数

1.10.1 Python中的引用计数
1.10.2 拥有规则
1.10.3 危险的薄冰
1.10.4 NULL指针

1.11 使用C++编写扩展
1.12 提供给其他模块以C API

2 定义新类型

2.1 基础

2.1.1 给例子添加数据和方法
2.1.2 为数据属性提供控制
2.1.3 支持循环引用垃圾收集
2.1.4 继承其他类型

2.2 类型方法

2.2.1 销毁与释放
2.2.2 对象表达
2.2.3 属性管理
2.2.4 对象比较
2.2.5 抽象协议支持
2.2.6 弱引用支持
2.2.7 更多建议

3 使用distutils构建扩展

3.1 发布你的扩展模块

4 在Windows构建扩展

4.1 照着菜谱走猫步(a cookbook approach)
4.2 Unix与Windows的不同
4.3 实践中使用DLL

5 嵌入Python到其他应用

5.1 高层次嵌入
5.2 超越高层嵌入：预览
5.3 纯扩展
5.4 扩展嵌入的Python
5.5 在C++中嵌入Python
5.6 链接必备条件

1 使用C/C++扩展Python

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

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

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

1.1 一个简单的例子

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

>>> import spam

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

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

#include

这会导入Python API。

Warning

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

Python.h中所有用户可见的符号都有 Py 或 PY 的前缀，除非定义在标准头文件中。为了方便 "Python.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以通知解释器出错。

1.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() 系列函数的异常，(by gashero)返回一个整数状态码是有效的，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 作为函数返回类型的用法。

1.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指针。

1.4 模块方法表和初始化函数

把函数声明为可以被Python调用，需要先定义一个方法表:

static PyMethodDef SpamMethods[]= {

...

{"system",spam_system,METH_VARARGS,

"Execute a shell command."},

...

{NULL,NULL,0,NULL} /*必须的结束符 by gashero*/

};

注意第三个参数 METH_VARARGS ，这个标志指定会使用C的调用惯例。可选值有 METH_VARARGS 、 METH_VARARGS | METH_KEYWORDS 。值0代表使用 PyArg_ParseTuple() 的陈旧变量。

如果单独使用 METH_VARARGS ，函数会等待Python传来tuple格式的参数，并最终使用 PyArg_ParseTuple() 进行解析。

METH_KEYWORDS 值表示接受关键字参数。这种情况下C函数需要接受第三个 PyObject* 对象，表示字典参数，使用 PyArg_ParseTupleAndKeywords() 来解析出参数。

方法表必须传递给模块初始化函数。初始化函数函数名规则为 initname() ，其中 name 为模块名。并且不能定义为文件中的static函数:

PyMODINIT_FUNC

initspam(void) {

(void) Py_InitModule("spam",SpamMethods);

}

注意 PyMODINIT_FUNC 声明了void为返回类型，还有就是平台相关的一些定义，如C++的就要定义成 extern "C" 。

Python程序首次导入这个模块时就会调用initspam()函数。他调用 Py_InitModule() 来创建一个模块对象，同时这个模块对象会插入到 sys.modules 字典中的 "spam" 键下面。然后是插入方法表中的内置函数到 "spam" 键下面。 Py_InitModule() 返回一个指针指向刚创建的模块对象。他是有可能发生严重错误的，也有可能在无法正确初始化时返回NULL。

当嵌入Python时， initspam() 函数不会自动被调用，除非在入口处的 _PyImport_Inittab 表。最简单的初始化方法是在 Py_Initialize() 之后静态调用 initspam() 函数:

int

main(int argc, char* argv[]) {

Py_SetProgramName(argv[0]);

Py_Initialize();

initspam();

//...

}

在Python发行版的 Demo/embed/demo.c 中有可以参考的源码(by gashero)。

Note

从 sys.modules 中移除模块入口，或者在多解释器环境中导入编译模块，会导致一些扩展模块出错。扩展模块作者应该特别注意初始化内部数据结构。同时要注意 reload() 函数可能会被用在扩展模块身上，并调用模块初始化函数，但是对动态状如对象(动态链接库)，却不会重新载入。

更多关于模块的现实的例子包含在Python源码包的Modules/xxmodule.c中。这些文件可以用作你的代码模板，或者学习。脚本 modulator.py 包含在源码发行版或Windows安装中，提供了一个简单的GUI，用来声明需要实现的函数和对象，并且可以生成供填入的模板。脚本在 Tools/modulator/ 目录。查看README以了解用法。

1.5 编译和连接

如果使用动态载入，细节依赖于系统，查看关于构建扩展模块部分，和关于在Windows下构建扩展的细节。

如果你无法使用动态载入，或者希望模块成为Python的永久组成部分，就必须改变配置并重新构建解释器。幸运的是，这对UNIX来说很简单，只要把你的代码(例如spammodule.c)放在 Modules/ Python源码目录下，然后增加一行到文件 Modules/Setup.local 来描述你的文件即可:

spam spammodule.o

然后重新构建解释器，使用make。你也可以在 Modules/ 子目录使用make，但是你接下来首先要重建Makefile文件，使用 make Makefile 命令。这对你改变 Setup 文件来说很重要。

如果你的模块需要其他扩展模块连接，则需要在配置文件后面加入，如:

spam spammodule.o -lX11

1.6 在C中调用Python函数

迄今为止，我们一直把注意力集中于让Python调用C函数，其实反过来也很有用，就是用C调用Python函数。这在回调函数中尤其有用。如果一个C接口使用回调，那么就要实现这个回调机制。

幸运的是，Python解释器是比较方便回调的，并给标准Python函数提供了标准接口。这里就不再详述解析Python代码作为输入的方式，如果有兴趣可以参考 Python/pythonmain.c 中的 -c 命令代码。

调用Python函数，首先Python程序要传递Python函数对象。当调用这个函数时，用全局变量保存Python函数对象的指针，还要调用 Py_INCREF() 来增加引用计数，当然不用全局变量也没什么关系。例如如下:

static PyObject* my_callback=NULL;

static PyObject*

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");

return NULL;

}

Py_XINCREF(temp);

Py_XINCREF(my_callback);

my_callback=temp;

Py_INCREF(Py_None);

result=Py_None;

}

return result;

}

这个函数必须使用 METH_VARARGS 标志注册到解释器。宏 Py_XINCREF() 和 Py_XDECREF() 增加和减少对象的引用计数。

然后，就要调用函数了，使用 PyEval_CallObject() 。这个函数有两个参数，都是指向Python对象：Python函数和参数列表。参数列表必须总是tuple对象，如果没有参数则要传递空的tuple。使用 Py_BuildValue() 时，在圆括号中的参数会构造成tuple，无论有没有参数，如:

int arg;

PyObject* arglist;

PyObject* result;

//...

arg=123;

//...

arglist=Py_BuildValue("(i)",arg);

result=PyEval_CallObject(my_callback,arglist);

Py_DECREF(arglist);

PyEval_CallObject() 返回一个Python对象指针表示返回值。 PyEval_CallObject() 是 引用计数无关 的，有如例子中，参数列表对象使用完成后就立即减少引用计数了。PyEval_CallObject() 返回一个Python对象指针表示返回值。 PyEval_CallObject() 是 引用计数无关 的，有如例子中，参数列表对象使用完成后就立即减少引用计数了。

PyEval_CallObject() 的返回值总是新的，新建对象或者是对已有对象增加引用计数。所以你必须获取这个对象指针，在使用后减少其引用计数，即便是对返回值没有兴趣也要这么做。但是在减少这个引用计数之前，你必须先检查返回的指针是否为NULL。如果是NULL，则表示出现了异常并中止了(by gashero)。如果没有处理则会向上传递并最终显示调用栈，当然，你最好还是处理好异常。如果你对异常没有兴趣，可以用 PyErr_Clear() 清除异常，例如:

if (result==NULL)

return NULL; /*向上传递异常*/

//使用result

Py_DECREF(result);

依赖于具体的回调函数，你还要提供一个参数列表到 PyEval_CallObject() 。在某些情况下参数列表是由Python程序提供的，通过接口再传到回调函数。这样就可以不改变形式直接传递。另外一些时候你要构造一个新的tuple来传递参数。最简单的方法就是 Py_BuildValue() 函数构造tuple。例如，你要传递一个事件对象时可以用:

PyObject* arglist;

//...

arglist=Py_BuildValue("(l)",eventcode);

result=PyEval_CallObject(my_callback,arglist);

Py_DECREF(arglist);

if (result==NULL)

return NULL; /*一个错误*/

/*使用返回值*/

Py_DECREF(result);

注意 Py_DECREF(arglist) 所在处会立即调用，在错误检查之前。当然还要注意一些常规的错误，比如 Py_BuildValue() 可能会遭遇内存不足等等。

1.7 解析传给扩展模块函数的参数

函数 PyArg_ParseTuple() 声明如下:

int PyArg_ParseTuple(PyObject* arg, char* format, ...);

参数 arg 必须是一个tuple对象，包含传递过来的参数， format 参数必须是格式化字符串，语法解释见 "Python C/API" 的5.5节。剩余参数是各个变量的地址，类型要与格式化字符串对应。

注意 PyArg_ParseTuple() 会检测他需要的Python参数类型，却无法检测传递给他的C变量地址，如果这里出错了，可能会在内存中随机写入东西，小心。

任何Python对象的引用，在调用者这里都是 借用的引用 ，而不增加引用计数。

一些例子:

int ok;

int i,j;

long k,l;

const char* s;

int size;

ok=PyArg_ParseTuple(args,"");

/* python call: f() */

ok=PyArg_ParseTuple(args,"s",&s);

/* python call: f('whoops!') */

ok=PyArg_ParseTuple(args,"lls",&k,&l,&s);

/* python call: f(1,2,'three') */

ok=PyArg_ParseTuple(args,"(ii)s#",&i,&j,&s,&size);

/* python call: f((1,2),'three') */

{

const char* file;

const char* mode="r";

int bufsize=0;

ok=PyArg_ParseTuple(args,"s|si",&file,&mode,&bufsize);

/* python call:

f('spam')

f('spam','w')

f('spam','wb',100000)

}

{

int left,top,right,bottom,h,v;

ok=PyArg_ParseTuple(args,"((ii)(ii))(ii)",

&left,&top,&right,&bottom,&h,&v);

/* python call: f(((0,0),(400,300)),(10,10)) */

}

{

Py_complex c;

ok=PyArg_ParseTuple(args,"D:myfunction",&c);

/* python call: myfunction(1+2j) */

}

1.8 解析传给扩展模块函数的关键字参数

函数 PyArg_ParseTupleAndKeywords() 声明如下:

int PyArg_ParseTupleAndKeywords(PyObject* arg, PyObject* kwdict, \

char* format, char* kwlist[],...);

参数arg和format定义同 PyArg_ParseTuple() 。参数 kwdict 是关键字字典，用于接受运行时传来的关键字参数。参数 kwlist 是一个NULL结尾的字符串，定义了可以接受的参数名，并从左到右与format中各个变量对应。如果执行成功 PyArg_ParseTupleAndKeywords() 会返回true，否则返回false并抛出异常。

Note

嵌套的tuple在使用关键字参数时无法生效，不在kwlist中的关键字参数会导致 TypeError 异常。

如下是使用关键字参数的例子模块，作者是 Geoff Philbrick ([email protected]):

#include "Python.h"

static PyObject*

keywdarg_parrot(PyObject* self, PyObject* args, PyObject* keywds) {

int voltage;

char* state="a stiff";

char* action="voom";

char* type="Norwegian Blue";

static char* kwlist[]={"voltage","state","action","type",NULL};

if (!PyArg_ParseTupleAndKeywords(args,keywds,"i|sss",kwlist,

&voltage,&state,&action,&type))

return NULL;

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_INCREF(Py_None);

return Py_None;

}

static PyMethodDef keywdary_methods[]= {

/*注意PyCFunction，这对需要关键字参数的函数很必要*/

{"parrot",(PyCFunction)keywdarg_parrot, \

METH_VARARGS | METH_KEYWORDS, \

"Print a lovely skit to standard output."},

{NULL,NULL,0,NULL}

};

void

initkeywdarg(void) {

Py_InitModule("keywdarg",keywdarg_methods);

}

1.9 构造任意值

这个函数声明与 PyArg_ParseTuple() 很相似，如下:

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

接受一个格式字符串，与 PyArg_ParseTuple() 相同，但是参数必须是原变量的地址指针。最终返回一个Python对象适合于返回给Python代码(by gashero)。

一个与 PyArg_ParseTuple() 的不同是，后面可能需要的要求返回一个tuple，比如用于传递给其他Python函数以参数。 Py_BuildValue() 并不总是生成tuple，在多于1个参数时会生成tuple，而如果没有参数则返回None，一个参数则直接返回该参数的对象。如果要求强制生成一个长度为空的tuple，或包含一个元素的tuple，需要在格式字符串中加上括号。

例如：

代码	返回值
Py_BuildValue("")	None
Py_BuildValue("i",123)	123
Py_BuildValue("iii",123,456,789)	(123,456,789)
Py_BuildValue("s","hello")	'hello'
Py_BuildValue("ss","hello","world")	('hello', 'world')
Py_BuildValue("s#","hello",4)	'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}",'a',1,'b',2)	{'a':1,'b':2}
Py_BuildValue("((ii)(ii))(ii)",1,2,3,4,5,6)	(((1,2),(3,4)),(5,6))

1.10 引用计数

在C/C++语言中，程序员负责动态分配和回收堆(heap)当中的内存。这意味着，我们在C中编程时必须面对这个问题。

每个由 malloc() 分配的内存块，最终都要由 free() 扔到可用内存池里面去。而调用 free() 的时机非常重要，如果一个内存块忘了 free() 则是内存泄漏，程序结束前将无法重新使用。而如果对同一内存块 free() 了以后，另外一个指针再次访问，则叫做野指针。这同样会导致严重的问题。

内存泄露往往发生在一些并不常见的程序流程上面，比如一个函数申请了资源以后，却提前返回了，返回之前没有做清理工作。人们经常忘记释放资源，尤其对于后加新加的代码，而且会长时间都无法发现。这些函数往往并不经常调用，而且现在大多数机器都有庞大的虚拟内存，所以内存泄漏往往在长时间运行的进程，或经常被调用的函数中才容易发现。所以最好有个好习惯加上代码约定来尽量避免内存泄露。

Python往往包含大量的内存分配和释放，同样需要避免内存泄漏和野指针。他选择的方法就是 引用计数 。其原理比较简单：每个对象都包含一个计数器，计数器的增减与引用的增减直接相关，当引用计数为0时，表示对象已经没有存在的意义了，就可以删除了。

一个叫法是 自动垃圾回收 ，引用计数是一种垃圾回收方法，用户必须要手动调用 free() 函数。优点是可以提高内存使用率，缺点是C语言至今也没有一个可移植的自动垃圾回收器。引用计数却可以很好的移植，有如C当中的 malloc() 和 free() 一样。也许某一天会出现C语言饿自动垃圾回收器，不过在此之前我们还得用引用计数。

Python使用传统的引用计数实现，不过他包含一个循环引用探测器。这允许应用不需要担心的直接或间接的创建循环引用，而这实际上是引用计数实现的自动垃圾回收的致命缺点。循环引用指对象经过几层引用后回到自己，导致了其引用计数总是不为0。传统的引用计数实现无法解决循环引用的问题，尽管已经没有其他外部引用了。

循环引用探测器可以检测出垃圾回收中的循环并释放其中的对象。只要Python对象有 __del__() 方法，Python就可以通过 gc module 模块来自动暴露出循环引用。gc模块还提供 collect() 函数来运行循环引用探测器，可以在配置文件或运行时禁用循环应用探测器。

循环引用探测器作为一个备选选项，默认是打开的，可以在构建时使用 --without-cycle-gc 选项加到 configure 上来配置，或者移除 pyconfig.h 文件中的 WITH_CYCLE_GC 宏定义。在循环引用探测器禁用后，gc模块将不可用。

1.10.1 Python中的引用计数

有两个宏 Py_INCREF(x) 和 Py_DECREF(x) 用于增减引用计数。 Py_DECREF() 同时会在引用计数为0时释放对象资源。为了灵活性，他并不是直接调用 free() 而是调用对象所在类型的析构函数。

一个大问题是何时调用 Py_INCREF(x) 和 Py_DECREF(x) 。首先介绍一些术语。没有任何人都不会拥有一个对象，只能拥有其引用。对一个对象的引用计数定义了引用数量。拥有的引用，在不再需要时负责调用 Py_DECREF() 来减少引用计数。传递引用计数有三种方式：传递、存储和调用 Py_DECREF() 。忘记减少拥有的引用计数会导致内存泄漏。

同样重要的一个概念是借用一个对象，借用的对象不能调用 Py_DECREF() 来减少引用计数。借用者在不需要借用时，不保留其引用就可以了。应该避免拥有者释放对象之后仍然访问对象，也就是野指针。

借用的优点是你无需管理引用计数，缺点是可能被野指针搞的头晕。借用导致的野指针问题常发生在看起来无比正确，但是事实上已经被释放的对象。

借用的引用也可以用 Py_INCREF() 来改造成拥有的引用。这对引用的对象本身没什么影响，但是拥有引用的程序有责任在适当的时候释放这个拥有。

1.10.2 拥有规则

一个对象的引用进出一个函数时，其引用计数也应该同时改变。

大多数函数会返回一个对对象拥有的引用。而且几乎所有的函数其实都会创建一个对象，例如 PyInt_FromLong() 和 Py_BuildValue() ，传递一个拥有的引用给接受者。即便不是刚创建的，你也需要接受一个新的拥有引用。一般来说， PyInt_FromLong() 会维护一个常用值缓存，并且返回缓存项的引用。

很多函数提取一些对象的子对象并传递拥有引用，例如 PyObject_GetAttrString() 。另外，小心一些函数，包括： PyTuple_GetItem() 、 PyList_GetItem() 、 PyDict_GetItem() 和 PyDict_GetItemString() ，他们返回的都是借用的引用。

函数 PyImport_AddModule() 也是返回借用的引用，尽管他实际上创建了对象，只不过其拥有的引用实际存储在了 sys.modules 中。

当你传递一个对象的引用到另外一个函数时，一般来说，函数是借用你的引用，如果他确实需要存储，则会使用 Py_INCREF() 来变为拥有引用。这个规则有两种可能的异常： PyTuple_SetItem() 和 PyList_SetItem() ，这两个函数获取传递给他的拥有引用，即便是他们执行出错了。不过 PyDict_SetItem() 却不是接收拥有的引用。

当一个C函数被py调用时，使用对参数的借用。调用者拥有参数对象的拥有引用。所以，借用的引用的寿命是函数返回。只有当这类参数必须存储时，才会使用 Py_INCREF() 变为拥有的引用。

从C函数返回的对象引用必须是拥有的引用，这时的拥有者是调用者。

1.10.3 危险的薄冰

有些使用借用的情况会出现问题。这是对解释器的盲目理解所导致的，因为拥有者往往提前释放了引用。

首先而最重要的情况是使用 Py_DECREF() 来释放一个本来是借用的对象，比如列表中的元素:

void

bug(PyObject* list) {

PyObject* item=PyList_GetItem(list,0);

PyList_SetItem(list,1,PyInt_FromLong(0L));

PyObject_Print(item,stdout,0); /* BUG! */

}

这个函数首先借用了 list[0] ，然后把 list[1] 替换为值0，最后打印借用的引用。看起来正确么，不是！

我们来跟踪一下 PyList_SetItem() 的控制流，列表拥有所有元素的引用，所以当项目1被替换时，他就释放了原始项目1。而原始项目1是一个用户定义类的实例，假设这个类定义包含 __del__() 方法。如果这个类的实例引用计数为1，处理过程会调用 __del__() 方法。

因为使用python编写，所以 __del__() 中可以用任何python代码来完成释放工作。替换元素的过程会执行 del list[0] ，即减掉了对象的最后一个引用，然后就可以释放内存了。

知道问题后，解决方案就出来了：临时增加引用计数。正确的版本如下:

void

no_bug(PyObject* list) {

PyObject* item=PyList_GetItem(list,0);

Py_INCREF(item);

PyList_SetItem(list,1,PyInt_FromLong(0L));

PyObject_Print(item,stdout,0);

Py_DECREF(item);

}

这是一个真实的故事，旧版本的Python中多处包含这个问题，让guido花费大量时间研究 __del__() 为什么失败了。

第二种情况的问题出现在多线程中的借用引用。一般来说，python中的多线程之间并不能互相影响对方，因为存在一个GIL。不过，这可能使用宏 Py_BEGIN_ALLOW_THREADS 来临时释放锁，最后通过宏 Py_END_ALLOW_THREADS 来再申请锁，这在IO调用时很常见，允许其他线程使用处理器而不是等待IO结束。很明显，下面的代码与前面的问题相同:

void

bug(PyObject* list) {

PyObject* item=PyList_GetItem(list,0);

Py_BEGIN_ALLOW_THREADS

//一些IO阻塞调用

Py_END_ALLOW_THREADS

PyObject_Print(item,stdout,0); /*BUG*/

}

1.10.4 NULL指针

一般来说，函数接受的参数并不希望你传递一个NULL指针进来，这会出错的。函数的返回对象引用返回NULL则代表发生了异常。这是Python的机制，毕竟，一个函数如果执行出错了，那么也没有必要多解释了，浪费时间。(注：彪悍的异常也不需要解释)

最好的测试NULL的方法就是在代码里面，一个指针如果收到了NULL，例如 malloc() 或其他函数，则表示发生了异常。

宏 Py_INCREF() 和 Py_DECREF() 并不检查NULL指针，不过还好， Py_XINCREF() 和 Py_XDECREF() 会检查。

检查特定类型的宏，形如 Pytype_Check() 也不检查NULL指针，因为这个检查是多余的。

C函数的调用机制确保传递的参数列表(也就是args参数)用不为NULL，事实上，它总是一个tuple。

而把NULL扔到Python用户那里可就是一个非常严重的错误了。

1.11 使用C++编写扩展

有时候需要用C++编写Python扩展模块。不过有一些严格的限制。如果Python解释器的主函数是使用C编译器编译和连接的，那么全局和静态对象的构造函数将无法使用。而主函数使用C++编译器时则不会有这个问题。被Python调用的函数，特别是模块初始化函数，必须声明为 extern "C" 。没有必要在Python头文件中使用 extern "C" 因为在使用C++编译器时会自动加上 __cplusplus 这个定义，而一般的C++编译器一般都会设置这个符号。

1.12 提供给其他模块以C API

很多模块只是提供给Python使用的函数和新类型，但是偶尔也有可能被其他扩展模块所调用。例如一个模块实现了 "collection" 类型，可以像list一样工作而没有顺序。有如标准Python中的list类型一样，提供的C接口可以让扩展模块创建和管理list，这个新的类型也需要有C函数以供其他扩展模块直接管理。

初看这个功能可能以为很简单：只要写这些函数就行了(不需要声明为静态)，提供适当的头文件，并注释C的API。当然，如果所有的扩展模块都是静态链接到Python解释器的话，这当然可以正常工作。但是当其他扩展模块是动态链接库时，定义在一个模块中的符号，可能对另外一个模块来说并不是可见的。而这个可见性又是依赖操作系统实现的，一些操作系统对Python解释器使用全局命名空间和所有的扩展模块(例如Windows)，也有些系统则需要明确的声明模块的导出符号表(AIX就是个例子)，或者提供一个不同策略的选择(大多数的Unices)。即便这些符号是全局可见的，拥有函数的模块，也可能尚未载入。

为了可移植性，不要奢望任何符号会对外可见。这意味着模块中所有的符号都声明为 static ，除了模块的初始化函数以外，这也是为了避免各个扩展模块之间的符号名称冲突。这也意味着必须以其他方式导出扩展模块的符号。

Python提供了一种特殊的机制，以便在扩展模块间传递C级别的信息(指针)： CObject 。一个CObject是一个Python的数据类型，存储了任意类型指针(void*)。CObject可以只通过C API来创建和存取，但是却可以像其他Python对象那样来传递。在特别的情况下，他们可以被赋予一个扩展模块命名空间内的名字。其他扩展模块随后可以导入这个模块，获取这个名字的值，然后得到CObject中保存的指针。

通过CObject有很多种方式导出扩展模块的C API。每个名字都可以得到他自己的CObject，或者可以把所有的导出C API放在一个CObject指定的数组中来发布。所以可以有很多种方法导出C API。

如下的示例代码展示了把大部分的重负载任务交给扩展模块，作为一个很普通的扩展模块的例子。他保存了所有的C API的指针到一个数组中，而这个数组的指针存储在CObject中。对应的头文件提供了一个宏以管理导入模块和获取C API的指针，客户端模块只需要在存取C API之前执行这个宏就可以了。

这个导出模块是修改自1.1节的spam模块。函数 spam.system() 并不是直接调用C库的函数 system() ，而是调用 PySpam_System() ，提供了更加复杂的功能。这个函数 PySpam_System() 同样导出供其他扩展模块使用。

函数 PySpam_System() 是一个纯C函数，(by gashero)声明为static如下:

static int

PySpam_System(const char* command) {

return system(command);

}

函数 spam_system() 做了细小的修改:

static PyObject*

spam_system(PyObject* self, PyObject* args) {

const char* command;

int sts;

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

return NULL;

sts=PySpam_System(command);

return Py_BuildValue("i",sts);

}

在模块的头部加上如下行:

#include "Python.h"

另外两行需要添加的是:

#define SPAM_MODULE

#include "spammodule.h"

这个宏定义是告诉头文件需要作为导出模块，而不是客户端模块。最终模块的初始化函数必须管理初始化C API指针数组的初始化:

PyMODINIT_FUNC

initspam(void)

{

PyObject *m;

static void *PySpam_API[PySpam_API_pointers];

PyObject *c_api_object;

m = Py_InitModule("spam", SpamMethods);

if (m == NULL)

return;

/* Initialize the C API pointer array */

PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

/* Create a CObject containing the API pointer array's address */

c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);

if (c_api_object != NULL)

PyModule_AddObject(m, "_C_API", c_api_object);

}

注意 PySpam_API 声明为static，否则 initspam() 函数执行之后，指针数组就消失了。

大部分的工作还是在头文件 spammodule.h 中，如下:

#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 */

static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;

#else

/* This section is used in modules that use spammodule's API */

static void **PySpam_API;

#define PySpam_System \

(*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])

/* Return -1 and set exception on error, 0 on success. */

static int

import_spam(void)

{

PyObject *module = PyImport_ImportModule("spam");

if (module != NULL) {

PyObject *c_api_object = PyObject_GetAttrString(module, "_C_API");

if (c_api_object == NULL)

return -1;

if (PyCObject_Check(c_api_object))

PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);

Py_DECREF(c_api_object);

}

return 0;

}

#endif

#ifdef __cplusplus

}

#endif

#endif /* !defined(Py_SPAMMODULE_H) */

想要调用 PySpam_System() 的客户端模块必须在初始化函数中调用 import_spam() 以初始化导出扩展模块:

PyMODINIT_FUNC

initclient(void) {

PyObject* m;

m=Py_InitModule("client",ClientMethods);

if (m==NULL)

return;

if (import_spam()<0)

return;

/*其他初始化语句*/

}

这样做的缺点是 spammodule.h 有点复杂。不过这种结构却可以方便的用于其他导出函数，所以学着用一次也就好了。

最后需要提及的是CObject提供的一些附加函数，用于CObject指定的内存块的分配和释放。详细信息可以参考Python的C API参考手册的CObject一节，和CObject的实现，参考文件 Include/cobject.h 和 Objects/cobject.c 。

2 定义新类型

程序员可以自定义类型供Python操作，有如一些核心数据类型一样。

这并不困难，所有的扩展类型代码都遵循同一个模式，但是有一些细节需要了解就是了。

Note

定义新类型的方法在Python2.2时发生了巨大的改变。本文仅描述Python2.2和更新的版本的。如果需要支持太老的Python，你还是找老文档去吧。

2.1 基础

Python运行时会把所有Python对象看作是PyObject*类型的指针。一个PyObject并不是一个很庞大的对象，而仅仅包含引用计数和指向 类型对象 的指针。类型对象决定了C函数从哪里调用，例如，一个属性就会查找一个对象或被其他对象使用(?)。C函数会调用 类型方法 来区别于 [].append (叫做 对象方法 )。

所以，如果你想要定义一个新的对象类型，你需要创建类型对象。

这个步骤可以用例子来解释，如下就是一个很小，但是完整定义的新类型。

#include

typedef struct {

PyObject_HEAD

//这里描述各个字段

} noddy_NoddyObject;

static PyTypeObject noddy_NoddyType={

PyObject_HEAD_INIT(NULL)

0, //ob_size

"noddy.Noddy", //tp_name

sizeof(noddy_NoddyObject), //tp_basicsize

0, //tp_itemsize

0, //tp_dealloc

0, //tp_print

0, //tp_getattr

0, //tp_setattr

0, //tp_compare

0, //tp_repr

0, //tp_as_number

0, //tp_as_sequence

0, //tp_as_mapping

0, //tp_hash

0, //tp_call

0, //tp_str

0, //tp_getattro

0, //tp_setattro

0, //tp_as_buffer

Py_TPFLAGS_DEFAULT, //tp_flags

"Noddy objects", //tp_doc

};

static PyMethodDef noddy_methods[]={

{NULL}

};

#ifndef PyMODINIT_FUNC

#define PyMODINIT_FUNC void

#endif

PyMODINIT_FUNC initnoddy(void) {

PyObject* m;

noddy_NoddyType.tp_new=PyType_GenericNew;

if (PyType_Ready(&noddy_NoddyType)<0)

return;

m=Py_InitModule3("noddy",noddy_methods,"Example module with new type");

Py_INCREF(&noddy_NoddyType);

PyModule_AddObject(m,"Noddy",(PyObject*)&noddy_NoddyType);

}

这里还有很多地方(bit)是空的，以后可以逐渐知道他们的意义。

首先是:

typedef struct {

PyObject_HEAD

} noddy_NoddyObject;

这就是Noddy需要包含的，在这种情况下没办法包含Python对象以外的东西(This is what a Noddy object will contain--in this case, nothing more than every Python object contains)，也就是一个类型对象的指针。这是由PyObject_HEAD宏所引进的字段。在这里使用宏是为了规范化层次并且便于调试。注意，在宏 PyObject_HEAD 后面是没有分号";"的，因为宏里面已经包含了一个了。一定要小心不注意加上的分号，因为习惯使然，你的编译器也会提示，但是其他人也许却不注意(在Windows上MSVC会把这个问题当作错误，并且不允许编译)。

与之相比，我们看看标准Python整数的定义:

typedef struct {

PyObject_HEAD

long ob_ival;

} PyIntObject;

继续看看类型对象:

static PyTypeObject noddy_NoddyType={

PyObject_HEAD_INIT(NULL)

0, //ob_size

"noddy,Noddy", //tp_name

sizeof(noddy_NoddyObject), //tp_basicsize

0, //tp_itemsize

0, //tp_dealloc

0, //tp_print

0, //tp_getattr

0, //tp_setattr

0, //tp_compare

0, //tp_repr

0, //tp_as_number

0, //tp_as_sequence

0, //tp_as_mapping

0, //tp_hash

0, //tp_call

0, //tp_str

0, //tp_getattro

0, //tp_setattro

0, //tp_as_buffer

Py_TPFLAGS_DEFAULTS, //tp_flags

"Noddy objects", //tp_doc

};

现在你再去看看 object.h 中 PyTypeObject 的定义，你会发现有如上的很多字段定义。剩余的字段会被C编译器以0填充，按照惯例，如果你不用他们那就别碰他们。

这对于为未来预留功能位置比较有用:

PyObject_HEAD_INIT(NULL)

这行有点恶心，(by gashero)而我们还可以这样写:

PyObject_HEAD_INIT(&PyType_Type)

作为一个类型对象type的类型，但是这些并不是总是会被C编译器接受。幸运的，是，这些空着的字段会自动被 PyType_Ready() 所填充。

0, //ob_size

字段ob_size并没有用上，它放在这个位置只是为了兼容旧版本的Python的扩展模块。这个字段总是设为0。

"noddy.Noddy", //tp_name

这是这个类型的名字。这将会显示在默认的文本描述或者一些错误信息中，例如:

>>> ""+noddy.new_noddy()

Traceback (most recent call last):

File "", line1, in ?

TypeError: cannot add type "noddy.Noddy" to string

注意名字是以点号分隔的，同时包含模块名和类型名。这里的模块名是noddy，而类型是Noddy，所以设置类型名为noddy.Noddy。

sizeof(noddy_NoddyObject), //tp_basicsize

这是让Python知道在调用 PyObject_New() 时分配多少内存。

Note

如果你想要你的类型可以被子类化，并且你的类型作为基类时拥有相同的tp_basicsize，你可能在多继承时遇到问题。因为该子类会在 __bases__ 中列出自定义的类型，而且在调用 __new__ 失败时不会报出错误。想要避免这个问题可以设置一个足够大的 tp_basicsize ，至少比父类型要大。大多数时候这是正确的，无论你实例化对象，还是给基类对象添加数据成员，因此也会增加其大小。

0, //tp_itemsize

对于列表和字符串，这里应该是可变长度，不过暂时忽略。

跳过我们没有定义的类型方法，我们设置类标志为 Py_TPFLAGS_DEFAULT

Py_TPFLAGS_DEFAULT, //tp_flags

所有的类型都应该包含这个常量。它允许在当前Python版本中所有成员定义。

我们提供了一个doc string到 tp_doc

"Noddy objects", //tp_doc

现在我们看看类型方法。我们在模块中实现这些。一会的例子中展示。

现在所作的都是为了创建Noddy对象。允许对象的创建，我们必须提供一个 tp_new 的实现。我们也可以使用默认的实现，也就是 PyType_GenericNew() 。只需要将其赋值到 tp_new 的位置即可。不过有些平台和C编译器实现中不允许用一个函数调用来初始化一个结构体。所以，我们将赋值放到模块初始化函数中，在 PyType_Ready() 之前:

noddy_NoddyType.tp_new=PyType_GenericNew;

if (PyType_Ready(&noddy_NoddyType)<0)

return;

所有其他类型方法都是NULL，一会在写。

剩余的部分都很像，除了 initnoddy() 中的一些代码:

if (PyType_Ready(&noddy_NoddyType)<0)

return;

这会初始化Noddy类型，填入成员，包括 ob_type

PyModule_AddObject(m,"Noddy",(PyObject*)&noddy_NoddyType);

这回添加类型到模块字典，这样我们就可以通过如下来创建Noddy的示例了:

>>> import noddy

>>> mynoddy=noddy.Noddy()

就这些了，剩余的就是构建了，将这些代码放到 noddy.c 中，然后 setup.py 中写:

from distutils.core import setup,Extension

setup(name="noddy",version="1.0",

ext_modules=[Extension("noddy",["noddy.c"])])

然后输入:

$ python setup.py build

这时就会在子目录产生 noddy.so ，将其放到Python启动目录下，就可以按照上面的导入该模块并生成实例了。

其实并不难，不过现在功能还不够有趣，没有数据，不能做任何事，也不能被继承。

2.1.1 给例子添加数据和方法

让我们给这个例子添加数据和方法。也要让着个类型可以作为基类。我们创建一个新的模块，noddy2添加这些功能:

#include

typedef struct {

PyObject_HEAD

PyObject *first;

PyObject *last;

int number;

} Noddy;

static void Noddy_dealloc(Noddy *self) {

Py_XDECREF(self->first);

Py_XDECREF(self->last);

self->ob_type->tp_free((PyObject*)self);

}

static PyObject *Noddy_New(PyTypeObject *type, PyObject *args, PyObject *kwds) {

Noddy *self;

self=(Noddy*)type->tp_alloc(type,0);

if (self!=NULL) {

self->first=PyString_FromString("");

if (self->first==NULL) {

Py_DECREF(self);

return NULL;

}

self->last=PyString_FromString("");

if (self->last==NULL) {

Py_DECREF(self);

return NULL;

}

self->number=0;

}

return (PyObject*)self;

}

static int Noddy_init(Noddy *self, PyObject *args, PyObject *kwds) {

PyObject *first=NULL, *last=NULL, *tmp;

static char *kwlist[]={"first", "last", "number", NULL};

if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,

&first, &last, &self->number))

return -1;

if (first) {

tmp=self->first;

Py_INCREF(first);

self->first=first;

Py_XDECREF(tmp);

}

if (last) {

tmp=self->last;

Py_INCREF(last);

self->last=last;

Py_XDECREF(tmp);

}

return 0;

}

static PyMemberDef Noddy_members[]={

{"first", T_OBJECT_EX, offsetof(Noddy, first), 0, "first name"},

{"last", T_OBJECT_EX, offsetof(Noddy, last), 0, "last name"},

{"number", T_OBJECT_EX, offsetof(Noddy, number),0, "number"},

{NULL}

};

static PyObject *Noddy_name(Noddy *self) {

static PyObject *format=NULL;

PyObject *args, *result;

if (format==NULL) {

format=PyString_FromString("%s %s");

if (format==NULL) //by gashero

return NULL;

}

if (self->first==NULL) {

PyErr_SetString(PyExc_AttributeError, "first");

return NULL;

}

if (self->last==NULL) {

PyErr_SetString(PyExc_AttributeError, "last");

return NULL;

}

args=Py_BuildValue("OO", self->first, self->last);

if (args==NULL)

return NULL;

result=PyString_Format(format, args);

Py_DECREF(args);

return result;

}

static PyMethodDef Noddy_methods[] = {

{"name", (PyCFunction)Noddy_name, METH_NOARGS,

"return name, combining the first and last name"},

{NULL}

};

static PyTypeObject NoddyType = {

PyObject_HEAD_INIT(NULL)

0, //ob_size

"noddy.Noddy", //tp_name

sizeof(Noddy), //tp_basicsize

0, //tp_itemsize

(destructor)Noddy_dealloc, //tp_dealloc

0, //tp_print

0, //tp_getattr

0, //tp_setattr

0, //tp_compare

0, //tp_repr

0, //tp_as_number

0, //tp_as_sequence

0, //tp_as_mapping

0, //tp_hash

0, //tp_call

0, //tp_str

0, //tp_getattro

0, //tp_setattro

0, //tp_as_buffer

Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, //tp_flags

"Noddy objects", //tp_doc

0, //tp_traverse

0, //tp_clear

0, //tp_richcompare

0, //tp_weaklistoffset

0, //tp_iter

0, //tp_iternext

Noddy_methods, //tp_methods

Noddy_members, //tp_members

0, //tp_getset

0, //tp_base

0, //tp_dict

0, //tp_descr_get

0, //tp_descr_set

0, //tp_dictoffset

(initproc)Noddy_init, //tp_init

0, //tp_alloc

Noddy_new, //tp_new

};

static PyMethodDef module_methods[] = {

{NULL}

};

#ifndef PyMODINIT_FUNC

#define PyMODINIT_FUNC void

#endif

PyMODINIT_FUNC

initnoddy2(void) {

PyObjec *m;

if (PyType_Ready(&NoddyType)<0)

return;

m=Py_InitModule3("noddy2", module_methods,

Example");

if (m==NULL)

return;

Py_INCREF(&NoddyType);

PyModule_AddObject(m, "Noddy", (PyObject*)&NoddyType);

}

开头时导入了 structmember.h 头文件。用于处理属性，稍后解释。

Noddy对象也缩写为Noddy了，其类型对象是 NoddyType 。

Noddy类型有三个数据属性，first、last、number。first和last是Python字符串，number是整数。对象结构体中记录了这三个字段的实际值。

因为有数据成员了，所以需要小心的分配和释放。至少需要释放方法(deallocation method)，即 Noddy_dealloc() 函数。并且指定到 tp_dealloc 成员。负责将几个对象的引用计数减少。使用 Py_XDECREF() 因为first和last有可能是NULL。随后会调用 tp_free 成员来释放对象的内存。注意对象的类型有可能不是Noddy，有可能是其子类。

我们需要确保first和last初始化为空字符串，在 Noddy_new() 中做。并将该函数赋值到 tp_new 成员。

tp_new 成员用于响应创建(create, 而不是初始化)类型的对象。暴露为Python的 __new__() 方法。实现 new 方法的一个目的是所有实例值都有初始化的值。此例中，我们使用新方法来确保初始值不是NULL。如果我们不在乎初始值是NULL，则可以使用 PyType_GenericNew() 作为我们的 new 方法，也就是以前所做的。 PyType_GenericNew() 初始化所有的实例变量到NULL。

new 方法是静态方法，传入要初始化的类型及其参数，返回新创建的对象。 new 方法总是接收可选的和关键字参数，不过通常被忽略，留下参数处理到初始化方法。注意如果类型支持子类，传递来的类型可能不是之前定义的。 new 方法调用 tp_alloc 槽来分配内存。我们并不填充 tp_alloc 槽。 PyType_Ready() 会自动填充它，集成自基类，缺省是 object 。大多数类型都是默认分配的。

如果你创建一个合作的(co-operative) tp_new (调用基类的 tp_new 或 __new__() )，你必须不能假设调用顺序。总是静态检测你要调用的类型，并直接调用 tp_new ，或通过 type->tp_base->tp_new 。如果你不这么做，你类型的Python子类也会集成Python定义的类，而无法正常工作。你根本就无法创建子类的对象，而得到TypError。

初始化方法 Noddy_init() 放入 tp_init 成员。暴露为Python的 __init__() 方法，用于初始化刚创建对象。不像 new 方法，我们无法确保初始化器一定被调用。初始化器在被解包时不会被调用，且可以被重载。我们的初始化器接收参数来提供初始化值。初始化器总是接受可选的和关键字参数。

初始化器可以被多次调用。任何人可以调用 __init__() 方法。因为如此，我们必须小心的确保赋值。可能被诱惑这么干:

if (first) {

Py_XDECREF(self->first);

Py_INCREF(first);

self->first=first;

}

但是这是有风险的。我们的类型没有严格限制first的类型，所以其可能是其他类型的对象(by gashero)。有可能在方法first成员时触发其destructor。要避免这种可能，我们总是重新赋值成员，在减少其引用计数前，原因：

当我们绝对知道引用计数大于1时
当我们知道对象的deallocation不会在我们的代码里被调用时
当tp_dealloc 在GC调用时不支持减少引用计数时

要暴露实例属性，有多种办法，最简单的办法是定义成员定义，即 Noddy_members 。然后放在 tp_members 成员。

每个成员定义都有个成员名字，类型，偏移值，访问标识和文档字符串。

这种方式的缺点是没法提供限制属性赋值的方法。我们期望first和last是字符串，但是任何Python对象都可以被赋值。而且这些属性也可以被删除，甚至C指针到NULL。哪怕我们已经初始化为非NULL值了，成员在被删除时会被设置为NULL。

定义了一个方法叫 name() ，输出first和last组合的结果。

方法实现为一个C函数，接受Noddy(或其子类)作为第一个参数。方法总是接受一个实例作为第一个参数。方法总是接受可选和关键字参数，不过此例我们不关心参数，就定义了不接受参数。有如:

def name(self):

return '%s %s'%(self.first, self.last)

注意我们必须检查first和last不能是NULL。这是因为删除会导致成员变为NULL。更好的办法是检测属性值必须是String类型，下一节讨论。

已有的定义方法也需要放到一个数组中 Noddy_methods ，然后放到 tp_methods 成员。注意我们使用 METH_NOARGS 标识来表示不接受参数。

最后我们定义这个类型可以作为基类，通过 Py_TPFLAGS_BASETYPE 。一直到现在，很小心的确保了我们的对象可以被作为基类使用。

2.1.2 为数据属性提供控制

本节讨论如何给Noddy对象的属性first和last提供控制。在前面章节的模块中，实例变量first和last可以设置为非空字符串，我们想要确保这些属性总是包含字符串。

#include

#include "structmember.h"

typedef struct {

PyObject_HEAD

PyObject *first;

PyObject *last;

int number;

} Noddy;

static void Noddy_dealloc(Noddy *self) {

Py_XDECREF(self->first);

Py_XDECREF(self->last);

self->ob_type->tp_free((PyObject*)self);

}

static PyObject *Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds) {

Noddy *self;

self=(Noddy*)type->tp_alloc(type,0);

if (self!=NULL) {

self->first=PyString_FromString("");

if (self->first==NULL) {

Py_DECREF(self);

return NULL;

}

self->last=PyString_FromString("");

if (self->last==NULL) {

Py_DECREF(self);

return NULL;

}

self->number=0;

}

return (PyObject*)self;

}

static int Noddy_init(Noddy *self, PyObject *args, PyObject *kwds) {

PyObject *first=NULL, *last=NULL, *tmp;

static char *kwlist[]={"first","last","number", NULL};

if (!PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist,

&first, &last, &self->number))

return -1;

if (first) {

tmp=self->first;

Py_INCREF(first);

self->first=first;

Py_DECREF(tmp);

}

if (last) {

tmp=self->last;

Py_INCREF(last);

self->last=last;

Py_DECREF(tmp);

}

return 0;

}

static PyMemberDef Noddy_members[]={

{"number", T_INT, offsetof(Noddy,number), 0, "noddy number"},

{NULL}

};

static PyObject *Noddy_getfirst(Noddy *self, void *closure) {

Py_INCREF(self->first);

return self->first;

}

static int Noddy_setfirst(Noddy *self, PyObject *value, void *closure) {

if (value==NULL) {

PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");

return -1;

}

if (!PyString_Check(value)) {

PyErr_SetString(PyExc_TypeError, "The first attribute value must be a string");

return -1;

}

Py_DECREF(self->first);

Py_INCREF(value);

self->first=value;

return 0;

}

static PyObject *Noddy_getlast(Noddy *self, void *closure) {

Py_INCREF(self->last);

return self->last;

}

static int Noddy_setlast(Noddy *self, PyObject *value, void *closure) {

if (value==NULL) {

PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");

return -1;

}

if (!PyString_Check(value)) {

PyErr_SetString(PyExc_TypeError, "The last attribute value must be a string");

return -1;

}

Py_DECREF(self->last);

Py_INCREF(value);

self->last=value;

return 0;

}

static PyGetSetDef Noddy_getseters[]={

{"first", (getter)Noddy_getfirst, (setter)Noddy_setfirst, "first name", NULL},

{"last", (getter)Noddy_getlast, (setter)Noddy_setlast, "last name", NULL},

{NULL}

};

static PyObject *Noddy_name(Noddy *self) {

static PyObject *format=NULL;

PyObject *args, *result;

if (format==NULL) {

format=PyString_FromString("%s %s");

if (format==NULL)

return NULL;

}

args=Py_BuildValue("OO",self->first,self->last);

if (args==NULL)

return NULL;

result=PyString_Format(format,args);

Py_DECREF(args);

return result;

}

static PyMethodDef Noddy_methods[]={

{"name", (PyCFunction)Noddy_name, METH_NOARGS, "return name"},

{NULL}

};

static PyTypeObject NoddyType={

PyObject_HEAD_INIT(NULL)

0, //ob_size

"noddy.Noddy", //tp_name

sizeof(Noddy), //tp_basicsize

0, //tp_itemsize

(destructor)Noddy_dealloc, //tp_dealloc

0, //tp_print

0, //tp_getattr

0, //tp_setattr

0, //tp_compare

0, //tp_repr

0, //tp_as_number

0, //tp_as_sequence

0, //tp_as_mapping

0, //tp_hash

0, //tp_call

0, //tp_str

0, //tp_getattro

0, //tp_setattro

0, //tp_as_buffer

Py_TPFLAGS_DEFAULT|Py_TPFLAGS_BASETYPE, //tp_flags

"Noddy object", //tp_doc

0, //tp_traverse

0, //tp_clear

0, //tp_richcompare

0, //tp_weaklistoffset

0, //tp_iter

0, //tp_iternext

Noddy_methods, //tp_methods

Noddy_members, //tp_members

Noddy_getseters, //tp_getset

0, //tp_base

0, //tp_dict

0, //tp_descr_get

0, //tp_descr_set

0, //tp_dictoffset

(initproc)Noddy_init, //tp_init

0, //tp_alloc

Noddy_new, //tp_new

};

static PyMethodDef module_methods[]={

{NULL}

};

#ifndef PyMODINIT_FUNC

#define PyMODINIT_FUNC void

#endif

PyMODINIT_FUNC initnoddy3(void) {

PyObject *m;

if (PyType_Ready(&Noddy_Type)<0)

return;

m=Py_InitModule3("noddy3",module_methods,

"Example noddy3");

if (m==NULL)

return;

Py_INCREF(&NoddyType);

PyModule_AddObject(m, "Noddy", (PyObject*)&NoddyType);

}

要实现更加精细的控制，可以自己修改getter和setter函数。如下就是first属性对应的set和get函数:

Noddy_getfirst(Noddy *self, void *closure) {

Py_INCREF(self->first);

return self->first;

}

static int Noddy_setfirst(Noddy *self, PyObject *value, void *closure) {

if (value==NULL) {

PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");

return -1;

}

if (!PyString_Check(value)) {

PyErr_SetString(PyExc_TypeError,

"The first attribute value must be a string");

return -1;

}

Py_DECREF(self->first);

Py_INCREF(value);

self->first=value;

return 0;

}

setter和getter函数会传入Noddy对象和一个 "closure" 。在这个例子里，closure会被忽略。closure用以支持定义数据时的高级用法。例如允许一组setter和getter函数决定closure里数据的设置和获取。

setter函数传入Noddy对象，新的值，以及closure。新的值可以时NULL，表示该属性需要被删除。在我们的setter里，如果属性被删除或传入的值不是字符串则抛出异常。

创建一个数组 PyGetSetDef 结构来声明:

static PyGetSetDef Noddy_getseters[] = {

{"first",

(getter)Noddy_getfirst, (setter)Noddy_setfirst,

"first name", NULL},

{"last",

(getter)Noddy_getlast, (setter)Noddy_setlast,

"last name", NULL},

{NULL}

};

并且注册到 tp_getset 槽:

Noddy_getseters, //tp_getset

最后要提到的是closure，这里用到时都是传入NULL的。

还可以删除成员定义:

static PyMemberDef Noddy_members[] = {

{"number", T_INT, offsetof(Noddy, number), 0,

"noddy number"},

{NULL}

};

我们还需要更新 tp_init 处理器来允许传入string:

static int

Noddy_init(Noddy *self, PyObject *args, PyObject *kwds) {

PyObject *first=NULL, *last=NULL, *tmp;

static char *kwlist[] = {"first", "last", "number", NULL};

if (!PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist,

&first, &last, &self->number))

return -1;

if (first) {

tmp=self->first;

Py_INCREF(first);

self->first=first;

Py_DECREF(tmp);

}

if (last) {

tmp=self->last;

Py_INCREF(last);

self->last=last;

Py_DECREF(tmp);

}

return 0;

}

通过这些修改，我们可以确保first和last成员不会是NULL，所以可以在所有情况中不必检查其是否为NULL了。这意味着大部分的 Py_XDECREF() 可以改为 Py_DECREF() 。(by gashero)唯一无法修改的地方是 dealloctor ，因为在初始化这些成员时可能会出错。

我们也将模块初始化函数改为初始化函数，以及增加了另外的定义到 setup.py 文件。

2.1.3 支持循环引用垃圾收集

Python有循环垃圾收集器，可以将对象在引用计数不为零时仍然标记为无用。这可以解决循环引用。例如:

>>> l=[]

>>> l.append(l)

>>> del l

在这里例子中，列表包含了他自身。当删除时，他仍然持有他自己的引用，其引用计数不会到0。幸运的是Python的循环垃圾收集会实际指出该问题，并释放。

在第二个版本的Noddy例子，我们允许任何类型的对象存储到first和last属性。这意味着Noddy对象可以进入循环:

>>> import noddy2

>>> n=noddy2.Noddy()

>>> l=[n]

>>> n.first=l

这很蠢，但提醒我们需要加入循环垃圾收集器到Noddy的例子。要支持循环垃圾收集，类型需要填充2个槽并设置类标识允许这些槽。

#include

#include "structmember.h"

typedef struct {

PyObject_HEAD

PyObject *first;

PyObject *last;

int number;

} Noddy;

static int

Noddy_traverse(Noddy *self, visitproc visit, void *arg {

int vert;

if (self->first) {

vret=visit(self->first,arg);

if (vert!=0)

return vert;

}

if (self->last) {

vert=visit(self->last, arg);

if (vert!=0)

return vert;

}

return 0;

}

static int

Noddy_clear(Noddy *self) {

PyObject *tmp;

tmp=self->first;

self->first=NULL;

Py_XDECREF(tmp);

tmp=self->last;

self->last=NULL;

Py_XDECREF(tmp);

return 0;

}

static void

Noddy_dealloc(Noddy *self) {

Noddy_clear(self);

self->ob_type->tp_free((PyObject*)self);

}

static PyObject *

Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds) {

Noddy *self;

self=(Noddy*)type->tp_alloc(type,0);

if (self!=NULL) {

self->first=PyString_FromString("");

if (self->first==NULL) {

Py_DECREF(self);

return NULL;

}

self->last=PyString_FromString("");

if (self->last==NULL) {

Py_DECREF(self);

return NULL;

}

self->number=0;

}

return (PyObject*)self;

}

static int

Noddy_init(Noddy *self, PyObject *args, PyObject *kwds) {

PyObject *first=NULL, *last=NULL, *tmp;

static char *kwlist[] = {"first", "last", "number", NULL};

if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,

&first, &last, &self->number))

return -1;

if (first) {

tmp=self->first;

Py_INCREF(first);

self->first=first;

Py_XDECREF(tmp);

}

if (last) {

tmp=self->last;

Py_INCREF(last);

self->last=last;

Py_XDECREF(tmp);

}

return 0;

}

static PyMemberDef Noddy_members[] = {

{"first", T_OBJECT_EX, offsetof(Noddy,first), 0,

"first name"},

{"last", T_OBJECT_EX, offsetof(Noddy,last), 0,

"last name"},

{"number", T_INT, offsetof(Noddy,number), 0,

"noddy number"},

{NULL}

};

@wait 代码都没抄完呢，(by gashero)一大堆废话

2.1.4 继承其他类型

@wait

2.2 类型方法

快速了解类型方法(type method)的实现。如下是 PyTypeObject 的定义，有些字段用于调试:

typedef struct _typeobject {

PyObject_VAR_HEAD

char *tp_name; //用于打印

int tp_basicsize, tp_itemsize; //用于分配

//标准操作的实现方法

destructor tp_dealloc;

printfunc tp_print;

getattrfunc tp_getattr;

setattrfunc tp_setattr;

cmpfunc tp_compare;

reprfunc tp_repr;

//标准类的方法集合

PyNumberMethods *tp_as_number;

PySequenceMethods *tp_as_sequence;

PyMappingMehtods *tp_as_mapping;

//更多标准操作(二进制兼容)

hashfunc tp_hash;

ternaryfunc tp_call;

reprfunc tp_str;

getattrfunc tp_getattro;

setattrfunc tp_setattro;

//访问对象IO缓冲的函数

PyBufferProcs *tp_as_buffer;

//定义可选和扩展操作的标识

long tp_flags;

char *tp_doc; //文档字符串

//从2.0开始的所有可访问对象调用函数

traverseproc tp_traverse;

//删除包含对象的引用

inquiry tp_clear;

//从2.1开始，富比较

richcmpfunc tp_richcompare;

//弱引用

long tp_weaklistoffset;

//从2.2开始，迭代器

getiterfunc tp_iter;

iternextfunc tp_iternext;

//属性描述符和子类支持

struct PyMethodDef *tp_methods;

struct PyMemberDef *tp_members;

struct PyGetSetDef *tp_getset;

struct _typeobject *tp_base;

PyObject *tp_dict;

descrgetfunc tp_descr_get;

descrsetfunc tp_descr_set;

long tp_dictoffset;

initproc tp_init;

allocfunc tp_alloc;

newfunc tp_new;

freefunc tp_free;

inquiry tp_is_gc;

PyObject *tp_bases;

PyObject *tp_mro;

PyObject *tp_cache;

PyObject *tp_subclasses;

PyObject *tp_weaklist;

} PyTypeObject;

这里有一大堆的方法，无需担心太多，通常只需要实现一部分。

接下来介绍各种对应的处理器。不会进入结构定义，因为这里一堆历史兼容问题，确保你的初始化按照正确的字段顺序。你可以参照该顺序，只是修改自己所需的。

char *tp_name; //for printing

类型的名字，有如上节所说，会在很多地方出现，选择个有帮助的。

int tp_basicsize, tp_itemsize; //for allocation

这些字段供内存分配。Python对变长对象有内置支持，需要用到 tp_itemsize 字段。

char *tp_doc;

存放一个字符串来供 obj.__doc__ 返回文档字符串。

现在回到基本类型方法。(by gashero)

2.2.1 销毁与释放

destructor tp_dealloc;

该函数在引用计数降低到0时调用。如果你的类型有需要释放的内存或其他要执行的清理，就将其放在这里。对象本身也需要在这里释放，一个例子:

static void

newdatatype_dealloc(newdatatypeobject *obj) {

free(obj->obj_UnderlyingDatatypePtr);

obj->ob_type->tp_free(obj);

}

需要关注的点是deallocator可能会遗留异常。当deallocator将异常放到栈中，可能无人会看到这个异常，而且这个异常未必来自于哪个deallocator。这可能导致难以调试的问题。正确的做法是将未决异常放到不安全的动作之前，并在完成时恢复。可以用 PyErr_Fetch() 和 PyErr_Restore() 函数:

static void my_dealloc(PyObject *obj) {

MyObject *self=(MyObject*)obj;

PyObject *cbresult;

if (self->my_callback!=NULL) {

PyObject *err_type, *err_value, *err_traceback;

int have_error=PyErr_Occurred() ? 1 : 0;

if (have_error)

PyErr_Fetch(&err_type, &err_value, &err_traceback);

cbresult=PyObject_CallObject(self->my_callback, NULL);

if (cbresult==NULL)

PyErr_WriteUnraisable(self->my_callback);

else

Py_DECREF(cbresult);

if (have_error)

PyErr_Restore(err_type, err_value, err_trackback);

Py_DECREF(self->my_callback);

}

obj->ob_type->tp_free((PyObject*)self);

}

2.2.2 对象表达

在Python里有三种方法生成对象的文本表示， repr() 函数、 str() 函数和 print 语句。对大多数对象， print 语句就等同于 str() 函数，但是其实可以指定打印到特定的 FILE* ，这对于打印到文件变得靠谱。

这三个处理器是可选的，常用类型只需要实现 tp_str 和 tp_repr 处理器即可:

reprfunc tp_repr;

reprfunc tp_str;

printfunc tp_print;

tp_repr 处理器应该返回一个字符串对象包含了实例的描述，简单的例子如:

static PyObject *newdatatype_repr(newdatatypeobject *obj) {

return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",

obj->obj_UnderlyingDatatypePtr->size);

}

如果没有提供 tp_repr 处理器，解释器会提供类型的 tp_name 和一个对象的唯一值。

tp_str 处理 str() 的请求， tp_repr 处理 repr() 的请求。这使得可以在对象上调用 str() 。实现类似于 tp_repr 函数，但是结果字符串应该是人类可读的。如果 tp_str 没有提供，就使用 tp_repr 处理器。

如下简单例子:

static PyObject *newdatatype_str(newdatatypeobject *obj) {

return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",

obj->obj_UnderlyingDatatypePtr->size);

}

而print功能会在需要打印实例时调用。例如，如果结点是TreeNode类型，则打印功能调用就是:

print node

还有个flags参数，只有个 Py_PRINT_RAW ，会假设无需字符串转义就打印。

打印函数接受一个文件对象作为第一个参数，你可以这样写数据到文件。

如下是例子:

static int

newdatatype_print(newdatatypeobject *obj, FILE *fp, int flags) {

if (flags & Py_PRINT_RAW) {

fprintf(fp, "<{newdatatype object--size: %d}>",

obj->obj_UnderlyingDatatypePtr->size);

} else {

fprintf(fp, "\"<{newdatatype object--size: %d}>\"",

obj->obj_UnderlyingDatatypePtr->size);

}

return 0;

}

2.2.3 属性管理

对每个需要支持属性的对象，其类型必须提供函数来控制属性如何被解析。这需要一个函数来获取属性，另一个用来设置属性。删除一个属性时特例，对应的新值是NULL。

Python支持两对属性处理器，一个类型支持属性成对处理。区别是一对接受属性名字为 char* ，而另一种接受 PyObject* 。每种类型都能实现更多便利:

getattrfunc tp_getattr;

setattrfunc tp_setattr;

/* ... */

getattrofunc tp_getattrofunc;

setattrofunc tp_setattrofunc;

如果访问属性总是简单操作，有个通用的实现可以用于提供 PyObject* 版本的属性管理。实际需要一个类型相关的属性处理器来实现，自Python2.2消失。因此有很多例子无需更新使用新的通用机制。

2.2.4 对象比较

@wait

2.2.5 抽象协议支持

Python支持一系列抽象协议，供Python C API的抽象对象层API来调用。

一些抽象接口是在Python早期定义的。数字、映射、序列协议已经成为Python的一部分。其他协议加入则较晚。每种协议需要实现多个接口，旧协议作为类型对象的可选块。新协议会添加槽到主类型对象，一个标志位指定这些槽是否应该被解释器检查。标志位不应该设置为NULL，而应该用于表示槽，而槽可以是未填充的。

PyNumberMethods tp_as_number;

PySequenceMethods tp_as_sequence;

PyMappingMethods tp_as_mapping;

如果你希望你的对象表现的像一个数字、序列、映射，你应该将实现的结构体地址填充上。可以到Python源码包里找到例子。

hashfunc tp_hash;

这个函数可选提供，会返回你对象类型的哈希数字。如下是一个例子:

static long

newdatatype_hash(newdatatypeobject *obj) {

long result;

result=obj->obj_UnderlyingDatatypePtr->size;

result=result*3;

return result;

}

ternaryfunc tp_call;

这个函数会被数据类型实例调用。例如obj1是你的数据类型的实例，而语句 obj1('hello') 就会调用 tp_call 。

函数接受3个参数：

arg1是数据类型实例，上例为 obj1
arg2是参数元组，通过 PyArg_ParseTuple() 来解析
arg3是关键字参数字典，通过 PyArg_ParseTupleAndKeywords() 来解析，不想支持就抛出 TypeError

如下例子实现了call函数:

static PyObject *

newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject kwds) {

PyObject *result;

char *arg1;

char *arg2;

char *arg3;

if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {

return NULL;

}

result=PyString_FromFormat(

"Returning -- value: [\%d] arg1: [\%s] arg2: [\%s] arg3: [\%s]\n",

obj->obj_UnderlyingDatatypePtr->size,

arg1, arg2, arg3);

printf("\%s", PyString_AS_STRING(result));

return result;

}

其他字段...。

getierfunc tp_iter;

iternextfunc tp_iternext;

这些函数提供了迭代器支持。任何对象想要支持迭代其内容，都应该实现 tp_iter 和 tp_iternext 处理器。两个处理器都接受一个参数，就是对象的实例，返回新的引用。如果发生错误，应该设置异常并返回NULL。

对于迭代器容器， tp_iter 处理器应该返回一个迭代器对象。迭代器对象用于管理迭代器的状态。容器可以支持多个迭代器，互相之间不影响，每次返回个新的迭代器即可。对象应该确保被迭代一次，实现者应该返回其本身新的引用，以及实现 tp_iternext 处理器。文件对象就是迭代器的例子。

tp_iternext 处理器返回下一个对象的新的引用。如果迭代器已经到达末尾，就应该返回NULL而不设置异常，或 StopIteration 异常，避免异常影响性能。如果发生了错误，就应该设置异常并返回NULL。

2.2.6 弱引用支持

@wait

2.2.7 更多建议

大部分函数都可以不提供，写为0即可。类型定义必须提供，在 object.h 中。

想要学习如何实现特定方法，就去解压Python源码包，进入 Objects 目录，搜索C源码 tp_ 前缀的即可。

当你想要验证一个对象是否实现了，可以使用 PyObject_TypeCheck() 函数，一个样例如下:

if (!PyObject_TypeCheck(some_object, &MyType)) {

PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");

return NULL;

}

3 使用distutils构建扩展

自从Python1.4开始就提供一个自动构建动态载入扩展模块和自定义解释器的make文件了。自动2.0开始，这个机制不再被支持。构建自定义解释器很少用到，而构建扩展模块则更多的使用了distutils。

使用distutils构建扩展模块需要的distutils已经是Python2.x中的标准组成。distutils也同时支持二进制包，而用户并不一定需要一个编译器来安装扩展模块。

一个distutils包包含一个驱动脚本 setup.py 。这个纯Python文件一般形式如下:

from distutils.core import setup,Extension

module1=Extension('demo',sources=['demo.c'])

setup(name='PackageName',

version='1.0',

description='This is a demo package',

ext_modules=[module1])

包含一个setup.py和一个demo.c，运行:

python setup.py build

将会编译demo.c，并会在build目录下产生一个"demo"扩展模块。依赖于系统，模块会在一个子目录build/lib.system中，并把名字叫做demo.so或demo.pyd。

在setup.py，所有执行操作依靠 setup() 函数的调用。接受一大堆关键字参数，上面的例子只是使用了一些子集。一般来说，要指明包的内容。还要指明包含附加模块，有如Python源码模块，文档，子包等。参考distutils了解更多。本章只是描述构建扩展模块的基础而已。

最好把需要填入 setup() 的参数先计算好再填入，有如上面的 ext_modules 参数就是如此。例子中，这个实例定义了一个叫做"demo"的扩展模块。

在很多情况下，构建扩展模块比较复杂，包含很多预处理指令和链接库。下面示范了一下:

from distutils.core import setup,Extension

module1=Extension('demo',

define_macros=[('MAJOR_VERSION','1'),

('MINOR_VERSION','0'),

]

include_dirs=['/usr/local/lib',],

libraries=['tcl83'],

library_dirs=['/usr/local/lib',],

sources=['demo.c',])

setup(name='PackageName',

version='1.0',

description='This is a demo package',

author='Martin v. Loewis',

author_email='[email protected]',

url='http://www.python.org/doc/current/ext/building.html',

long_description='long description',

ext_modules=[module1])

这个例子里面，setup附带了很多参数，指定了预处理定义，各类文件夹等。依赖于编译器，distutils用不同的方法传递信息。例如，在UNIX上，可能的结果如下:

gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 \

-DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 \

-c demo.c -o build/temp.linux-i686-2.2/demo.o

gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 \

-o build/lib.linux-i686-2.2/demo.so

当然，这些行只是用于演示，你应该相信distutils会做出正确的判断。

3.1 发布你的扩展模块

扩展模块构建完成之后，你可以用三种方法使用。

最终用户可以直接安装模块，如:

python setup.py install

模块发行人员可以发布源码包:

python setup.py sdist

在某些情况下，附加文件需要加入到源码包里面，这通过 MANIFEST.in 文件实现，查看distutils的文档。

如果源码发行版构建成功，模块发行人员还可以创建二进制发行版，依赖于具体平台，可以用如下:

python setup.py bdist_wininst

python setup.py bdist_rpm

python setup.py bdist_dumb

4 在Windows构建扩展

本章解释如何在Windows下使用VC++创建Python扩展(by gashero)，并给出一些背景资料解释如何运行。这些知识对大家都有用。

模块作者一般推荐使用distutils来构造扩展模块，而不是本章所描述的。但是你仍然需要有个C编译器，这里就是VC++。

Note

本章提到的一些文件名可能包含Python版本号。这些文件名带有2位数字的版本号，分别为主版本号和次版本号。。例如Python2.2.1的这2个数字就是22。

4.1 照着菜谱走猫步(a cookbook approach)

在Windows上编译扩展有两种方式，有如Unix上一样：用distutils或者手动。使用distutils方式对大多数模块工作的很好，可以参考distutils的手册。本节仅介绍手动编译C/C++编写的Python扩展模块。

要构建扩展模块，你首先要拥有与你版本相同的Python源码，你还需要一个VC++，工程文件是供VC++ 7.1使用的，但是你也可以使用老版本的VC++。注意的是，你必须使用编译Python相同版本的VC++来编译扩展模块。例子文件 PC\example_nt\ 描述了一个例子。

复制例子文件
把那个文件夹拷出来，以防玷污了那个文件夹。
打开工程
在VC++中打开工程文件example.sln。
构建例子的DLL
为了检查是否OK了，可以尝试先构建一下：

选择一个配置文件，Release或Debug，默认为Debug。
构建DLL，就是Build一下。

测试debug模式的DLL
得到了调试构建以后，就可以在DLL所在的文件夹下打开Python解释器:
C>..\..\PCbuild\python_d
Adding parser accelerators ...
Done.
Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32
Type "copyright", "credits" or "license" for more information.
>>> import example
[4897 refs]
>>> example.foo()
Hello, world
[4903 refs]
>>>
恭喜，你已经成功的构建了这个扩展模块。
创建自己的工程
创建一个目录，然后把这些源文件拷进去。文件名并不一定需要与模块名有什么必然联系，但是模块的初始化函数必须与模块名相关-你可以导入 spam 依赖于初始化函数名为 initspam() ，并且他会调用 Py_InitModule() 函数，并传递 spam 这个名字作为首参数。只是按照习俗，它一般是在spam.c或者spammodule.c中。输出文件可以叫做 spam.dll 或 spam.pyd (后一种.pyd方式是为了防止与系统DLL文件重名导致混乱)。调试模式的文件名为 spam_d.dll 或 spam_d.pyd 。
现在你可以拷贝原工程文件后修改或重新创建一个新的工程。
同时还要拷贝 example_nt\example.def 到 spam\spam.def ，然后修改 spam.def 的第二行包含 initspam 。如果创建了新工程则需要自己添加 spam.def 文件，别怕这个文件就2行。另一个方法是根本不去创建.def文件，而是添加 /export:initspam 到连接器选项，可以手动修改工程配置。
创建全新工程
创建一个VC++工作空间，选择VC++ -> Win32 -> Win32 Project，然后选择工程名和存放路径，确保存放路径与刚才的那个路径相同，在Python源码树中，就是在PC目录下，并且有相同的Include路径设置。选择Win32平台，然后OK。
你现在就可以创建 spam.def 了，然后添加源文件，添加进来 spam.c 和 spam.def 然后就是OK了。
打开工程选项。确保每个需要定制的位置都修改好。需啊则C/C++这个TAB页面，选择通用范畴的弹出菜单，输入如下附加的Include路径:
..\Include,..\PC
然后修改通用范畴的连接器TAB页面，然后输入:
..\PCbuild
另外还需要一些其他设置。在Release配置页的连接TAB页，选择输入框，然后添加 pythonXX.lib 到附加依赖框(Additional Dependencies)。
选择Debug配置页的也同样添加 pythonXY_d.lib 文件到附加依赖。然后选择C/C++的TAB页，选择代码生成，选择"Multi-threaded Debug DLL"选项作为运行时。
选择Release页面同样选择多线程DLL运行时。

如果你的模块创建了新的类型，你可能在这一行碰钉子:

PyObject_HEAD_INIT(&PyType_Type)

需要改成:

PyObject_HEAD_INIT(NULL)

并且添加如下到模块初始化函数中:

MyObject_Type.ob_type=&PyType_Type;

参考Python FAQ的第三节了解更多。

4.2 Unix与Windows的不同

Unix与Windows在载入运行时代码方面完全不同。

在Unix，动态载入的代码包含在共享对象文件(.so)中。当这个文件载入时，程序会自动在内存中重新定位函数和数据的位置。这是基本的动态连接操作。

在Windows，动态载入代码包含在动态链接库当中(.dll)。(by gashero)获取这些函数的地址需要一个查找表，所以DLL代码的指针并不需要运行时重定位；而是在代码表中填入已经重定位的函数和数据地址。

在Unix中，只有一种链接库(.a)，包含一些目标文件(.o)。当链接用于创建共享对象文件(.so)时，连接器会查找标识符的位置。然后会在最终的.so文件包含所有标识符的定义。

在Windows，有两种库。静态库和导入库(尽管都叫做.lib)。静态库有如Unix的.a文件，包含重要代码。导入库仅仅使用连接器提供的标识符，也就是加载时提供的查找表。所以连接器使用导入库构建查找表。

如果你想构建两种动态载入模块，B和C，并可能共享代码块A。在Unix你需要传递A.a到B.so和C.so的连接过程，这会导致两次包含，B和C都包含他们自己对A的拷贝。在Windows，构造一个A.dll同时会构造一个A.lib。你可以传递A.lib到连接器B和C。A.lib并不包含代码，仅包含A代码的运行时查找表。

在Windows，使用导入库有如 import spam ，给出要导入的名字，但是并不创建一个单独的拷贝。在Unix，连接一个静态库更像是 from spam import * ，他包含单独的拷贝。

4.3 实践中使用DLL

Windows Python基于VC++构建，使用其他编译器可能不会工作，下面都是基于VC++讲解。

当在Windows下创建DLL时，你必须传递pythonXY.lib到连接器。来构建两个DLL，spam和ni(在spam中使用的C函数)，你可以使用如下命令:

cl /LD /I/python/include spam.c ../libs/pythonXY.lib

cl /LD /I/python/include ni.c spam.lb ../libs/pythonXY.lib

第一个命令生成3个文件 spam.obj 、 spam.dll 、 spam.lib 。其中 spam.dll 并不包含Python函数(比如 PyArg_ParseTuple() )，但是它依赖 pythonXY.lib 知道如何去找到这些Python代码。

第二个命令创建了 ni.dll (和附带的.obj和.lib)，他知道如何找到spam的函数定义，并且可以找到Python的执行。

并不是所有的标识符都会导出到查找表。如果你想要Python看到你的标识符，就需要以 _declspec(dllexport) 来前缀声明，比如 void _declspec(dllexport) initspam(void) 或 PyObject _declspec(dllexport) *NiGetSpamData(void) 。

VC++会导入一大堆你并不需要的库，增加超过100KB的文件尺寸，想要扔掉这些导入，打开工程属性对话框的Link页面，忽略缺省导入库。添加必须的 msvcrtxx.lib 到库列表就可以了。

5 嵌入Python到其他应用

前面的章节讨论如何扩展Python，如何生成适合的C库等。不过还有另一种情况：通过将Python嵌入C/C++应用以扩展程序的功能。Python嵌入实现了一些使用Python更合适的功能。这可以有很多用途，一个例子是允许用户裁减需要的Python功能。也可以用于默写使用Python编写更加方便的功能。

嵌入Python与扩展很像。扩展Python时，主程序是Python解释器，但是嵌入Python则主程序并不是Python的-是程序的其他部分调用Python来实现一些功能。

所以，如果要嵌入Python，你可以提供自己的主程序，这个主程序需要初始化Python解释器。至少需要调用函数 Py_Initialize() (对于MacOS，调用 PyMac_Initialize())。可以选择是否传入命令行参数到Python。然后你就可以在应用的任何地方调用Python解释器了。

有几种方法调用解释器：可以传递一个包含Python语句的字符串到 PyRun_SimpleString() ，也可以传递一个stdio文件指针和一个文件名(用于识别错误信息)到 PyRun_SimpleFile() 。你也可以调用前几章介绍的底层操作直接控制Python对象。

可以在目录 Demo/embed/ 中找到嵌入Python的例子。

5.1 高层次嵌入

嵌入Python最简单的形式是使用高层次的接口。这个接口专门用于执行Python脚本，而不需要与应用程序直接交互。例子可以在一个文件中展示:

#include

int

main(int argc, char* argv[]) {

Py_Initialize();

PyRun_SimpleString("from time import time,ctime\n"

"print 'Today is',ctime(time())\n");

Py_Finalize();

return 0;

}

如上代码首先使用 Py_Initialize() 初始化Python解释器，随后执行硬编码中的Python脚本来打印日期和时间。最后 Py_Finalize() 关闭了解释器。在真实应用中，你可能希望从其他方式获取Python脚本，文件、编辑器、数据库等。从文件获取的方式更适合使用 PyRun_SimpleFile() 函数，可以省去分配内存空间和载入文件的麻烦。

5.2 超越高层嵌入：预览

高层次的接口可以方便的执行Python代码，但是交换数据就很麻烦。如果需要，你可以使用低层次的接口调用。虽然多写一些C代码，但是却可以完成很多功能。

仍然要提醒的是，Python的扩展与嵌入其实很像，尽管目的不同。前几章讨论的大多数问题在这里也同样适用。可以参考用C扩展Python时一些步骤：

转换Python类型到C类型
传递参数并调用C函数
转换返回值到Python

当嵌入Python时，接口需要做：

转换C数据到Python
调用Python接口程序来调用Python函数
转化返回值到C

有如你所见，数据转换的步骤用于跨语言的数据交换。唯一的不同是两次数据转换之间调用的函数。当扩展时，你调用C函数，当嵌入时，调用Python函数。

这一章不会讨论Python和C之间的数据转换。并且假设你会使用手册来处理错误，自此只会讨论与扩展解释器不同的部分，你可以到前面的章节找到需要的信息。

5.3 纯扩展

第一个程序是执行一段Python脚本中的函数。有如高层接口一节，Python解释器并不会自动与程序结合。

运行一段Python脚本中的函数的代码如下:

#include

int

main(int argc, char *argv[])

{

PyObject *pName, *pModule, *pDict, *pFunc;

PyObject *pArgs, *pValue;

int i;

if (argc < 3) {

fprintf(stderr,"Usage: call pythonfile funcname [args]\n");

return 1;

}

Py_Initialize();

pName = PyString_FromString(argv[1]);

/* Error checking of pName left out */

pModule = PyImport_Import(pName);

Py_DECREF(pName);

if (pModule != NULL) {

pFunc = PyObject_GetAttrString(pModule, argv[2]);

/* pFunc is a new reference */

if (pFunc && PyCallable_Check(pFunc)) {

pArgs = PyTuple_New(argc - 3);

for (i = 0; i < argc - 3; ++i) {

pValue = PyInt_FromLong(atoi(argv[i + 3]));

if (!pValue) {

Py_DECREF(pArgs);

Py_DECREF(pModule);

fprintf(stderr, "Cannot convert argument\n");

return 1;

}

/* pValue reference stolen here: */

PyTuple_SetItem(pArgs, i, pValue);

}

pValue = PyObject_CallObject(pFunc, pArgs);

Py_DECREF(pArgs);

if (pValue != NULL) {

printf("Result of call: %ld\n", PyInt_AsLong(pValue));

Py_DECREF(pValue);

}

else {

Py_DECREF(pFunc);

Py_DECREF(pModule);

PyErr_Print();

fprintf(stderr,"Call failed\n");

return 1;

}

else {

if (PyErr_Occurred())

PyErr_Print();

fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);

}

Py_XDECREF(pFunc);

Py_DECREF(pModule);

}

else {

PyErr_Print();

fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);

return 1;

}

Py_Finalize();

return 0;

}

这段代码从argv[1]中载入Python脚本，并且调用argv[2]中的函数，整数型的参数则是从argv数组后面得来的。如果编译和链接这个程序，执行如下脚本:

def multiply(a,b):

print "Will compute",a,"times",b

c=0

for i in range(0,a)

c=c+b

return c

结果将是:

$ call multiply multiply 3 2

Will compute 3 times 2

Result of call: 6

虽然这个程序的代码挺多的，但是大部分其实都是做数据转换和错误报告。主要关于嵌入Python的开始于:

Py_Initialize();

pName=PyString_FromString(argv[1]);

/* Error checking of pName left out */

pModule=PyImport_Import(pName);

初始化解释器之后，使用 PyImport_Import() 导入模块。这个函数需要字符串作为参数，使用 PyString_FromString() 来构造:

pFunc=PyObject_GetAttrString(pModule,argv[2]);

/* pFunc is a new reference */

if (pFunc && PyCallable_Check(pFunc)) {

...

}

Py_XDECREF(pFunc);

载入了模块以后，就可以通过 PyObject_GetAttrString() 来获取对象。如果名字存在并且可以执行则可以安全的调用它。程序随后构造参数元组，然后执行调用:

pValue=PyObject_CallObject(pFunc,pArgs);

函数调用之后，pValue要么是NULL，要么是返回值的对象引用。注意在检查完返回值之后要释放引用。

5.4 扩展嵌入的Python

至今为止，嵌入的Python解释器还不能访问应用程序本身的功能。Python的API允许扩展嵌入的Python的解释器。所以，Python可以获得其所嵌入的程序的功能。这听起来挺麻烦的，其实并不是那样。只要简单的忘记是应用程序启动了Python解释器。

可以把程序看作一对功能的集合，可以写一些胶水代码来来让Python访问这些功能，有如你在写一个普通的Python扩展一样。例如:

static int numargs=0;

/* Return the number of arguments of the application command line */

static PyObject*

emb_numargs(PyObject *self, PyObject *args)

{

if(!PyArg_ParseTuple(args, ":numargs"))

return NULL;

return Py_BuildValue("i", numargs);

}

static PyMethodDef EmbMethods[] = {

{"numargs", emb_numargs, METH_VARARGS,

"Return the number of arguments received by the process."},

{NULL, NULL, 0, NULL}

};

添加上面的代码到 main() 函数。同样，插入如下两个语句到 Py_Initialize() 函数之后:

numargs=argc;

Py_InitModule("emb",EmbMethods);

这两行代码初始化numargs变量，(by gashero)并且使得 emb.numargs() 函数更加易于被Python嵌入的解释器所理解。通过这个扩展，Python脚本可以做如下事情:

import emb

print "Number of arguments",emb.numargs()

在实际的应用程序中，方法需要导出API以供Python使用。

5.5 在C++中嵌入Python

有时候需要将Python嵌入到C++程序中，而你必须有一些要注意的C++系统的细节，一般来说你要为这个程序写一个main()函数，然后使用C++编译器来编译和链接程序。而这里不需要因为使用C++而重新编译Python本身。

5.6 链接必备条件

当 configure 脚本执行时，可以正确的生成动态链接库使用的导出符号，而这些却不会自动被嵌入的静态链接的Python所继承，至少是在Unix。这是用于静态链接运行库(libpython.a)并且需要载入动态扩展(.so)的方式。

问题是一些入口点是使用Python运行时定义的而仅供扩展模块使用。如果嵌入应用不使用任何这些入口点，一些链接器不会包含这些实体到最终可执行文件的符号表(by gashero)。一些附加的选项可以用于告知连接器不要删除这些符号。

对于不同的平台，想要正确的检测该使用何种参数是非常困难的，但是幸运的是Python配置好了这些值。只要通过已经安装的Python解释器，启动交互解释器然后执行如下会话即可:

>>> import distutils.sysconfig

>>> distutils.sysconfig.get_config_var('LINKFORSHARED')

'-Xlinker -export-dynamic'

字符串的内容就是生成的选项。如果字符串为空，则不需要任何的附加选项。LINKFORSHARED的定义与Python顶层Makefile中的同名变量相同。

扩展和嵌入Python解释器 Extending and Embedding the Python Interpreter

你可能感兴趣的:(扩展和嵌入Python解释器 Extending and Embedding the Python Interpreter)