Python – Extension Programming with C

Pre-Requisites for Writing Extensions

• On Unix machines, this usually requires installing a developer-specific package such as python2.5-dev.
• Windows users get these headers as part of the package when they use the binary Python installer.

First look at a Python Extension

• The header file Python.h.
• The C functions you want to expose as the interface from your 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

The C Functions

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

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

The Method Mapping Table

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

• ml_name − This is the name of the function as 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 previous seection.
• 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.

Example

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

The Initialization Function

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

• 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.

#include <Python.h>
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, , NULL }
};
PyMODINIT_FUNC initModule() {
   Py_InitModule3(func, module_methods, "docstring...");
}

Example

#include <Python.h>
static PyObject* helloworld(PyObject* self) {
   return Py_BuildValue("s", "Hello, Python extensions!!");
}
static char helloworld_docs[] =
   "helloworld( ): Any message you want to put here!!n";
static PyMethodDef helloworld_funcs[] = {
   {"helloworld", (PyCFunction)helloworld, 
      METH_NOARGS, helloworld_docs},
      {NULL}
};
void inithelloworld(void) {
   Py_InitModule3("helloworld", helloworld_funcs,
                  "Extension module example!");
}

Building and Installing Extensions

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

$ python setup.py install

Importing Extensions

#!/usr/bin/python
import helloworld
print helloworld.helloworld()

Hello, Python extensions!!

Passing Function Parameters

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

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

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;
}

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)

The PyArg_ParseTuple Function

int PyArg_ParseTuple(PyObject* tuple,char* format,...)

Returning Values

static PyObject *foo_add(PyObject *self, PyObject *args) {
   int a;
   int b;
if (!PyArg_ParseTuple(args, "ii", &a, &b)) {
      return NULL;
   }
   return Py_BuildValue("i", a + b);
}

def add(a, b):
   return (a + b)

static PyObject *foo_add_subtract(PyObject *self, PyObject *args) {
   int a;
   int b;

if (!PyArg_ParseTuple(args, "ii", &a, &b)) {
      return NULL;
   }
   return Py_BuildValue("ii", a + b, a - b);
}

def add_subtract(a, b):
   return (a + b, a - b)

The Py_BuildValue Function

PyObject* Py_BuildValue(char* format,...)