Python Extension Programming With C

Some code that users write by any compiled language like C, C++, or Java can be mixed or imported into one more Python script. This code is believed as an "extension."

A Python extension unit is zilch in excess of a normal C library. On Unix mechanisms, these libraries typically end in .so (for shared objects). On Windows engines, users typically observe .dll (for dynamically linked libraries).

Pre-Requisites for Writing Extensions

• To create a writing users extension, users are going to call for the Python header files.
• On Unix machines, this typically necessitates fitting an engineer-specific enclose such as python2.5-dev.
• Windows users obtain these headers as a fraction of the package while they employ the binary Python installer.
• Moreover, it is assumed that users have first-rate information of C or C++ to write any Python Extension using C programming.

First look at a Python Extension

For users first look at a Python extension module, users require to group their code into four-part?

• The header file Python.h.
• The C functions users desire to depiction as the interface from the user's module.
• A table mapping the names of your functions as Python developers see them to C functions inside the extension module.
• An initialization function.

The Header File Python.h

Users require to embrace Python.h header file in your C source file, which presents users access to the inner Python API used to hook your module into the interpreter.

Ensure to comprise Python. h before any additional headers users might require. Users call for to follow with the functions users want to call from Python.

The C Functions

The signatures of the C implementation of your functions always take one of the following three forms

static PyObject *MyFunction( PyObject *self, PyObject *args );

static PyObject *MyFunctionWithKeywords(PyObject *self,
                                 PyObject *args,
                                 PyObject *kw);

static PyObject *MyFunctionWithNoArgs( PyObject *self );

Each one of the previous statements returns a Python object. There is no such obsession as a canceled function in Python as a present is in C. If users do not desire functions to return a value, return the C equivalent of Python's None value. The Python headers describe a macro, Py_RETURN_NONE, that does this for us.

The names of your C functions can be anything users like, as they are never seen the exterior of the extension module. They are described as still function.

UsersC functions characteristically are named by combine the Python module and function names together, as shown here:

static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Do your stuff here. */
   Py_RETURN_NONE;
}

This is a Python utility called func in of the module. Users will be putting sticks to their C functions into the technique table for the module that more often than not comes next in users' source code.

The Method Mapping Table

This method table is a simple array of PyMethodDef structures. That structure looks something like this

struct PyMethodDef {
   char *ml_name;
   PyCFunction ml_meth;
   int ml_flags;
   char *ml_doc;
};

Here is the description of the members of this structure:

• ml_name- This is the name of the function the Python interpreter presents when it is used in Python programs.
• ml_meth- This must be the address to a function that has any one of the signatures described in the previous section.
• ml_flags - This tells the interpreter which of the three signatures ml_meth is using.
• This flag usually has a value of METH_VARARGS.
• This flag can be bitwise OR'ed with METH_KEYWORDS if you want to allow keyword arguments into your function.
• This can also have a value of METH_NOARGS that indicates you do not want to accept any arguments.
• ml_doc- This is the docstring for the function, which could be NULL if you do not feel like writing one.

This table needs to be terminated with a sentinel that consists of NULL and 0 values for the appropriate members.

Example

For the above-defined function, we have the following method mapping table:

static PyMethodDef module_methods[] = {
   { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
   { NULL, NULL, 0, NULL }
};

The Initialization Function

The previous fraction of your extension unit is the initialization function. This function is known by the Python interpreter when the component is loaded. It is involved that the function is named initModule, where Module is the name of the module.

The initialization function requires to be sending abraded from the library you will be building. The Python headers define PyMODINIT_FUNC to include the appropriate incantations for that to happen for the particular environment in which we are compiling. All you have to do is use it when defining the function.

Your C initialization function generally has the following overall structure

PyMODINIT_FUNC initModule() {
   Py_InitModule3(func, module_methods, "docstring...");
}

Here is the description of the Py_InitModule3 function:

• func- This is the function to be exported.
• module_methods- This is the mapping table name defined above.
• docstring- This is the comment you want to give in your extension.

Putting this all together looks like the following:

#include 

static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Do your stuff here. */
   Py_RETURN_NONE;
}

static PyMethodDef module_methods[] = {
   { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
   { NULL, NULL, 0, NULL }
};

PyMODINIT_FUNC initModule() {
   Py_InitModule3(func, module_methods, "docstring...");
}

Example

A simple example that makes use of all the above concepts:

#include 

static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Do your stuff here. */
   Py_RETURN_NONE;
}

static PyMethodDef module_methods[] = {
   { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
   { NULL, NULL, 0, NULL }
};

PyMODINIT_FUNC initModule() {
   Py_InitModule3(func, module_methods, "docstring...");
}

Here the Py_BuildValue function is used to build a Python value. Save the above code in hello.c file. We would see how to compile and install this module to be called from Python script.

Building and Installing Extensions

The distutils package makes it very easy to distribute Python modules, both pure Python and extension modules, in a standard way. Modules are distributed in source form and built and installed via a setup script usually called setup.py as follows.

For the above module, you need to prepare the following setup.py script:

from distutils.core import setup, Extension
setup(name='helloworld', version='1.0',  \
      ext_modules=[Extension('helloworld', ['hello.c'])])

This would produce the following result:

Hello, Python extensions!!

Passing Function Parameters

As you will most likely want to define functions that accept arguments, you can use one of the other signatures for your C functions. For example, the following function, that accepts some number of parameters, would be defined like this:

static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Parse args and do something interesting here. */
   Py_RETURN_NONE;
}

The method table containing an entry for the new function would look like this:

static PyMethodDef module_methods[] = {
   { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
   { "func", module_func, METH_VARARGS, NULL },
   { NULL, NULL, 0, NULL }
};

You can use API PyArg_ParseTuple function to extract the arguments from the one PyObject pointer passed into your C function.

The first argument to PyArg_ParseTuple is the args argument. This is the object you will be parsing. The second argument is a format string describing the arguments as you expect them to appear. Each argument is represented by one or more characters in the format string as follows.

static PyObject *module_func(PyObject *self, PyObject *args) {
   int i;
   double d;
   char *s;

   if (!PyArg_ParseTuple(args, "ids", &i, &d, &s)) {
      return NULL;
   }
   
   /* Do something interesting here. */
   Py_RETURN_NONE;
}

Compiling the new version of your module and importing it enables you to invoke the new function with any number of arguments of any type:

module.func(1, s="three", d=2.0)
module.func(i=1, d=2.0, s="three")
module.func(s="three", d=2.0, i=1)

This function returns 0 for errors, and a value not equal to 0 for success. tuple is the PyObject* that was the C function's second argument. Here format is a C string that describes mandatory and optional arguments.

Here is a list of format codes for PyArg_ParseTuple function ?