Basic setup.py

The distutils extension provided with Cython allows you to pass .pyx files directly to the Extension constructor in your setup file.

If you have a single Cython file that you want to turn into a compiled extension, say with filename example.pyx the associated setup.py would be:

from distutils.core import setup
from distutils.extension import Extension
from Cython.Distutils import build_ext

setup(
    cmdclass = {'build_ext': build_ext},
    ext_modules = [Extension("example", ["example.pyx"])]
)

To understand the setup.py more fully look at the official distutils documentation. To compile the extension for use in the current directory use:

$ python setup.py build_ext --inplace

Cython Files Depending on C Files

When you have come C files that have been wrapped with cython and you want to compile them into your extension the basic setup.py file to do this would be:

from distutils.core import setup
from distutils.extension import Extension
from Cython.Distutils import build_ext

sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']

setup(
    cmdclass = {'build_ext': build_ext},
    ext_modules = [Extension("example", sourcefiles)]
)

Notice that the files have been given a name, this is not necessary, but it makes the file easier to format if the list gets long.

The Extension class takes many options, and a fuller explanation can be found in the distutils documentation. Some useful options to know about are include_dirs, libraries, and library_dirs which specify where to find the .h and library files when linking to external libraries.

Multiple Cython Files in a Package

TODO

Distributing Cython modules

It is strongly recommended that you distribute the generated .c files as well as your Cython sources, so that users can install your module without needing to have Cython available.

It is also recommended that Cython compilation not be enabled by default in the version you distribute. Even if the user has Cython installed, he probably doesn’t want to use it just to install your module. Also, the version he has may not be the same one you used, and may not compile your sources correctly.

This simply means that the setup.py file that you ship with will just be a normal distutils file on the generated .c files, for the basic example we would have instead:

from distutils.core import setup
from distutils.extension import Extension

setup(
    ext_modules = [Extension("example", ["example.c"])]
)

Pyximport

Cython is a compiler. Therefore it is natural that people tend to go through an edit/compile/test cycle with Cython modules. But my personal opinion is that one of the deep insights in Python’s implementation is that a language can be compiled (Python modules are compiled to .pyc) files and hide that compilation process from the end-user so that they do not have to worry about it. Pyximport does this for Cython modules. For instance if you write a Cython module called foo.pyx, with Pyximport you can import it in a regular Python module like this:

import pyximport; pyximport.install()
import foo

Doing so will result in the compilation of foo.pyx (with appropriate exceptions if it has an error in it).

If you would always like to import Cython files without building them specially, you can also the first line above to your sitecustomize.py. That will install the hook every time you run Python. Then you can use Cython modules just with simple import statements. I like to test my Cython modules like this:

$ python -c "import foo"