《扩展和嵌入python解释器》1.1 一个简单的例子

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

1.1 一个简单的例子

让我们创建一个名叫 "spam" （这是Python粉丝Monty喜爱的食物）的扩展模块，我们打算创建一个Python接口，使用C库函数 system().^1.1 这个函数以一个空字符结尾（null-terminated）的字符串作为参数，并返回一个整型数，我们想这个功能够象下面这样从Python调用：

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

首先创建文件 spammodule.c. （一般地，如果模块名为"spam", C它的实现文件名应为 spammodule.c; 如果模块名很长, 如"spammify", 模块名可以为 spammify.c ） .)

我们文件的第一行应为：

#include <Python.h>

这样就引入了Python API（如果你喜欢，可以增加描述模块的目的和版权信息）。

警告: 由于Python可能定义了一些预处理定义，在一些系统上，这些预处理可能影响标准头文件，你最好在包含任何标准头文件前包含 Python.h文件。

除了那些定义在标准头文件中的用户可见的符号，其他所有在 Python.h文件中定义的用户可见符号有 "Py" or "PY"前缀。为方便起见，也由于它们被Python解释器广泛使用， "Python.h"包含几个标准头文件 <stdio.h>, <string.h>, <errno.h>, and <stdlib.h> 。如果后几个头文件在你的系统上不存在，需要直接声明malloc(), free() 和realloc() malloc(), free() and realloc() 函数。

接着，我们继续向模块文件添加C函数，在Python表达式。 "spam.system(string) "被计算时，这个C函数将被调用：

这是从Python参数列表（如：单个表达式 "ls -l"）到直接翻译为C函数参数。C函数总是有两个参数，一般命名为self 和 args 。

self参数只有当C函数实现内置方法使用，而实现函数时不使用。在本例中，由于我们定义的是一个函数而不是方法，self 总是一个NULL 指针(这样做可以使解释器不必关心两种C函数的不同)。

args 参数是一个指向包含参数的Python元组对象指针。元组的每个条目对应于调用参数列表的一个参数。参数是Python对象――为了在我们的C函数里使用他们，我们必须把它们转换为C值。Python API函数PyArg_ParseTuple() 检查参数类型并把它们转换为C值。它使用一个模板字符串来确定的参数类型和转换后的值存入C变量的类型，后面详述。

如果所有参数都是正确的类型，并且参数代表的各元素都被存储到传入地址的变量中，则PyArg_ParseTuple()函数返回为true（非零）。如果无效的参数被传入，函数返回false(零)。在后面的例子中，PyArg_ParseTuple也产生一个恰当的异常，于是调用函数立刻返回 NULL （正如我们在例子中看到的）。