Commit 83076242 authored by Robert Bradshaw's avatar Robert Bradshaw

Move compilation block to before directives, add note about cython.inline.

parent 01a31397
......@@ -13,9 +13,128 @@ Cython code, unlike Python, must be compiled. This happens in two stages:
* 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.
Compiling from the command line
===============================
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.
Compiling with ``distutils``
============================
First, make sure that ``distutils`` package is installed in your
system. The following assumes a Cython file to be compiled called
*hello.pyx*. Now, create a ``setup.py`` script::
from distutils.core import setup
from distutils.extension import Extension
from Cython.Distutils import build_ext
ext_modules = [Extension("spam", ["spam.pyx"]),
Extension("ham", ["ham.pyx"])]
# You can add directives for each extension too
# by attaching the `pyrex_directives`
for e in ext modules:
e.pyrex_directives = {"boundscheck": False}
setup(
name = "My hello 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 and you are done. Import your new extension
module into your python shell or script as normal.
Cython provides utility code to automatically generate lists of
Extension objects from ```.pyx`` files, so one can write::
from distutils.core import setup
from Cython.Build import cythonize
setup(
name = "My hello app",
ext_modules = cythonize("*.pyx"),
)
to compile all ``.pyx`` files in a given directory.
The ``cythonize`` command also allows for multi-threaded compilation and
dependency resolution.
Compiling with ``pyximport``
=============================
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)
Compiling with ``cython.inline``
=============================
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.
Compiling with 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 functions defined in a Cython cell are imported into the
running session. Please check `Sage documentation
<http://www.sagemath.org/doc/>`_ for details.
You can tailor the behavior of the Cython compiler by specifying the
directives below.
====================
Compiler directives
====================
......@@ -112,6 +231,7 @@ Locally
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
......@@ -127,90 +247,3 @@ statement, like this::
.. Warning:: These two methods of setting directives are **not**
affected by overriding the directive on the command-line using the
-X option.
The following sub-sections describe several ways to build your
extension modules, and how to pass directives to the Cython compiler.
Compiling from the command line
===============================
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.
Compiling with ``distutils``
============================
First, make sure that ``distutils`` package is installed in your
system. The following assumes a Cython file to be compiled called
*hello.pyx*. Now, create a ``setup.py`` script::
from distutils.core import setup
from distutils.extension import Extension
from Cython.Distutils import build_ext
ext_modules = [Extension("spam", ["spam.pyx"]),
Extension("ham", ["ham.pyx"])]
# You can add directives for each extension too
# by attaching the `pyrex_directives`
for e in ext modules:
e.pyrex_directives = {"boundscheck": False}
setup(
name = ’My hello 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 and you are done. Import your new extension
module into your python shell or script as normal.
Compiling with ``pyximport``
=============================
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)
Compiling with 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 functions defined in a Cython cell imported into the
running session. Please check `Sage documentation
<http://www.sagemath.org/doc/>`_ for details.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment