Commit 2ca8b948 authored by gabrieldemarmiesse's avatar gabrieldemarmiesse

Removed the description of cythonize in the docs and instead, moved it to the...

Removed the description of cythonize in the docs and instead, moved it to the docstring and used autodocs to pull it in the docs.
parent c2a3457a
......@@ -871,27 +871,65 @@ def cythonize(module_list, exclude=None, nthreads=0, aliases=None, quiet=False,
Compile a set of source modules into C/C++ files and return a list of distutils
Extension objects for them.
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.
When using glob patterns, you can exclude certain module names explicitly
by passing them into the 'exclude' option.
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 cythonize() will not be changed.
For parallel compilation, set the 'nthreads' option to the number of
concurrent builds.
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.
Additional compilation options can be passed as keyword arguments.
: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`.
"""
if exclude is None:
exclude = []
......
......@@ -243,78 +243,8 @@ 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`.
.. autofunction:: Cython.Build.cythonize
Distributing Cython modules
----------------------------
......
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