Python Programming/Extending with C

From Wikibooks, open books for an open world
Jump to navigation Jump to search


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[edit]

A minimal example[edit]

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[edit]

Given the module source code and the setup.py created in the previous section, we can build the module as follows:

python setup.py build

The module hello.so will end up in build/lib.linux-i686-x.y.

On an Ubuntu system, you might need to run

$ sudo apt install python-dev

This command installs you the python developement package and ensures that you can use the line #include <Python.h> in the C source code. On other systems like openSUSE the needed package calls python-devel and can be installed by using zypper:

$ sudo zypper install python-devel

Building with GCC for Microsoft Windows[edit]

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++[edit]

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[edit]

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[edit]

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[edit]

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[edit]