User guide

NumPy User Guide, Release 1.9.0
Functions without keyword arguments
Functions that don’t accept keyword arguments should be written as:
static PyObject
*
nokeyword_cfunc (PyObject
*
dummy, PyObject
*
args)
{
/
*
convert Python arguments
*
/
/
*
do function
*
/
/
*
return something
*
/
}
The dummy argument is not used in this context and can be safely ignored. The args argument contains all of the
arguments passed in to the function as a tuple. You can do anything you want at this point, but usually the easiest way
to manage the input arguments is to call PyArg_ParseTuple (args, format_string, addresses_to_C_variables...)
or PyArg_UnpackTuple (tuple, “name” , min, max, ...). A good description of how to use the first function is
contained in the Python C-API reference manual under section 5.5 (Parsing arguments and building values). You
should pay particular attention to the “O&” format which uses converter functions to go between the Python ob-
ject and the C object. All of the other format functions can be (mostly) thought of as special cases of this general
rule. There are several converter functions defined in the NumPy C-API that may be of use. In particular, the
PyArray_DescrConverter function is very useful to support arbitrary data-type specification. This function
transforms any valid data-type Python object into a PyArray_Descr
*
object. Remember to pass in the address of
the C-variables that should be filled in.
There are lots of examples of how to use PyArg_ParseTuple throughout the NumPy source code. The standard
usage is like this:
PyObject
*
input;
PyArray_Descr
*
dtype;
if (!PyArg_ParseTuple(args, "OO&", &input,
PyArray_DescrConverter,
&dtype)) return NULL;
It is important to keep in mind that you get a borrowed reference to the object when using the “O” format string.
However, the converter functions usually require some form of memory handling. In this example, if the conversion is
successful, dtype will hold a new reference to a PyArray_Descr
*
object, while input will hold a borrowed refer-
ence. Therefore, if this conversion were mixed with another conversion (say to an integer) and the data-type conversion
was successful but the integer conversion failed, then you would need to release the reference count to the data-type
object before returning. A typical way to do this is to set dtype to NULL before calling PyArg_ParseTuple and
then use Py_XDECREF on dtype before returning.
After the input arguments are processed, the code that actually does the work is written (likely calling other functions
as needed). The final step of the C-function is to return something. If an error is encountered then NULL should be
returned (making sure an error has actually been set). If nothing should be returned then increment Py_None and
return it. If a single object should be returned then it is returned (ensuring that you own a reference to it first). If multi-
ple objects should be returned then you need to return a tuple. The Py_BuildValue (format_string, c_variables...)
function makes it easy to build tuples of Python objects from C variables. Pay special attention to the difference be-
tween ‘N’ and ‘O’ in the format string or you can easily create memory leaks. The ‘O’ format string increments the
reference count of the PyObject
*
C-variable it corresponds to, while the ‘N’ format string steals a reference to the
corresponding PyObject
*
C-variable. You should use ‘N’ if you ave already created a reference for the object and
just want to give that reference to the tuple. You should use ‘O’ if you only have a borrowed reference to an object and
need to create one to provide for the tuple.
5.1. How to extend NumPy 55