Cython code, unlike Python, must be compiled. This happens in two stages:
- A .pyx file is compiles by Cython to a .c file.
- The .c file is compiled by a C compiler to a .so file (or a .pyd file on Windows)
The following sub-sections describe several ways to build your extension modules, and how to pass directives to the Cython compiler.
Run the Cython compiler command with your options and list of .pyx files to generate. For example:
$ cython -a yourmod.pyx
This creates a yourmod.c file, and the -a switch produces a generated html file. Pass the -h flag for a complete list of supported flags.
Compiling your .c files will vary depending on your operating system. Python documentation for writing extension modules should have some details for your system. Here we give an example on a Linux system:
$ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing \ -I/usr/include/python2.5 -o yourmod.so yourmod.c
[gcc will need to have paths to your included header files and paths to libraries you need to link with]
A yourmod.so file is now in the same directory and your module, yourmod, is available for you to import as you normally would.
First, make sure that distutils package is installed in your system. It normally comes as part of the standard library. The following assumes a Cython file to be compiled called hello.pyx. Now, create a setup.py script:
from distutils.core import setup from Cython.Build import cythonize setup( name = "My hello app", ext_modules = cythonize('hello.pyx'), # accepts a glob pattern )
Run the command python setup.py build_ext --inplace in your system’s command shell and you are done. Import your new extension module into your python shell or script as normal.
The cythonize command also allows for multi-threaded compilation and dependency resolution. Recompilation will be skipped if the target file is up to date with its main source file and dependencies.
If you have include files in non-standard places you can pass an include_path parameter to cythonize:
from distutils.core import setup from Cython.Build import cythonize setup( name = "My hello app", ext_modules = cythonize("src/*.pyx", include_path = [...]), )
Often, Python packages that offer a C-level API provide a way to find the necessary include files, e.g. for NumPy:
include_path = [numpy.get_include()]
If you need to specify compiler options, libraries to link with or other linker options you will need to create Extension instances manually (note that glob syntax can still be used to specify multiple extensions in one line):
from distutils.core import setup from distutils.extension import Extension from Cython.Build import cythonize extensions = [ Extension("primes", ["primes.pyx"], include_dirs = [...], libraries = [...], library_dirs = [...]), # Everything but primes.pyx is included here. Extension("*", ["*.pyx"], include_dirs = [...], libraries = [...], library_dirs = [...]), ] setup( name = "My hello app", ext_modules = cythonize(extensions), )
If your options are static (for example you do not need to call a tool like pkg-config to determine them) you can also provide them directly in your .pyx source file using a special comment block at the start of the file:
# distutils: libraries = spam eggs # distutils: include_dirs = /opt/food/include
If you have some C files that have been wrapped with Cython and you want to compile them into your extension, you can define the distutils sources parameter:
# distutils: sources = helper.c, another_helper.c
Note that these sources are added to the list of sources of the current extension module. Spelling this out in the setup.py file looks as follows:
from distutils.core import setup from Cython.Build import cythonize from distutils.extension import Extension sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c'] extensions = [Extension("example", sourcefiles)] setup( ext_modules = cythonize(extensions) )
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.
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/she probably doesn’t want to use it just to install your module. Also, the installed version 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"])] )
This is easy to combine with cythonize() by changing the file extension of the extension module sources:
from distutils.core import setup from distutils.extension import Extension USE_CYTHON = ... # command line option, try-import, ... ext = '.pyx' if USE_CYTHON else '.c' extensions = [Extension("example", ["example"+ext])] if USE_CYTHON: from Cython.Build import cythonize extensions = cythonize(extensions) setup( ext_modules = extensions )
For generating Cython code right in your pure python module just type:
>>> import pyximport; pyximport.install() >>> import helloworld Hello World
This allows you to automatically run Cython on every .pyx that Python is trying to import. You should use this for simple Cython builds only where no extra C libraries and no special building setup is needed.
In the case that Cython fails to compile a Python module, pyximport will fall back to loading the source modules instead.
It is also possible to compile new .py modules that are being imported (including the standard library and installed packages). For using this feature, just tell that to pyximport:
>>> pyximport.install(pyimport = True)
One can also compile Cython in a fashion similar to SciPy’s weave.inline. For example:
>>> import cython >>> def f(a): ... ret = cython.inline("return a+b", b=3) ...
Unbound variables are automatically pulled from the surrounding local and global scopes, and the result of the compilation is cached for efficient re-use.
The Sage notebook allows transparently editing and compiling Cython code simply by typing %cython at the top of a cell and evaluate it. Variables and functions defined in a Cython cell are imported into the running session. Please check Sage documentation for details.
You can tailor the behavior of the Cython compiler by specifying the directives below.
Compiler directives are instructions which affect the behavior of Cython code. Here is the list of currently supported directives:
Add line tracing hooks for Python profilers into the compiled C code. This also enables profiling. Default is False. Note that the generated module will not actually use line tracing, unless you additionally pass the C macro definition CYTHON_TRACE=1 to the C compiler (e.g. using the distutils option define_macros).
Note that this feature is currently EXPERIMENTAL. It will slow down your code, may not work at all for what you want to do with it, and may even crash arbitrarily.
One can set compiler directives through a special header comment at the top of the file, like this:
#!python #cython: boundscheck=False
The comment must appear before any code (but can appear after other comments or whitespace).
One can also pass a directive on the command line by using the -X switch:
$ cython -X boundscheck=True ...
Directives passed on the command line will override directives set in header comments.
For local blocks, you need to cimport the special builtin cython module:
#!python cimport cython
Then you can use the directives either as decorators or in a with statement, like this:
#!python @cython.boundscheck(False) # turn off boundscheck for this function def f(): ... with cython.boundscheck(True): # turn it temporarily on again for this block ...
These two methods of setting directives are not affected by overriding the directive on the command-line using the -X option.