Python Cookbook

Returning None from a Python-Callable C Function

Credit: Alex Martelli

Problem

Your C-coded, Python-callable function in an extension module needs to return nothing in particular (i.e., a Python None), but it must, of course, do so without messing up reference counts.

Solution

Suppose we need an empty, C-coded function equivalent to Python:

def empty1(*args):
    pass

or, identically:

def empty2(*args):
    return None

there is still a right and a wrong way to solve the problem. The wrong way messes up reference counts:

static PyObject*
empty3(PyObject* self, PyObject* args)
{
    return Py_None;
}

But it’s not hard to do it right. Here is the simplest way:

static PyObject*
empty4(PyObject* self, PyObject* args)
{
    return Py_BuildValue("");
}

And here is the canonical way:

static PyObject*
empty5(PyObject* self, PyObject* args)
{
    Py_INCREF(Py_None);
    return Py_None;
}

Discussion

Often, a function written in C for Python needs to return nothing in particular. In other words, it should return None in Python terms, but you can’t return Py_None from C, because that will mess up reference counts. None—the Python object we must explicitly return from a Python-callable, C-coded function—is a perfectly normal Python object, still subject to all normal reference-count rules. One of these rules is that each function must Py_INCREF the Python object it returns.

So a bare return Py_None; is a nasty lurking bug. Either explicitly Py_INCREF the None object you’re returning, or delegate the work to handy function Py_BuildValue ...