Compilation¶
- 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 comiler to a.so
file (or a.pyd
file on Windows)
- The following sub-sections describe several ways to build your extension modules.
Note
The -a
option
- Using the Cython compiler with the
-a
option will produce a really nice HTML file of the Cython generated.c
code. - Double clicking on the highlighted sections will expand the code to reveal what Cython has actually generated for you.
- This is very useful for understanding, optimizing or debugging your module.
From the Command Line¶
Run the Cython compiler command with your options and list of
.pyx
files to generate:$ cython -a yourmod.pyx
This creates a
yourmod.c
file. (and the -a switch produces a generated html file)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.- Your module,
yourmod
is available for you to import as you normally would.
Distutils¶
Ensure Distutils is installed in your system.
The following assumes a Cython file to be compiled called hello.pyx.
Create a
setup.py
script:from distutils.core import setup from distutils.extension import Extension from Cython.Distutils import build_ext ext_modules = [Extension("hello", ["hello.pyx"])] setup( name = ’Hello world app’, cmdclass = {’build_ext’: build_ext}, ext_modules = ext_modules )
Run the command
python setup.py build_ext --inplace
in your system’s command shell.Your done.. import your new extension module into your python shell or script as normal.
SCons¶
to be completed...
Pyximport¶
For generating Cython code right in your pure python modulce:
>>> import pyximport; pyximport.install() >>> import helloworld Hello World
Use for simple Cython builds only.
- No extra C libraries.
- No special build setup needed.
- Also has experimental compilation support for normal Python modules.
- Allows you to automatically run Cython on every
.pyx
and.py
module that Python imports.
- This includes the standard library and installed packages.
- In the case that Cython fails to compile a Python module, pyximport will fall back to loading the source modules instead.
The
.py
import mechanism is installed like this:>>> pyximport.install(pyimport = True)
Note
Authors
Paul Prescod, Stefan Behnal
Sage¶
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 func- tions defined in a Cython cell imported into the run- ning session.
Todo
Provide a link to Sage docs