<commit_before>
.. _pure-mode:

Pure Python Mode
================

In some cases, it's desirable to speed up Python code without losing the
ability to run it with the Python interpreter.  While pure Python scripts
can be compiled with Cython, it usually results only in a speed gain of
about 20%-50%.

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 either via an augmenting :file:`.pxd` file, or
via special functions and decorators available after importing the magic
``cython`` module.

Although it is not typically recommended over writing straight Cython code
in a :file:`.pyx` file, there are legitimate reasons to do this - easier
testing, collaboration with pure Python developers, etc.  In pure mode, you
are more or less restricted to code that can be expressed (or at least
emulated) in Python, plus static type declarations. Anything beyond that
can only be done in .pyx files with extended language syntax, because it
depends on features of the Cython compiler.


Augmenting .pxd
---------------

Using an augmenting :file:`.pxd` allows to let the original :file:`.py` file
completely untouched.  On the other hand, one needs to maintain both the
:file:`.pxd` and the :file:`.py` to keep them in sync.

While declarations in a :file:`.pyx` file must correspond exactly with those<commit_msg>Mention more prominently in the docs that PEP-484/526 are supported normally. Closes #2587.<commit_after>
.. _pure-mode:

Pure Python Mode
================

In some cases, it's desirable to speed up Python code without losing the
ability to run it with the Python interpreter.  While pure Python scripts
can be compiled with Cython, it usually results only in a speed gain of
about 20%-50%.

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 either via an augmenting ``.pxd`` file, via Python
type annotations (following
`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ and
`PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_), or
via special functions and decorators available after importing the magic
``cython`` module.

Although it is not typically recommended over writing straight Cython code
in a :file:`.pyx` file, there are legitimate reasons to do this - easier
testing, collaboration with pure Python developers, etc.  In pure mode, you
are more or less restricted to code that can be expressed (or at least
emulated) in Python, plus static type declarations. Anything beyond that
can only be done in .pyx files with extended language syntax, because it
depends on features of the Cython compiler.


Augmenting .pxd
---------------

Using an augmenting :file:`.pxd` allows to let the original :file:`.py` file
completely untouched.  On the other hand, one needs to maintain both the
:file:`.pxd` and the :file:`.py` to keep them in sync.

While declarations in a :file:`.pyx` file must correspond exactly with those
{'fraction_non_alphanumeric': 0.07810059356451109, 'fraction_numerical': 0.00999687597625742, 'mean_word_length': 4.327787021630615, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6170058', 'n_tokens_mistral': 863, 'n_tokens_neox': 811, 'n_words': 473}