1.6 Calling Python Functions from C
So far we have concentrated on making C functions callable from Python. The reverse is also
useful: calling Python functions from C. This is especially the case for libraries that
support so-called ``callback'' functions. If a C interface makes use of callbacks, the
equivalent Python often needs to provide a callback mechanism to the Python programmer; the
implementation will require calling the Python callback functions from a C callback. Other
uses are also imaginable.
Fortunately, the Python interpreter is easily called recursively, and there is a standard
interface to call a Python function. (I won't dwell on how to call the Python parser with a
particular string as input -- if you're interested, have a look at the implementation of the -c command line option in Python/pythonmain.c
from the Python source code.)
Calling a Python function is easy. First, the Python program must somehow pass you the
Python function object. You should provide a function (or some other interface) to do this.
When this function is called, save a pointer to the Python function object (be careful to Py_INCREF() it!) in a global variable -- or wherever you see fit. For
example, the following function might be part of a module definition:
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); /* Add a reference to new callback */
Py_XDECREF(my_callback); /* Dispose of previous callback */
my_callback = temp; /* Remember new callback */
/* Boilerplate to return "None" */
Py_INCREF(Py_None);
result = Py_None;
}
return result;
}
This function must be registered with the interpreter using the METH_VARARGS
flag; this is described in section 1.4, ``The
Module's Method Table and Initialization Function.'' The PyArg_ParseTuple()
function and its arguments are documented in section 1.7,
``Extracting Parameters in Extension Functions.''
The macros Py_XINCREF() and Py_XDECREF()
increment/decrement the reference count of an object and are safe in the presence of NULL pointers (but note that temp will not be NULL in this context). More info on them in section 1.10, ``Reference Counts.''
Later, when it is time to call the function, you call the C function PyEval_CallObject().
This function has two arguments, both pointers to arbitrary Python objects: the Python
function, and the argument list. The argument list must always be a tuple object, whose length
is the number of arguments. To call the Python function with no arguments, pass an empty tuple;
to call it with one argument, pass a singleton tuple. Py_BuildValue()
returns a tuple when its format string consists of zero or more format codes between
parentheses. For example:
int arg;
PyObject *arglist;
PyObject *result;
...
arg = 123;
...
/* Time to call the callback */
arglist = Py_BuildValue("(i)", arg);
result = PyEval_CallObject(my_callback, arglist);
Py_DECREF(arglist);
PyEval_CallObject() returns a Python object pointer: this is the
return value of the Python function. PyEval_CallObject() is
``reference-count-neutral'' with respect to its arguments. In the example a new tuple was
created to serve as the argument list, which is Py_DECREF()-ed
immediately after the call.
The return value of PyEval_CallObject() is ``new'': either it is
a brand new object, or it is an existing object whose reference count has been incremented.
So, unless you want to save it in a global variable, you should somehow Py_DECREF()
the result, even (especially!) if you are not interested in its value.
Before you do this, however, it is important to check that the return value isn't NULL. If it is, the Python function terminated by raising an exception.
If the C code that called PyEval_CallObject() is called from
Python, it should now return an error indication to its Python caller, so the interpreter can
print a stack trace, or the calling Python code can handle the exception. If this is not
possible or desirable, the exception should be cleared by calling PyErr_Clear().
For example:
if (result == NULL)
return NULL; /* Pass error back */
...use result...
Py_DECREF(result);
Depending on the desired interface to the Python callback function, you may also have to
provide an argument list to PyEval_CallObject(). In some cases the
argument list is also provided by the Python program, through the same interface that
specified the callback function. It can then be saved and used in the same manner as the
function object. In other cases, you may have to construct a new tuple to pass as the argument
list. The simplest way to do this is to call Py_BuildValue(). For
example, if you want to pass an integral event code, you might use the following code:
PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
result = PyEval_CallObject(my_callback, arglist);
Py_DECREF(arglist);
if (result == NULL)
return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
Note the placement of "Py_DECREF(arglist)" immediately
after the call, before the error check! Also note that strictly spoken this code is not
complete: Py_BuildValue() may run out of memory, and this should be
checked.
|
