:mod:`pytimings.timer`
======================

.. py:module:: pytimings.timer
.. autoapi-nested-parse::

   Main module.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   pytimings.timer.TimingDelta
   pytimings.timer.TimingData
   pytimings.timer.Timings



Functions
~~~~~~~~~

.. autoapisummary::
  :nosignatures:

   pytimings.timer.scoped_timing
   pytimings.timer.cummulative_scoped_timing
   pytimings.timer.function_timer



Attributes
~~~~~~~~~~

.. autoapisummary::

   pytimings.timer.THREAD_TIME
   pytimings.timer.WALL_TIME
   pytimings.timer.SYS_TIME
   pytimings.timer.USER_TIME
   pytimings.timer.global_timings


.. py:data:: THREAD_TIME
   :value: 'thread'


.. py:data:: WALL_TIME
   :value: 'wall'


.. py:data:: SYS_TIME
   :value: 'sys'


.. py:data:: USER_TIME
   :value: 'user'


.. py:class:: TimingDelta

   Bases: :py:obj:`NamedTuple`


   Elapsed wall/system/user time for a section, all in seconds.


   .. py:attribute:: wall
      :type:  float


   .. py:attribute:: sys
      :type:  float


   .. py:attribute:: user
      :type:  float


.. py:exception:: NoTimerError(section: str, timings: Timings | None = None, is_unstopped: bool = False)

   Bases: :py:obj:`Exception`


   Common base class for all non-exit exceptions.


   .. py:attribute:: section


   .. py:attribute:: timings


   .. py:attribute:: is_unstopped
      :value: False



.. py:class:: TimingData(name: str)

   .. py:attribute:: name


   .. py:attribute:: _end_resources
      :value: None



   .. py:attribute:: _end_times
      :type:  dict[str, float] | None
      :value: None



   .. py:attribute:: _process


   .. py:attribute:: _start_times


   .. py:method:: _get() -> dict[str, float]


   .. py:method:: stop() -> None


   .. py:method:: delta() -> TimingDelta


.. py:class:: Timings

   .. py:attribute:: _commited_deltas
      :type:  dict[str, TimingDelta]


   .. py:attribute:: _known_timers_map
      :type:  dict[str, tuple[bool, TimingData | None]]


   .. py:attribute:: extra_data
      :type:  dict


   .. py:method:: start(section_name: str) -> None

      set this to begin a named section



   .. py:method:: stop(section_name: str | None = None) -> TimingDelta | None

      stop named section's counter or all of them if section_name is None



   .. py:method:: reset(section_name: str | None = None) -> None

      set elapsed time back to 0 for a given section or all of them if section_name is None



   .. py:method:: walltime(section_name: str) -> float

      get runtime of section in seconds



   .. py:method:: add_walltime(section_name: str, time: float) -> None


   .. py:method:: delta(section_name: str) -> TimingDelta

      get the full delta tuple



   .. py:method:: output_files(output_dir: str | pathlib.Path, csv_base: str) -> pathlib.Path

      output all recorded measures to a csv file



   .. py:method:: output_console() -> None

      output the recorded walltime per section to the console



   .. py:method:: output_all_measures(out=None) -> None

      output all recorded measures



   .. py:method:: add_extra_data(data: dict) -> None

      Use this for configuration data that makes the csv more informative.

      The data is also rendered in the console output.



.. py:data:: global_timings

.. py:function:: scoped_timing(section_name: str, log_function: collections.abc.Callable[[str], None] | None = None, timings: Timings | None = None, format: str = '') -> collections.abc.Iterator[None]

   Start timer on entering block scope, stop it (and optionally output) on exiting.

   The printout will only show walltime for the current scope.
   See :py:func:`pytimings.timer.cummulative_scoped_timing` for a version with cummulative output.


.. py:function:: cummulative_scoped_timing(section_name: str, log_function: collections.abc.Callable[[str], None] | None = None, timings: Timings | None = None, format: str = '') -> collections.abc.Iterator[None]

   Start timer on entering block scope, stop it (and optionally output) on exiting.

   The printout will show the cummulated walltime for all scopes with this section name.
   See :py:func:`pytimings.timer.scoped_timing` for a version with non-cummulative output.


.. py:function:: function_timer(section_name: str | None = None, log_function: collections.abc.Callable[[str], None] | None = None, timings: Timings | None = None) -> collections.abc.Callable