Extending and Embedding the Python Interpreter(一)

Let's create an extension module called "spam" (the favorite food of Monty Python fans...) and let's say we want to create a Python interface to the C library function system().This function takes a null-terminated character string as argument and returns an integer. We want this function to be callable from Python as follows:

 

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

现在我们为C语言编写的库函数system实现一个python接口，使用方式如上述代码所示

Begin by creating a file spammodule.c. (Historically, if a module is called "spam", the C file
containing its implementation is called spammodule.c; if the module name is very long, like
"spammify", the module name can be just spammify.c.) 

创建一个名为spammodule.c的文件。

 

The first line of our file can be:

 

#include <python.h></python.h>

which pulls in the Python API (you can add a comment describing the purpose of the module and a copyright notice if you like).

在spammodule.c文件的开头加入 #include <python.h></python.h> ，它的作用是将python API导入；必须先于其它标准头文件导入python API。

All user-visible symbols defined by Python.h have a prefix of "Py" or "PY", except those defined in standard header files. For convenience, and since they are used extensively by the Python interpreter, "Python.h" includes a few standard header files: stdio.h, string.h, errno.h, and stdlib.h<stdlib.h></stdlib.h>. If the latter header file does not exist on your system, it declares the functions malloc(), free() and realloc() directly

在python.h头文件中已经include <stdio.h></stdio.h>stdio.h, string.h, errno.h, 和stdlib.h<stdlib.h></stdlib.h>几个头文件。

The next thing we add to our module file is the C function that will be called when the Python expression "spam.system(string)"is evaluated (we'll see shortly how it ends up being called):

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

There is a straightforward translation from the argument list in Python (for example, the single expression "ls -l") to the arguments passed to the C function. The C function always has two arguments, conventionally named self and args.

C语言编写得函数通常有两个参数self和args。

The self argument is only used when the C function implements a built-in method, not a function. In the example, self will always be a NULL pointer, since we are defining a function, not a method. (This is done so that the interpreter doesn't have to understand two different types of C functions.)

self参数只在C语言编写得函数用来实现方法时使用，实现为函数时不使用。在这个例子中，self始终是指向NULL的指针。

The args argument will be a pointer to a Python tuple object containing the arguments. Each item of the tuple corresponds to an argument in the call's argument list. The arguments are Python objects -- in order to do anything with them in our C function we have to convert them to C values. The function PyArg_ParseTuple() in the Python API checks the argument types and converts them to C values. It uses a template string to determine the required types of the arguments as well as the types of the C variables into which to store the converted values. More about this later.

args参数是一个指向python tuple对象的指针，这个tuple对象包含所有的参数。这些对象都是python对象，当我们要在C代码中操作这些对象时我们需要将这些对象转化为C对象。python api中的PyArg_ParseTuple()函数用来检查这些对象的类别并将它们转化为C对象。

PyArg_ParseTuple() returns true (nonzero) if all arguments have the right type and its components have been stored in the variables whose addresses are passed. It returns false (zero) if an invalid argument list was passed. In the latter case it also raises an appropriate exception so the calling function can return NULL immediately (as we saw in the example).

如果所有的参数都有正确的类别并且被存储进设定的变量中，那么PyArg_ParseTuple() 函数返回true。如果有无效参数，那么该函数返回false。