Commit 0ced0629 authored by scoder's avatar scoder Committed by GitHub

Merge pull request #2287 from gabrieldemarmiesse/arguments_cythonize

Added a documentation for the Cythonize function and its arguments.
parents 89f43638 edf2fd7c
......@@ -107,6 +107,8 @@ methods.
Speedup: 150 times over pure Python.
.. _determining_where_to_add_types:
Determining where to add types
------------------------------
......
......@@ -237,6 +237,84 @@ Just as an example, this adds ``mylib`` as library to every extension::
then the argument to ``create_extension`` must be pickleable.
In particular, it cannot be a lambda function.
Cythonize arguments
-------------------
The function :func:`cythonize` can take extra arguments which will allow you to
customize your build.
.. py:function:: cythonize(module_list, \
exclude=None, \
nthreads=0, \
aliases=None, \
quiet=False, \
force=False, \
language=None, \
exclude_failures=False, \
**options)
Compile a set of source modules into C/C++ files and return a list of distutils
Extension objects for them.
:param module_list: As module list, pass either a glob pattern, a list of glob
patterns or a list of Extension objects. The latter
allows you to configure the extensions separately
through the normal distutils options.
You can also pass Extension objects that have
glob patterns as their sources. Then, cythonize
will resolve the pattern and create a
copy of the Extension for every matching file.
:param exclude: When passing glob patterns as ``module_list``, you can exclude certain
module names explicitly by passing them into the ``exclude`` option.
:param nthreads: The number of concurrent builds for parallel compilation
(requires the ``multiprocessing`` module).
:param aliases: If you want to use compiler directives like ``# distutils: ...`` but
can only know at compile time (when running the ``setup.py``) which values
to use, you can use aliases and pass a dictionary mapping those aliases
to Python strings when calling :func:`cythonize`. As an example, say you
want to use the compiler
directive ``# distutils: include_dirs = ../static_libs/include/``
but this path isn't always fixed and you want to find it when running
the ``setup.py``. You can then do ``# distutils: include_dirs = MY_HEADERS``,
find the value of ``MY_HEADERS`` in the ``setup.py``, put it in a python
variable called ``foo`` as a string, and then call
``cythonize(..., aliases={'MY_HEADERS': foo})``.
:param quiet: If True, Cython won't print error and warning messages during the compilation.
:param force: Forces the recompilation of the Cython modules, even if the timestamps
don't indicate that a recompilation is necessary.
:param language: To globally enable C++ mode, you can pass ``language='c++'``. Otherwise, this
will be determined at a per-file level based on compiler directives. This
affects only modules found based on file names. Extension instances passed
into :func:`cythonize` will not be changed. It is recommended to rather
use the compiler directive ``# distutils: language = c++`` than this option.
:param exclude_failures: For a broad 'try to compile' mode that ignores compilation
failures and simply excludes the failed extensions,
pass ``exclude_failures=True``. Note that this only
really makes sense for compiling ``.py`` files which can also
be used without compilation.
:param annotate: If ``True``, will produce a HTML file for each of the ``.pyx`` or ``.py``
files compiled. The HTML file gives an indication
of how much Python interaction there is in
each of the source code lines, compared to plain C code.
It also allows you to see the C/C++ code
generated for each line of Cython code. This report is invaluable when
optimizing a function for speed,
and for determining when to :ref:`release the GIL <nogil>`:
in general, a ``nogil`` block may contain only "white" code.
See examples in :ref:`determining_where_to_add_types` or
:ref:`primes`.
:param compiler_directives: Allow to set compiler directives in the ``setup.py`` like this:
``compiler_directives={'embedsignature': True}``.
See :ref:`compiler-directives`.
Distributing Cython modules
----------------------------
......
......@@ -119,6 +119,8 @@ And use the new extension with::
>>> fib.fib(2000)
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
.. _primes:
Primes
=======
......
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