Python Cookbook 2Nd Edition Jun 1002005 [Electronic resources]

David Ascher, Alex Martelli, Anna Ravenscroft

نسخه متنی -صفحه : 394/ 330

Recipe 17.8. 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

Despite the simplicity of the task, there are right and wrong ways to perform it. The canonical solution is:

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

and the simplest, but still correct way, is:

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

Discussion

A function written in C for Python often needs to return nothing in particular. In Python terms, it must return None. Don't just code return Py_None; from C: that messes up reference counts! Nonethe Python object we must explicitly return from a Python-callable, C-coded functionis a normal Python object, subject to all normal reference count rules. One of these rules is that each function must Py_INCREF the Python object it returns.

A bare return Py_None; is a nasty lurking buga frequent beginner's error that messes up reference counts:

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

Either explicitly Py_INCREF the None object you're returning, or (a simpler approach, but one that costs a few machine cycles) delegate the work to the handy function Py_BuildValue, which can be used to handle just about all cases of returning values from C to Python, offering potential uniformity advantages. To have Py_BuildValue build a properly incref'd None on your behalf, call it with just one argument, an empty format string.

In Python 2.4, the C API has gained a new macro just for this purpose. If you're coding a C extension that supports only Python 2.4, you can write Py_RETURN_NONE; instead of the return statement, and the macro takes care of everything for you.