Illustration by Lia Avant

Extending Python with C: Part 1

If you know C, it's not too hard to use it to code Python extension modules. Let's examine a simple example. Make a new directory tinydir, and, in it, write with any text editor a file tiny.c:

   1  #include      		/* get all declarations/macros */
   2
   3  static PyObject*
   4  tiny(PyObject* self, PyObject* args)   /* proto for all exposed funcs */
   5  {
   6      if(!PyArg_ParseTuple(args, ""))    /* receive arguments (no args) */
   7          return 0;                      /* propagate error if any */
   8      return Py_BuildValue("s","it works!"); /* build and return result */
   9  }
  10
  11  static PyMethodDef tinyMethods[] = {   /* methods exposed from module */
  12      {"tiny", tiny, METH_VARARGS, "A tiny function"},    /* descriptor */
  13      {0}                                                 /* sentinel   */
  14  };
  15
  16  void
  17  inittiny()                             /* called by Python on import */
  18  {
  19      Py_InitModule("tiny", tinyMethods);  /* init module with methods */
  20  }

The line numbers in the listing are not part of the file – I just use them to help me explain the file's contents, line by line.

	Sidebar - Building with distutils If your platform is Windows, building with the distutils works "out of the box" only if you have Microsoft's Visual C++ 6 compiler installed. There are ways to build extensions with free compilers, such as: the compiler inside Microsoft's ".NET Development Platform" Borland's free C/C++ compiler the mingw32 version of gcc the cygwin version of gcc (if you use Python in cygwin) but this article does not cover these specific details. On other platforms, such as Linux and OpenBSD, both Python and its extensions are implicitly built with "the C compiler that comes with the platform", typically gcc, so that the issue of using other compilers arises even more rarely than on Windows.

Let's examine and explain this short C source file in full detail, starting from the end. Since the module is called tiny, when the module is installed you can load it into Python with the statement import tiny.

To execute import tiny, Python finds the tiny extension module (normally called tiny.pyd on Windows, tiny.so on Linux) in some directory along the sys.path, loads the module into memory, and finds and calls a function named inittiny in the module.

The name of a module's initialization function is always init followed by the name of the module. Lines 16-20 define the initialization function. All inittiny has to do, in this simple example, is to initialize the Python module object, which it does on line 19 by calling function Py_InitModule (part of the Python C API, whose declarations are brought in by the #include on line 1).

Py_InitModule's first argument is the name of the module it must initialize. The second argument is an array of PyMethodDef structures -- here, the tryMethods array defined in lines 11-14. The array is always terminated by a "sentinel" structure with all fields at 0 (here defined on line 13). Before the sentinel, the array can have any number of PyMethodDef structures, each describing a C function that the module exposes to Python; here, we only have one such descriptor (on line 12), because module tiny exposes only one function to Python. The descriptor structure has four fields:

1. the function's name as seen from Python (a string)
2. the function's name as coded in C
3. a code which is always METH_VARARGS (unless you want to get into advanced issues such as functions which Python code can call with named-arguments; this article does not cover such advanced issues, but only the basics)
4. the docstring for the function.

The second field names a C function that must have exactly the signature used here in lines 3-4 to define function tiny: the function should be static, must return a PyObject*, and must accept two PyObject* arguments. All Python objects are always passed to C, and returned from C, as pointers to struct PyObject, the internal Python struct which describes the Python object in detail. The first argument will always be 0, the null pointer (except for advanced issues such as using C coded functions as object-methods rather than as functions in a module). The second argument will always be the Python tuple of the arguments that Python code has used to call the function.

In line 6, the function examines its arguments, by calling function PyArg_ParseTuple (another function from the Python C API). The first argument to function PyArg_ParseTuple is the PyObject* that function tiny received as its second argument; the second argument to PyArg_ParseTuple is a string describing the types of arguments that tiny expects – in this case, an empty string, which means that tiny expects no arguments at all. Function PyArg_ParseTuple returns 0 if it detects any error; in this case, function tiny also returns 0, at line 7, and the calling Python code eventually receives a Python exception describing the error. In line 8, function tiny returns its result to Python. tiny builds this result by calling Py_BuildValue, yet another function from the Python C API. The first argument to function Py_BuildValue is a string describing the type of Python object that Py_BuildValue must build – in this case, "s", meaning the result is a Python str object. The second argument to Py_BuildValue is the C-type "string" (array of char with a terminating 0) whose value Py_BuildValue must copy into the resulting Python str object.

To build your extension module, use your favorite text editor to build in directory tinydir a file setup.py, using Python's standard distutils package:

1 from distutils.core import setup, Extension
2	
3 setup(name = "tiny",
4 version = "1.0",
5 description = "A tiny example extension",
6 maintainer = "Alex Martelli",
7 maintainer_email = "aleaxit@yahoo.com",
8	       
9 ext_modules = [ Extension('tiny', sources=['tiny.c']) ]
10	)

Now, assuming you have write permission for your Python installation's site-packages directory, all you need to do is (from a shell prompt, or equivalently a CMD.EXE or COMMAND.COM prompt in Windows) to make tinydir your current directory (with cd tinydir), then run:

python setup.py install

>>> import tiny
>>> dir(tiny)
['__doc__', '__file__', '__name__', 'tiny']
>>> print tiny.tiny.__doc__
Truly tiny function
>>> print tiny.tiny()
it works!
>>> print tiny.tiny(23)
Traceback (most recent call last):
File "", line 1, in ?
TypeError: function takes exactly 0 arguments (1 given)

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

and also add a line inside tinyMethods:

 {"isum", isum, METH_VARARGS, "Sum two integers"},

>>> import tiny    # you need reload(tiny) if tiny is already loaded
>>> dir(tiny)
['__doc__', '__file__', '__name__', 'isum', 'tiny']
>>> tiny.isum(100, 23)
123
>>> tiny.isum(4.56, 7.89)
11

   static PyObject*
   sum(PyObject* self, PyObject* args)
   {
       PyObject *a, *b;
       if(!PyArg_ParseTuple(args, "OO", &a, &b))
           return 0;
       return PyNumber_Add(a, b);
   }

   {"sum", sum, METH_VARARGS, "Sum two objects"},

# you need reload(tiny) if tiny is already loaded
>>> import tiny    
>>> dir(tiny)
['__doc__', '__file__', '__name__', 'isum', 'sum', 'tiny']
>>> print tiny.sum.__doc__
Sum two objects
>>> print tiny.sum(4.56, 7.89)
12.45
>>> print tiny.sum('be', 'bop')
bebop

 Py is committed to bringing you great Python Articles.