# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['ipython_console_highlighting', 'cython_highlighting', 'sphinx.ext.pngmath', 'sphinx.ext.todo']
+extensions = ['ipython_console_highlighting', 'cython_highlighting', 'sphinx.ext.pngmath', 'sphinx.ext.todo', 'sphinx.ext.intersphinx']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# todo
todo_include_todos = True
+
+# intersphinx for standard :keyword:s (def, for, etc.)
+intersphinx_mapping = {'python': ('http://docs.python.org/3.2', None)}
def analyse_text(text):
return shebang_matches(text, r'pythonw?(2\.\d)?')
-highlighting.lexers['cython'] = CythonLexer()
+def setup(app):
+ app.add_lexer('cython', CythonLexer())
pylexer.get_tokens_unprocessed(curcode)):
yield item
-highlighting.lexers['ipython'] = IPythonConsoleLexer()
+
+def setup(app):
+ app.add_lexer('ipython', IPythonConsoleLexer())
.. highlight:: cython
-.. _compilation:
+.. _compilation-reference:
=============
Compilation
Providing static typing to parameters and variables is convenience to speed up your code, but it is not a necessity. Optimize where and when needed.
+
The cdef Statement
==================
* Return Python objects
* See **Parameters** for special consideration
+.. _cdef:
+
Callable from C
================
* Are called with either Python objects or C values.
* Can return either Python objects or C values.
+.. _cpdef:
+
Callable from both Python and C
================================
Speed comes with some cost. Especially it can be dangerous to set typed
objects (like ``f``, ``g`` and ``h`` in our sample code) to
- :keyword:`None`. Setting such objects to :keyword:`None` is entirely
+ ``None``. Setting such objects to ``None`` is entirely
legal, but all you can do with them is check whether they are None. All
other use (attribute lookup or indexing) can potentially segfault or
corrupt data (rather than raising exceptions as they would in Python).
Functions returning borrowed references were already mentioned as requiring
special care, but they also induce substantially more runtime overhead because
they often create weak references in PyPy where they only return a plain
-pointer in CPython. A visible example is :c:func:``PyTuple_GET_ITEM()`.
+pointer in CPython. A visible example is :c:func:`PyTuple_GET_ITEM()`.
Some more high-level functions may also show entirely different performance
characteristics, e.g. :c:func:`PyDict_Next()` for dict iteration. While
.. note::
in earlier versions of Cython, the :keyword:`cpdef` keyword is
- :keyword:`rdef` - but has the same effect).
+ ``rdef`` - but has the same effect).
Here, we just have a single area method, declared as :keyword:`cpdef` to make it
efficiently callable as a C function, but still accessible from pure Python
extension types to wrap arbitrary C data structures and provide a Python-like
interface to them.
+.. _readonly:
+
Attributes
============
.. sourcecode:: c
- ctypedef struct {
+ typedef struct {
...
} PyComplexObject;
3. When declaring an external extension type, you don't declare any
methods. Declaration of methods is not required in order to call them,
because the calls are Python method calls. Also, as with
- :keyword:`structs` and :keyword:`unions`, if your extension class
+ :keyword:`struct` and :keyword:`union`, if your extension class
declaration is inside a :keyword:`cdef` extern from block, you only need to
declare those C members which you wish to access.
be used for this new type.
5. If the header file uses macros to define constants, translate them into a
- dummy ``enum`` declaration.
+ dummy :keyword:`enum` declaration.
6. If the header file defines a function using a macro, declare it as though
it were an ordinary function, with appropriate argument and result types.
-7. For archaic reasons C uses the keyword :keyword:`void` to declare a function
+7. For archaic reasons C uses the keyword ``void`` to declare a function
taking no parameters. In Cython as in Python, simply declare such functions
as :meth:`foo()`.
cdef extern from *:
...
+.. _struct-union-enum-styles:
+
Styles of struct, union and enum declaration
----------------------------------------------
file consists of the full dotted name of the module, e.g. a module called
:mod:`foo.spam` would have a header file called :file:`foo.spam.h`.
+.. _api:
+
C API Declarations
-------------------
^^^^^^^^^^^^^^^^^
You can release the GIL around a section of code using the
-:keyword:`with nogil` statement::
+``with nogil`` statement::
with nogil:
<code to be executed with the GIL released>
way, and must not call anything that manipulates Python objects without first
re-acquiring the GIL. Cython currently does not check this.
+.. _gil:
+
Acquiring the GIL
^^^^^^^^^^^^^^^^^
.. highlight:: cython
.. _language-basics:
+.. _struct:
+.. _union:
+.. _enum:
+.. _ctypedef:
+
*****************
Language Basics
soft = 2
runny = 3
+See also :ref:`struct-union-enum-styles`
+
There is currently no special syntax for defining a constant, but you can use
an anonymous :keyword:`enum` declaration for this purpose, for example,::
.. Warning::
Speed comes with some cost. Especially it can be dangerous to set typed
- objects (like ``f``, ``g`` and ``h`` in our sample code) to :keyword:`None`.
- Setting such objects to :keyword:`None` is entirely legal, but all you can do with them
+ objects (like ``f``, ``g`` and ``h`` in our sample code) to ``None``.
+ Setting such objects to ``None`` is entirely legal, but all you can do with them
is check whether they are None. All other use (attribute lookup or indexing)
can potentially segfault or corrupt data (rather than raising exceptions as
they would in Python).
The actual rules are a bit more complicated but the main message is clear: Do
- not use typed objects without knowing that they are not set to None.
+ not use typed objects without knowing that they are not set to ``None``.
More generic code
==================
.. NOTE:: Functionality in this module may only be used from the main thread
or parallel regions due to OpenMP restrictions.
-__ nogil_
.. function:: prange([start,] stop[, step][, nogil=False][, schedule=None[, chunksize=None]][, num_threads=None])
Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C).
+
+.. _inline:
+
cdef inline
=============
Function pointers in structs
=============================
-Functions declared in :keyword:`structs` are automatically converted to
+Functions declared in :keyword:`struct` are automatically converted to
function pointers for convenience.
C++ Exception handling
Automatic ``typecheck``
========================
-Rather than introducing a new keyword :keyword:`typecheck` as explained in the
+Rather than introducing a new keyword ``typecheck`` as explained in the
`Pyrex docs
<http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/Manual/special_methods.html>`_,
Cython emits a (non-spoofable and faster) typecheck whenever
If one doesn't need to :keyword:`cimport` anything from this module, then this
is the only file one needs.
+.. _cimport:
+
The cimport statement
=======================
Source Files and Compilation
****************************
+.. note:: See :ref:`compilation-reference` reference section for more details
+
Cython source file names consist of the name of the module followed by a
``.pyx`` extension, for example a module called primes would have a source
file named :file:`primes.pyx`.
projects / platform / upstream / python-cython.git / commitdiff