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 = [...]),
)
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
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
...
Warning
These two methods of setting directives are not affected by overriding the directive on the command-line using the -X option.