User guide

NumPy User Guide, Release 1.9.0
Several examples are available in the examples directory where weave is installed on your system. Look particularly
at ramp2.py, increment_example.py and fibonacii.py
Conclusion
Weave is a useful tool for quickly routines in C/C++ and linking them into Python. It’s caching-mechanism allows for
on-the-fly compilation which makes it particularly attractive for in-house code. Because of the requirement that the
user have a C++-compiler, it can be difficult (but not impossible) to distribute a package that uses weave to other users
who don’t have a compiler installed. Of course, weave could be used to construct an extension module which is then
distributed in the normal way ( using a setup.py file). While you can use weave to build larger extension modules with
many methods, creating methods with a variable- number of arguments is not possible. Thus, for a more sophisticated
module, you will still probably want a Python-layer that calls the weave-produced extension.
5.2.5 Pyrex
Pyrex is a way to write C-extension modules using Python-like syntax. It is an interesting way to generate extension
modules that is growing in popularity, particularly among people who have rusty or non- existent C-skills. It does
require the user to write the “interface” code and so is more time-consuming than SWIG or f2py if you are trying to
interface to a large library of code. However, if you are writing an extension module that will include quite a bit of
your own algorithmic code, as well, then Pyrex is a good match. A big weakness perhaps is the inability to easily and
quickly access the elements of a multidimensional array.
Notice that Pyrex is an extension-module generator only. Unlike weave or f2py, it includes no automatic facility for
compiling and linking the extension module (which must be done in the usual fashion). It does provide a modified
distutils class called build_ext which lets you build an extension module from a .pyx source. Thus, you could write in
a setup.py file:
from Pyrex.Distutils import build_ext
from distutils.extension import Extension
from distutils.core import setup
import numpy
py_ext = Extension(’mine’, [’mine.pyx’],
include_dirs=[numpy.get_include()])
setup(name=’mine’, description=’Nothing’,
ext_modules=[pyx_ext],
cmdclass = {’build_ext’:build_ext})
Adding the NumPy include directory is, of course, only necessary if you are using NumPy arrays in the extension
module (which is what I assume you are using Pyrex for). The distutils extensions in NumPy also include support for
automatically producing the extension-module and linking it from a .pyx file. It works so that if the user does not
have Pyrex installed, then it looks for a file with the same file-name but a .c extension which it then uses instead of
trying to produce the .c file again.
Pyrex does not natively understand NumPy arrays. However, it is not difficult to include information that lets
Pyrex deal with them usefully. In fact, the numpy.random.mtrand module was written using Pyrex so an example
of Pyrex usage is already included in the NumPy source distribution. That experience led to the creation of a standard
c_numpy.pxd file that you can use to simplify interacting with NumPy array objects in a Pyrex-written extension. The
file may not be complete (it wasn’t at the time of this writing). If you have additions you’d like to contribute, please
send them. The file is located in the .../site-packages/numpy/doc/pyrex directory where you have Python installed.
There is also an example in that directory of using Pyrex to construct a simple extension module. It shows that Pyrex
looks a lot like Python but also contains some new syntax that is necessary in order to get C-like speed.
5.2. Using Python as glue 69