1.12.给扩展模块提供C API¶

很多扩展模块提供了新的函数和类型供Python使用，但有时扩展模块里的代码也可以被其他扩展模块使用。例如，一个扩展模块可以实现一个类型 "collection" 看起来是没有顺序的。就像是Python列表类型，拥有C API允许扩展模块来创建和维护列表，这个新的集合类型可以有一堆C函数用于给其他扩展模块直接使用。

开始看起来很简单：只需要编写函数(无需声明为 static )，提供恰当的头文件，以及C API的文档。实际上在所有扩展模块都是静态链接到Python解释器时也是可以正常工作的。当模块以共享库链接时，一个模块中的符号定义对另一个模块不可见。可见的细节依赖于操作系统，一些系统的Python解释器使用全局命名空间(例如Windows)，有些则在链接时需要一个严格的已导入符号列表(一个例子是AIX)，或者提供可选的不同策略(如Unix系列)。即便是符号是全局可见的，你要调用的模块也可能尚未加载。

可移植性需要不能对符号可见性做任何假设。这意味着扩展模块里的所有符号都应该声明为 static ，除了模块的初始化函数，来避免与其他扩展模块的命名冲突(在段落 模块方法表和初始化函数 中讨论) 。这意味着符号应该 必须 通过其他导出方式来供其他扩展模块访问。

Python提供了一个特别的机制来传递C级别信息(指针)，从一个扩展模块到另一个：Capsules。一个Capsule是一个Python数据类型，会保存指针( void * )。Capsule只能通过其C API来创建和访问，但可以像其他Python对象一样的传递。通常，我们可以指定一个扩展模块命名空间的名字。其他扩展模块可以导入这个模块，获取这个名字的值，然后从Capsule获取指针。

Capsule可以用多种方式导出C API给扩展模块。每个函数可以用自己的Capsule，或者所有C API指针可以存储在一个数组里，数组地址再发布给Capsule。存储和获取指针也可以用多种方式，供客户端模块使用。

无论你选择哪个方法，正确地为你的 Capsule 命名都很重要。 函数 PyCapsule_New() 接受一个名称形参 (const char *)；允许你传入一个 NULL 作为名称，但我们强烈建议你指定一个名称。 正确地命名的 Capsule 提供了一定程序的运行时类型安全；没有可行的方式能区分两个未命名的 Capsule。

通常来说，Capsule用于暴露C API，其名字应该遵循如下规范：

modulename.attributename

便利函数 PyCapsule_Import() 可以方便的载入通过Capsule提供的C API，仅在Capsule的名字匹配时。这个行为为C API用户提供了高度的确定性来载入正确的C API。

如下例子展示了将大部分负担交由导出模块作者的方法，适用于常用的库模块。其会存储所有C API指针(例子里只有一个)在 void 指针的数组里，并使其值变为Capsule。对应的模块头文件提供了宏来管理导入模块和获取C API指针；客户端模块只需要在访问C API前调用这个宏即可。

导出的模块修改自 spam 模块，来自 一个简单的例子 段落。函数 spam.system() 不会直接调用C库函数 system() ，但一个函数 PySpam_System() 会负责调用，当然现实中会更复杂些(例如添加 "spam" 到每个命令)。函数 PySpam_System() 也会导出给其他扩展模块。

函数 PySpam_System() 是个纯C函数，声明 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 PyLong_FromLong(sts);

}

在模块开头，在此行后:

#include

添加另外两行:

#define SPAM_MODULE

#include "spammodule.h"

#define 用于告知头文件需要包含给导出的模块，而不是客户端模块。最终，模块的初始化函数必须负责初始化C API指针数组:

PyMODINIT_FUNC

PyInit_spam(void)

{

PyObject *m;

static void *PySpam_API[PySpam_API_pointers];

PyObject *c_api_object;

m = PyModule_Create(&spammodule);

if (m == NULL)

return NULL;

/* 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);

return NULL;

}

return m;

}

注意 PySpam_API 声明为 static ；此外指针数组会在 PyInit_spam() 结束后消失!

头文件 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 on error, 0 on success.

* PyCapsule_Import will set an exception if there's an error.

*/

static int

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

客户端模块必须在其初始化函数里按顺序调用函数 import_spam() (或其他宏)才能访问函数 PySpam_System() 。

PyMODINIT_FUNC

PyInit_client(void)

{

PyObject *m;

m = PyModule_Create(&clientmodule);

if (m == NULL)

return NULL;

if (import_spam() < 0)

return NULL;

/* additional initialization can happen here */

return m;

}

这种方法的主要缺点是，文件 spammodule.h 过于复杂。当然，对每个要导出的函数，基本结构是相似的，所以只需要学习一次。

最后需要提醒的是Capsule提供了额外的功能，用于存储在Capsule里的指针的内存分配和释放。细节参考 Python/C API参考手册的章节 胶囊 和Capsule的实现(在Python源码发行包的 Include/pycapsule.h 和 Objects/pycapsule.c )。

备注

这个函数的接口已经在标准模块 os 里了，这里作为一个简单而直接的例子。

术语"借用"一个引用是不完全正确的：拥有者仍然有引用的拷贝。

检查引用计数至少为1 没有用 ，引用计数本身可以在已经释放的内存里，并有可能被其他对象所用。

当你使用 "旧式" 风格调用约定时，这些保证不成立，尽管这依旧存在于很多旧代码中。