Producing Python Wrappers for C++ Libraries Using SWIG

Joshua L. Cherry, Ph.D.

National Center for Biotechnology InformationNational Library of MedicineNational Institutes of Healthjcherry@ncbi.nlm.nih.gov

SWIG

Simplified Wrapper and Interface Generator

www.swig.org

Two Ways to Extend Python

• Write functions, classes, etc. in Python

• Write C/C++– Use Python C API– Usually turn into shared library (dll)

Why C/C++?

• Performance

• Do things that couldn’t otherwise be done

• Use already existing C/C++ code

double foo(int n);

double foo(int n);

#include <Python.h>

PyObject *wrap_foo(PyObject *dummy, PyObject *args) {

...

}

double foo(int n);

#include <Python.h>

PyObject *wrap_foo(PyObject *dummy, PyObject *args) {

PyObject *resultobj;

int n;

double result;

PyArg_ParseTuple(args, “i", &n);

result = foo(n);

resultobj = PyFloat_FromDouble(result)

return resultobj;

}

double foo(int n);

int bar(int n, int m);

#include <Python.h>

PyObject *wrap_foo(PyObject *dummy, PyObject *args) {

...

}

PyObject *wrap_bar(PyObject *dummy, PyObject *args) {

PyObject *resultobj;

int n, m;

int result;

PyArg_ParseTuple(args, “ii", &n, &m);

result = bar(n, m);

resultobj = PyInt_FromLong(result)

return resultobj;

}

Some Things SWIG Does for You

• Full support for structs and classes, including inheritance

• Support for overloaded functions and functions with default arguments

• Exception handling that you specify

• Numerous customization capabilities

SharedLibrary

C++Code

PythonCode

Compile,link

SWIGInterface Files

(point atC++ headers)

SWIG

Simple SWIG Interface File

%module example

%include my_header1.hpp

%include my_header2.hpp

void some_function(double x, int n);

%{

#include “my_header1.hpp”

#include “my_header2.hpp

void some_function(double x, int n);

%}

Some Customizations and Features

• Simple customization with %rename, %ignore, %extend, %pythoncode, etc.

• Specialize C++ classes in Python with “directors”

• Customize behavior by writing “typemaps”

• SWIG Library: very useful library of SWIG code, e.g., exception handling, typemaps, stl support

%module example

%include stl.i%template(vector_int) std::vector<int>;

int prod(const std::vector<int>& vec);

>>> import example>>> vec = example.vector_int()>>> vec.append(42) # append mapped to vector::push_back>>> vec.append(98)>>> vec.append(47)>>> len(vec) # __len__ mapped to vector::size3>>> example.prod(vec) # normal class usage193452>>> >>> example.prod([42, 98, 47]) # works because of "in" typemap193452>>> vec2 = example.vector_int([42, 98, 47])

STL Support Example

NCBI C++ Toolkit

• C++ for speed and programmer control

• Vast: about 3200 classes, 44,000 functions– General-purpose functionality– Mission-specific functionality– Includes handling of ASN.1 objects

Scripting Languages

• E.g., Perl and Python

• “High-level”

• No (explicit) compilation necessary

• Usually lots of functionality included, and more available separately

Why Make Scripting Interfaces?

• Large number of existing programmers

• Easy to learn

• Easy to use

• Allow interactive use

• Ability to combine Toolkit functions with scripting language functions

• Embedding scripting languages in applications can make them customizable

Uses of Scripting Language Interfaces

• Writing end-product programs

• Prototyping C++ programs

• Interactive use for accomplishing things

• Interactive use for exploring the C++ Toolkit

• Introspection

The Interfaces

• SWIG generates code based on C++ headers and other information

• Ancillary scripts necessary for proper behavior and customizations

• Perl and Python supported

• Interfaces largely mirror C++ API, but with important enhancements and customizations

Issues

• Languages are different

• C++ templates must be instantiated at build time

• SWIG far from perfect

• Problems with the NCBI C++ Toolkit

• Large size of monolithic wrapper

Enhancements and Customizations

• Easier ASN.1/XML reading and writing

• Easy access to NCBI documentation

• Transparent reference counting for reference-counted objects

• Other add-on features

Josh Cherry

jcherry@ncbi.nlm.nih.gov

SWIG

www.swig.org

NCBI C++ Toolkit Wrappers

www.ncbi.nlm.nih.gov/cvsweb/index.cgi/internal/c++/src/wrappers/