Download Python Scientific lecture notes
Transcript
Python Scientific lecture notes, Release 2013.2 beta (euroscipy 2013)
This chapter contains an introduction to the many different routes for making your native code (primarily C/C++)
available from Python, a process commonly referred to wrapping. The goal of this chapter is to give you a
flavour of what technologies exist and what their respective merits and shortcomings are, so that you can select
the appropriate one for your specific needs. In any case, once you do start wrapping, you almost certainly will
want to consult the respective documentation for your selected technique.
Chapters contents
•
•
•
•
•
•
•
•
Introduction (page 253)
Python-C-Api (page 254)
Ctypes (page 258)
SWIG (page 261)
Cython (page 265)
Summary (page 269)
Further Reading and References (page 269)
Exercises (page 269)
Python Scientific lecture notes, Release 2013.2 beta (euroscipy 2013)
• You will need a C compiler for most of the examples.
2.8.2 Python-C-Api
The Python-C-API is the backbone of the standard Python interpreter (a.k.a CPython). Using this API it is possible
to write Python extension module in C and C++. Obviously, these extension modules can, by virtue of language
compatibility, call any function written in C or C++.
When using the Python-C-API, one usually writes much boilerplate code, first to parse the arguments that were
given to a function, and later to construct the return type.
Advantages
• Requires no additional libraries
• Lots of low-level control
• Entirely usable from C++
Disadvantages
• May require a substantial amount of effort
2.8.1 Introduction
• Much overhead in the code
This chapter covers the following techniques:
• Must be compiled
• Python-C-Api
• High maintenance cost
• Ctypes
• No forward compatibility across Python versions as C-API changes
• SWIG (Simplified Wrapper and Interface Generator)
• Reference count bugs are easy to create and very hard to track down.
• Cython
These four techniques are perhaps the most well known ones, of which Cython is probably the most advanced one
and the one you should consider using first. The others are also important, if you want to understand the wrapping
problem from different angles. Having said that, there are other alternatives out there, but having understood the
basics of the ones above, you will be in a position to evaluate the technique of your choice to see if it fits your
needs.
The following criteria may be useful when evaluating a technology:
• Are additional libraries required?
Note: The Python-C-Api example here serves mainly for didactic reasons. Many of the other techniques actually
depend on this, so it is good to have a high-level understanding of how it works. In 99% of the use-cases you will
be better off, using an alternative technique.
Note: Since refernce counting bugs are easy to create and hard to track down, anyone really needing to use
the Python C-API should read the section about objects, types and reference counts from the official python
documentation. Additionally, there is a tool by the name of cpychecker which can help discover common errors
with reference counting.
• Is the code autogenerated?
• Does it need to be compiled?
Example
• Is there good support for interacting with Numpy arrays?
The following C-extension module, make the cos function from the standard math library available to Python:
• Does it support C++?
Before you set out, you should consider your use case. When interfacing with native code, there are usually two
use-cases that come up:
• Existing code in C/C++ that needs to be leveraged, either because it already exists, or because it is faster.
• Python code too slow, push inner loops to native code
Each technology is demonstrated by wrapping the cos function from math.h. While this is a mostly a trivial
example, it should serve us well to demonstrate the basics of the wrapping solution. Since each technique also
includes some form of Numpy support, this is also demonstrated using an example where the cosine is computed
on some kind of array.
Last but not least, two small warnings:
• All of these techniques may crash (segmentation fault) the Python interpreter, which is (usually) due to bugs
in the C code.
• All the examples have been done on Linux, they should be possible on other operating systems.
2.8. Interfacing with C
253
/*
Example of wrapping cos function from math.h with the Python-C-API. */
#include <Python.h>
#include <math.h>
/* wrapped cosine function */
static PyObject* cos_func(PyObject* self, PyObject* args)
{
double value;
double answer;
/* parse the input, from python float to c double */
if (!PyArg_ParseTuple(args, "d", &value))
return NULL;
/* if the above function returns -1, an appropriate Python exception will
* have been set, and the function simply returns NULL
*/
2.8. Interfacing with C
254