User guide

NumPy User Guide, Release 1.9.0
multiple modules will be defined by that file. However, there are some tricks to get that to work correctly and it is not
covered here.
A minimal init{name} method looks like:
PyMODINIT_FUNC
init{name}(void)
{
(void)Py_InitModule({name}, mymethods);
import_array();
}
The mymethods must be an array (usually statically declared) of PyMethodDef structures which contain method
names, actual C-functions, a variable indicating whether the method uses keyword arguments or not, and docstrings.
These are explained in the next section. If you want to add constants to the module, then you store the returned
value from Py_InitModule which is a module object. The most general way to add itmes to the module is to get the
module dictionary using PyModule_GetDict(module). With the module dictionary, you can add whatever you like to
the module manually. An easier way to add objects to the module is to use one of three additional Python C-API calls
that do not require a separate extraction of the module dictionary. These are documented in the Python documentation,
but repeated here for convenience:
int PyModule_AddObject(PyObject* module, char* name, PyObject* value)
int PyModule_AddIntConstant(PyObject* module, char* name, long value)
int PyModule_AddStringConstant(PyObject* module, char* name, char* value)
All three of these functions require the module object (the return value of Py_InitModule). The name is a string
that labels the value in the module. Depending on which function is called, the value argument is either a
general object (PyModule_AddObject steals a reference to it), an integer constant, or a string constant.
5.1.3 Defining functions
The second argument passed in to the Py_InitModule function is a structure that makes it easy to to define functions in
the module. In the example given above, the mymethods structure would have been defined earlier in the file (usually
right before the init{name} subroutine) to:
static PyMethodDef mymethods[] = {
{ nokeywordfunc,nokeyword_cfunc,
METH_VARARGS,
Doc string},
{ keywordfunc, keyword_cfunc,
METH_VARARGS|METH_KEYWORDS,
Doc string},
{NULL, NULL, 0, NULL} /
*
Sentinel
*
/
}
Each entry in the mymethods array is a PyMethodDef structure containing 1) the Python name, 2) the C-function
that implements the function, 3) flags indicating whether or not keywords are accepted for this function, and 4) The
docstring for the function. Any number of functions may be defined for a single module by adding more entries to this
table. The last entry must be all NULL as shown to act as a sentinel. Python looks for this entry to know that all of the
functions for the module have been defined.
The last thing that must be done to finish the extension module is to actually write the code that performs the desired
functions. There are two kinds of functions: those that don’t accept keyword arguments, and those that do.
54 Chapter 5. Using Numpy C-API