Python Programming/Extending with C

Python modules can be written in pure Python but they can also be written in the C language. The following shows how to extend Python with C.

Using the Python/C API

A minimal example

To illustrate the mechanics, we will create a minimal extension module containing a single function that outputs "Hello" followed by the name passed in as the first parameter.

We will first create the C source code, placing it to hellomodule.c:

#include <Python.h>

static PyObject*
say_hello(PyObject* self, PyObject* args)
{
    const char* name;

    if (!PyArg_ParseTuple(args, "s", &name))
        return NULL;

    printf("Hello %s!\n", name);

    Py_RETURN_NONE;
}

static PyMethodDef HelloMethods[] =
{
     {"say_hello", say_hello, METH_VARARGS, "Greet somebody."},
     {NULL, NULL, 0, NULL}
};

PyMODINIT_FUNC
inithello(void)
{
     (void) Py_InitModule("hello", HelloMethods);
}

Then we will need a setup file, setup.py:

from distutils.core import setup, Extension

module1 = Extension('hello', sources = ['hellomodule.c'])

setup (name = 'PackageName',
        version = '1.0',
        description = 'This is a demo package',
        ext_modules = [module1])

Then we can build the module using a procedure whose details depends on the operating system and the compiler suite.

Building with GCC for Linux

Before our module can be compiled, you must install the Python development headers if you have not already. On Debian and Debian-based systems such as Ubuntu, these can be installed with the following command:

$ sudo apt install python-dev

On openSUSE, the required package is called python-devel and can be installed with zypper:

$ sudo zypper install python-devel

Now that Python.h is available, we can compile the module source code we created in the previous section as follows:

$ python setup.py build

The will compile the module to a file called hello.so in build/lib.linux-i686-x.y.

Building with GCC for Microsoft Windows

Microsoft Windows users can use MinGW to compile the extension module from the command line. Assuming gcc is in the path, you can build the extension as follows:

python setup.py build -cmingw32

The above will produce file hello.pyd, a Python Dynamic Module, similar to a DLL. The file will land in build\lib.win32-x.y.

An alternate way of building the module in Windows is to build a DLL. (This method does not need an extension module file). From cmd.exe, type:

gcc -c  hellomodule.c -I/PythonXY/include
gcc -shared hellomodule.o -L/PythonXY/libs -lpythonXY -o hello.dll

where XY represents the version of Python, such as "24" for version 2.4.

Building using Microsoft Visual C++

With VC8, distutils is broken. Therefore, we will use cl.exe from a command prompt instead:

cl /LD hellomodule.c /Ic:\Python24\include c:\Python24\libs\python24.lib /link/out:hello.dll

Using the extension module

Change to the subdirectory where the file hello.so resides. In an interactive Python session you can use the module as follows.

>>> import hello
>>> hello.say_hello("World")
Hello World!

A module for calculating Fibonacci numbers

In this section, we present a module for Fibonacci numbers, thereby expanding on the minimal example above. Compared to the minimal example, what is worth noting is the use of "i" in PyArg_ParseTuple() and Py_BuildValue().

The C source code in (fibmodule.c):

#include <Python.h>

int
_fib(int n)
{
    if (n < 2)
        return n;
    else
        return _fib(n-1) + _fib(n-2);
}

static PyObject*
fib(PyObject* self, PyObject* args)
{
    int n;

    if (!PyArg_ParseTuple(args, "i", &n))
        return NULL;

    return Py_BuildValue("i", _fib(n));
}

static PyMethodDef FibMethods[] = {
    {"fib", fib, METH_VARARGS, "Calculate the Fibonacci numbers."},
    {NULL, NULL, 0, NULL}
};

PyMODINIT_FUNC
initfib(void)
{
    (void) Py_InitModule("fib", FibMethods);
}

The build script (setup.py):

from distutils.core import setup, Extension

module1 = Extension('fib', sources = ['fibmodule.c'])

setup (name = 'PackageName',
        version = '1.0',
        description = 'This is a demo package',
        ext_modules = [module1])

Usage:

>>> import fib
>>> fib.fib(10)
55

Using SWIG

SWIG is a tool that helps a variety of scripting and programming languages call C and C++ code. SWIG makes creation of C language modules much more straightforward.

To use SWIG, you need to get it up and running first.

You can install it on an Ubuntu system as follows:

$ sudo apt-get install swig
$ sudo apt-get install python-dev

To get SWIG for Windows, you can use binaries available from the SWIG download page.

Once you have SWIG, you need to create the module source file and the module interface file:

hellomodule.c:

#include <stdio.h>

void say_hello(const char* name) {
    printf("Hello %s!\n", name);
}

hello.i:

%module hello
extern void say_hello(const char* name);

Then we let SWIG do its work:

swig -python hello.i

The above produces files hello.py and hello_wrap.c.

The next step is compiling; substitute /usr/include/python2.4/ with the correct path to Python.h for your setup:

gcc -fpic -c hellomodule.c hello_wrap.c -I/usr/include/python2.4/

As the last step, we do the linking:

gcc -shared hellomodule.o hello_wrap.o -o _hello.so -lpython

The module is used as follows:

>>> import hello
>>> hello.say_hello("World")
Hello World!

External links

• Extending and Embedding the Python Interpreter, python.org
• Python/C API Reference Manual, python.org
• SWIG, swig.org
• Download SWIG, swig.org