# 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**:

``` 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**:

``` python
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:

``` bash
$ sudo apt install python-dev
```

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

``` bash
$ 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:

``` bash
$ 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/Python`*`XY`*`/include`\
`gcc -shared hellomodule.o -L/Python`*`XY`*`/libs -lpython`*`XY`*` -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):

``` 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):

``` python
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:

``` c
#include <stdio.h>

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

hello.i:

``` c
%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

