diff options
Diffstat (limited to 'docs/src/tutorial/pure.rst')
| -rw-r--r-- | docs/src/tutorial/pure.rst | 186 |
1 files changed, 165 insertions, 21 deletions
diff --git a/docs/src/tutorial/pure.rst b/docs/src/tutorial/pure.rst index 775e7719c..32a7fa0ca 100644 --- a/docs/src/tutorial/pure.rst +++ b/docs/src/tutorial/pure.rst @@ -13,7 +13,7 @@ To go beyond that, Cython provides language constructs to add static typing and cythonic functionalities to a Python module to make it run much faster when compiled, while still allowing it to be interpreted. This is accomplished via an augmenting ``.pxd`` file, via Python -type annotations (following +type :ref:`pep484_type_annotations` (following `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ and `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_), and/or via special functions and decorators available after importing the magic @@ -29,6 +29,7 @@ In pure mode, you are more or less restricted to code that can be expressed beyond that can only be done in .pyx files with extended language syntax, because it depends on features of the Cython compiler. +.. _augmenting_pxd: Augmenting .pxd --------------- @@ -82,7 +83,7 @@ in the :file:`.pxd`, that is, to be accessible from Python, In the example above, the type of the local variable `a` in `myfunction()` -is not fixed and will thus be a Python object. To statically type it, one +is not fixed and will thus be a :term:`Python object`. To statically type it, one can use Cython's ``@cython.locals`` decorator (see :ref:`magic_attributes`, and :ref:`magic_attributes_pxd`). @@ -153,26 +154,10 @@ Static typing @exceptval(-1, check=False) # cdef int func() except -1: @exceptval(check=True) # cdef int func() except *: @exceptval(-1, check=True) # cdef int func() except? -1: + @exceptval(check=False) # no exception checking/propagation -* Python annotations can be used to declare argument types, as shown in the - following example. To avoid conflicts with other kinds of annotation - usages, this can be disabled with the directive ``annotation_typing=False``. - - .. literalinclude:: ../../examples/tutorial/pure/annotations.py - - This can be combined with the ``@cython.exceptval()`` decorator for non-Python - return types: - - .. literalinclude:: ../../examples/tutorial/pure/exceptval.py - - Since version 0.27, Cython also supports the variable annotations defined - in `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_. This allows to - declare types of variables in a Python 3.6 compatible way as follows: - - .. literalinclude:: ../../examples/tutorial/pure/pep_526.py - - There is currently no way to express the visibility of object attributes. - + If exception propagation is disabled, any Python exceptions that are raised + inside of the function will be printed and ignored. C types ^^^^^^^ @@ -225,6 +210,68 @@ Here is an example of a :keyword:`cdef` function:: return a == b +Managing the Global Interpreter Lock +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* ``cython.nogil`` can be used as a context manager or as a decorator to replace the :keyword:`nogil` keyword:: + + with cython.nogil: + # code block with the GIL released + + @cython.nogil + @cython.cfunc + def func_released_gil() -> cython.int: + # function that can be run with the GIL released + + Note that the two uses differ: the context manager releases the GIL while the decorator marks that a + function *can* be run without the GIL. See :ref:`<cython_and_gil>` for more details. + +* ``cython.gil`` can be used as a context manager to replace the :keyword:`gil` keyword:: + + with cython.gil: + # code block with the GIL acquired + + .. Note:: Cython currently does not support the ``@cython.with_gil`` decorator. + +Both directives accept an optional boolean parameter for conditionally +releasing or acquiring the GIL. The condition must be constant (at compile time):: + + with cython.nogil(False): + # code block with the GIL not released + + @cython.nogil(True) + @cython.cfunc + def func_released_gil() -> cython.int: + # function with the GIL released + + with cython.gil(False): + # code block with the GIL not acquired + + with cython.gil(True): + # code block with the GIL acquired + +A common use case for conditionally acquiring and releasing the GIL are fused types +that allow different GIL handling depending on the specific type (see :ref:`gil_conditional`). + +.. py:module:: cython.cimports + +cimports +^^^^^^^^ + +The special ``cython.cimports`` package name gives access to cimports +in code that uses Python syntax. Note that this does not mean that C +libraries become available to Python code. It only means that you can +tell Cython what cimports you want to use, without requiring special +syntax. Running such code in plain Python will fail. + +.. literalinclude:: ../../examples/tutorial/pure/py_cimport.py + +Since such code must necessarily refer to the non-existing +``cython.cimports`` 'package', the plain cimport form +``cimport cython.cimports...`` is not available. +You must use the form ``from cython.cimports...``. + + Further Cython functions and declarations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -242,6 +289,13 @@ Further Cython functions and declarations print(cython.sizeof(cython.longlong)) print(cython.sizeof(n)) +* ``typeof`` returns a string representation of the argument's type for debugging purposes. It can take expressions. + + :: + + cython.declare(n=cython.longlong) + print(cython.typeof(n)) + * ``struct`` can be used to create struct types.:: MyStruct = cython.struct(x=cython.int, y=cython.int, data=cython.double) @@ -272,6 +326,12 @@ Further Cython functions and declarations t1 = cython.cast(T, t) t2 = cython.cast(T, t, typecheck=True) +* ``fused_type`` creates a new type definition that refers to the multiple types. + The following example declares a new type called ``my_fused_type`` which can + be either an ``int`` or a ``double``.:: + + my_fused_type = cython.fused_type(cython.int, cython.float) + .. _magic_attributes_pxd: Magic Attributes within the .pxd @@ -289,10 +349,94 @@ can be augmented with the following :file:`.pxd` file :file:`dostuff.pxd`: The :func:`cython.declare()` function can be used to specify types for global variables in the augmenting :file:`.pxd` file. +.. _pep484_type_annotations: + +PEP-484 type annotations +------------------------ + +Python `type hints <https://www.python.org/dev/peps/pep-0484>`_ +can be used to declare argument types, as shown in the +following example: + + .. literalinclude:: ../../examples/tutorial/pure/annotations.py + +Note the use of ``cython.int`` rather than ``int`` - Cython does not translate +an ``int`` annotation to a C integer by default since the behaviour can be +quite different with respect to overflow and division. + +Annotations can be combined with the ``@cython.exceptval()`` decorator for non-Python +return types: + + .. literalinclude:: ../../examples/tutorial/pure/exceptval.py + +Note that the default exception handling behaviour when returning C numeric types +is to check for ``-1``, and if that was returned, check Python's error indicator +for an exception. This means, if no ``@exceptval`` decorator is provided, and the +return type is a numeric type, then the default with type annotations is +``@exceptval(-1, check=True)``, in order to make sure that exceptions are correctly +and efficiently reported to the caller. Exception propagation can be disabled +explicitly with ``@exceptval(check=False)``, in which case any Python exceptions +raised inside of the function will be printed and ignored. + +Since version 0.27, Cython also supports the variable annotations defined +in `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_. This allows to +declare types of variables in a Python 3.6 compatible way as follows: + +.. literalinclude:: ../../examples/tutorial/pure/pep_526.py + +There is currently no way to express the visibility of object attributes. + +Disabling annotations +^^^^^^^^^^^^^^^^^^^^^ + +To avoid conflicts with other kinds of annotation +usages, Cython's use of annotations to specify types can be disabled with the +``annotation_typing`` :ref:`compiler directive<compiler-directives>`. From Cython 3 +you can use this as a decorator or a with statement, as shown in the following example: + +.. literalinclude:: ../../examples/tutorial/pure/disabled_annotations.py + + + +``typing`` Module +^^^^^^^^^^^^^^^^^ + +Support for the full range of annotations described by PEP-484 is not yet +complete. Cython 3 currently understands the following features from the +``typing`` module: + +* ``Optional[tp]``, which is interpreted as ``tp or None``; +* typed containers such as ``List[str]``, which is interpreted as ``list``. The + hint that the elements are of type ``str`` is currently ignored; +* ``Tuple[...]``, which is converted into a Cython C-tuple where possible + and a regular Python ``tuple`` otherwise. +* ``ClassVar[...]``, which is understood in the context of + ``cdef class`` or ``@cython.cclass``. + +Some of the unsupported features are likely to remain +unsupported since these type hints are not relevant for the compilation to +efficient C code. In other cases, however, where the generated C code could +benefit from these type hints but does not currently, help is welcome to +improve the type analysis in Cython. + +Reference table +^^^^^^^^^^^^^^^ + +The following reference table documents how type annotations are currently interpreted. +Cython 0.29 behaviour is only shown where it differs from Cython 3.0 behaviour. +The current limitations will likely be lifted at some point. + +.. csv-table:: Annotation typing rules + :file: annotation_typing_table.csv + :header-rows: 1 + :class: longtable + :widths: 1 1 1 Tips and Tricks --------------- +.. _calling-c-functions: + Calling C functions ^^^^^^^^^^^^^^^^^^^ |