Opaque data structures are easily handled by wrapping them inside capsule objects.

Consider this fragment of C code from our sample code:

typedef struct Point {

double x,y;

} Point;

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

Here is an example of extension code that wraps the Point structure and distance()

function using capsules:

/* Destructor function for points */

/* Utility functions */

static PyObject *PyPoint_FromPoint(Point *p, int must_free) {

/* Create a new Point object */

Point *p;

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

if (!PyArg_ParseTuple(args,"OO",&py_p1, &py_p2)) {

return NULL;

}

if (!(p1 = PyPoint_AsPoint(py_p1))) {

return NULL;

}

if (!(p2 = PyPoint_AsPoint(py_p2))) {

return NULL;

}

result = distance(p1,p2);

return Py_BuildValue("d", result);

}

Using these functions from Python looks like this:

>>> import sample

>>> p1 = sample.Point(2,3)

>>> p2 = sample.Point(4,5)

>>> p1

>>> p2

>>> sample.distance(p1,p2)

>>>

Capsules are similar to a typed C pointer. Internally, they hold a generic pointer along

with an identifying name and can be easily created using the PyCapsule_New() function.

In addition, an optional destructor function can be attached to a capsule to release the

underlying memory when the capsule object is garbage collected.

To extract the pointer contained inside a capsule, use the PyCapsule_GetPointer()

function and specify the name. If the supplied name doesn’t match that of the capsule

or some other error occurs, an exception is raised and NULL is returned.

In this recipe, a pair of utility functions—PyPoint_FromPoint() and PyPoint_As

Point()—have been written to deal with the mechanics of creating and unwinding

Point instances from capsule objects. In any extension functions, we’ll use these func‐

tions instead of working with capsules directly. This design choice makes it easier to

deal with possible changes to the wrapping of Point objects in the future. For example,

if you decided to use something other than a capsule later, you would only have to change

these two functions.

One tricky part about capsules concerns garbage collection and memory management.

The PyPoint_FromPoint() function accepts a must_free argument that indicates

whether the underlying Point * structure is to be collected when the capsule is de‐

stroyed. When working with certain kinds of C code, ownership issues can be difficult

to handle (e.g., perhaps a Point structure is embedded within a larger data structure

that is managed separately). Rather than making a unilateral decision to garbage collect,

this extra argument gives control back to the programmer. It should be noted that the

destructor associated with an existing capsule can also be changed using the PyCap

sule_SetDestructor() function.

Capsules are a sensible solution to interfacing with certain kinds of C code involving

structures. For instance, sometimes you just don’t care about exposing the internals of

a structure or turning it into a full-fledged extension type. With a capsule, you can put

a lightweight wrapper around it and easily pass it around to other extension functions.