GNU Info

(python2.1-ext.info)Calling Python Functions from C

---

Next: Extracting Parameters in Extension Functions Prev: Compilation and Linkage Up: Extending Python with C or C++

---

Enter node , (file) or (file)node

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(dummy, args)
         PyObject *dummy, *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 Note: Module's Method
Table and Initialization Function, "The Module's Method Table and
Initialization Function."  The `PyArg_ParseTuple()' function and its
arguments are documented in section Note: Extracting Parameters in
Extension Functions, "Format Strings for `PyArg_ParseTuple()'."

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 Note: Reference Counts, "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.