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")
Begin by creating a file `spammodule.c'. (In general, 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
'.)
The first line of our file can be:
#include "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).
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>
. If the latter header file does not exist on your
system, it declares the functions malloc()
, free()
and
realloc()
directly.
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(self, args) PyObject *self; PyObject *args; { 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 (e.g. 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.
The self argument is only used when the C function implements a
builtin method. This will be discussed later. 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.)
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.
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 by so the calling function can return
NULL
immediately (as we saw in the example).