<commit_before>.. highlight:: cython

.. _profiling:

*********
Profiling
*********

This part describes the profiling abilities of Cython. If you are familiar
with profiling pure Python code, you can only read the first section
(:ref:`profiling_basics`). If you are not familiar with Python profiling you
should also read the tutorial (:ref:`profiling_tutorial`) which takes you
through a complete example step by step.

.. _profiling_basics:

Cython Profiling Basics
=======================

Profiling in Cython is controlled by a compiler directive.
It can be set either for an entire file or on a per function basis
via a Cython decorator.

Enabling profiling for a complete source file
---------------------------------------------

Profiling is enabled for a complete source file via a global directive to the
Cython compiler at the top of a file::

   # cython: profile=True

Note that profiling gives a slight overhead to each function call therefore making
your program a little slower (or a lot, if you call some small functions very
often).

Once enabled, your Cython code will behave just like Python code when called
from the cProfile module. This means you can just profile your Cython code
together with your Python code using the same tools as for Python code alone.

Disabling profiling function wise
---------------------------------

If your profiling is messed up because of the call overhead to some small
functions that you rather do not want to see in your profile - either because
you plan to inline them anyway or because you are sure that you can't make them
any faster - you can use a special decorator to disable profiling for one
function only:

.. literalinclude:: ../../examples/tutorial/profiling_tutorial/often_called.pyx

Enabling line tracing
---------------------

To get more detailed trace information (for tools that can make use of it),
you can enable line tracing::

   # cython: linetrace=True

This will also enable profiling support, so the above ``profile=True`` option
is not needed.  Line tracing is needed for coverage analysis, for example.
<commit_msg>Try to clarify that the @profile(False) decorator is harmless when profiling is disabled anyway.<commit_after>.. highlight:: cython

.. _profiling:

*********
Profiling
*********

This part describes the profiling abilities of Cython. If you are familiar
with profiling pure Python code, you can only read the first section
(:ref:`profiling_basics`). If you are not familiar with Python profiling you
should also read the tutorial (:ref:`profiling_tutorial`) which takes you
through a complete example step by step.

.. _profiling_basics:

Cython Profiling Basics
=======================

Profiling in Cython is controlled by a compiler directive.
It can be set either for an entire file or on a per function basis
via a Cython decorator.

Enabling profiling for a complete source file
---------------------------------------------

Profiling is enabled for a complete source file via a global directive to the
Cython compiler at the top of a file::

   # cython: profile=True

Note that profiling gives a slight overhead to each function call therefore making
your program a little slower (or a lot, if you call some small functions very
often).

Once enabled, your Cython code will behave just like Python code when called
from the cProfile module. This means you can just profile your Cython code
together with your Python code using the same tools as for Python code alone.

Disabling profiling function wise
---------------------------------

If your profiling is messed up because of the call overhead to some small
functions that you rather do not want to see in your profile - either because
you plan to inline them anyway or because you are sure that you can't make them
any faster - you can use a special decorator to disable profiling for one
function only (regardless of whether it is globally enabled or not):

.. literalinclude:: ../../examples/tutorial/profiling_tutorial/often_called.pyx

Enabling line tracing
---------------------

To get more detailed trace information (for tools that can make use of it),
you can enable line tracing::

   # cython: linetrace=True

This will also enable profiling support, so the above ``profile=True`` option
is not needed.  Line tracing is needed for coverage analysis, for example.

{'fraction_non_alphanumeric': 0.10181985717576596, 'fraction_numerical': 0.0, 'mean_word_length': 3.5418410041841004, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, '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': '2965289', 'n_tokens_mistral': 1074, 'n_tokens_neox': 995, 'n_words': 620}