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'.)

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 INCREF() it!) in a global variable - or whereever you see fit. For example, the following function might be part of a module definition:

    static object *my_callback = NULL;

    static object *
    my_set_callback(dummy, arg)
        object *dummy, *arg;
    {
        XDECREF(my_callback); /* Dispose of previous callback */
        my_callback = arg;
        XINCREF(my_callback); /* Remember new callback */
        /* Boilerplate for "void" return */
        INCREF(None);
        return None;
    }

This particular function doesn't do any typechecking on its argument - that will be done by call_object(), which is a bit late but at least protects the Python interpreter from shooting itself in its foot. (The problem with typechecking functions is that there are at least five different Python object types that can be called, so the test would be somewhat cumbersome.)

The macros XINCREF() and XDECREF() increment/decrement the reference count of an object and are safe in the presence of NULL pointers. More info on them in the section on Reference Counts below.

Later, when it is time to call the function, you call the C function call_object(). 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, you must pass an empty tuple. For example:

    object *arglist;
    object *result;
    ...
    /* Time to call the callback */
    arglist = mktuple(0);
    result = call_object(my_callback, arglist);
    DECREF(arglist);

call_object() returns a Python object pointer: this is the return value of the Python function. call_object() 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 DECREF()-ed immediately after the call.

The return value of call_object() 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 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 call_object() 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 err_clear(). For example:

    if (result == NULL)
        return NULL; /* Pass error back */
    /* Here maybe use the result */
    DECREF(result);

Depending on the desired interface to the Python callback function, you may also have to provide an argument list to call_object(). 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 mkvalue(). For example, if you want to pass an integral event code, you might use the following code:

    object *arglist;
    ...
    arglist = mkvalue("(l)", eventcode);
    result = call_object(my_callback, arglist);
    DECREF(arglist);
    if (result == NULL)
        return NULL; /* Pass error back */
    /* Here maybe use the result */
    DECREF(result);

Note the placement of DECREF(argument) immediately after the call, before the error check! Also note that strictly spoken this code is not complete: mkvalue() may run out of memory, and this should be checked.