You want to write a simple C extension module directly using Python’s extension API

and no other tools.

For simple C code, it is straightforward to make a handcrafted extension module. As a

preliminary step, you probably want to make sure your C code has a proper header file.

For example,

/* sample.h */

#include <math.h>

extern int gcd(int, int);

extern int in_mandel(double x0, double y0, int n);

extern int divide(int a, int b, int *remainder);

typedef struct Point {

double x,y;

} Point;

extern double distance(Point *p1, Point *p2);

Typically, this header would correspond to a library that has been compiled separately.

With that assumption, here is a sample extension module that illustrates the basics of

writing extension functions:

#include "Python.h"

#include "sample.h"

/* int gcd(int, int) */

if (!PyArg_ParseTuple(args,"ii", &x, &y)) {

return NULL;

}

result = gcd(x,y);

return Py_BuildValue("i", result);

}

/* int in_mandel(double, double, int) */

if (!PyArg_ParseTuple(args, "ddi", &x0, &y0, &n)) {

return NULL;

}

result = in_mandel(x0,y0,n);

return Py_BuildValue("i", result);

}

/* int divide(int, int, int *) */

/* Module method table */

/* Module structure */

"sample", /* name of module */

"A sample module", /* Doc string (may be NULL) */

-1, /* Size of per-interpreter state or -1 */

SampleMethods /* Method table */

/* Module initialization function */

For building the extension module, create a setup.py file that looks like this:

# setup.py

from distutils.core import setup, Extension

setup(name='sample',

ext_modules=[

Extension('sample',

['pysample.c'],

include_dirs = ['/some/dir'],

define_macros = [('FOO','1')],

undef_macros = ['BAR'],

library_dirs = ['/usr/local/lib'],

libraries = ['sample']

)

]

)

Now, to build the resulting library, simply use python3 buildlib.py build_ext --

inplace. For example:

bash % python3 setup.py build_ext --inplace

running build_ext

building 'sample' extension

gcc -fno-strict-aliasing -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes

-I/usr/local/include/python3.3m -c pysample.c

-o build/temp.macosx-10.6-x86_64-3.3/pysample.o

gcc -bundle -undefined dynamic_lookup

build/temp.macosx-10.6-x86_64-3.3/pysample.o \

-L/usr/local/lib -lsample -o sample.so

bash %

As shown, this creates a shared library called sample.so. When compiled, you should

be able to start importing it as a module:

>>> import sample

>>> sample.gcd(35, 42)

>>> sample.in_mandel(0, 0, 500)

>>> sample.in_mandel(2.0, 1.0, 500)

0

>>> sample.divide(42, 8)

>>>

If you are attempting these steps on Windows, you may need to spend some time fiddling

with your environment and the build environment to get extension modules to build

correctly. Binary distributions of Python are typically built using Microsoft Visual

Studio. To get extensions to work, you may have to compile them using the same or

compatible tools. See the Python documentation.

Before attempting any kind of handwritten extension, it is absolutely critical that you

consult Python’s documentation on “Extending and Embedding the Python Interpret‐

er”. Python’s C extension API is large, and repeating all of it here is simply not practical.

However, the most important parts can be easily discussed.

First, in extension modules, functions that you write are all typically written with a

common prototype such as this:

static PyObject *py_func(PyObject *self, PyObject *args) {

PyObject is the C data type that represents any Python object. At a very high level, an

extension function is a C function that receives a tuple of Python objects (in PyObject

*args) and returns a new Python object as a result. The self argument to the function

return Py_BuildValue("i", 34); // Return an integer

return Py_BuildValue("d", 3.4); // Return a double

return Py_BuildValue("s", "Hello"); // Null-terminated UTF-8 string

return Py_BuildValue("(ii)", 3, 4); // Tuple (3, 4)

Near the bottom of any extension module, you will find a function table such as the

SampleMethods table shown in this recipe. This table lists C functions, the names to use

in Python, as well as doc strings. All modules are required to specify such a table, as it

gets used in the initialization of the module.

The final function PyInit_sample() is the module initialization function that executes

when the module is first imported. The primary job of this function is to register the

module object with the interpreter.

As a final note, it must be stressed that there is considerably more to extending Python

with C functions than what is shown here (in fact, the C API contains well over 500

functions in it). You should view this recipe simply as a stepping stone for getting started.

To do more, start with the documentation on the PyArg_ParseTuple() and Py_Build

Value() functions, and expand from there.