riogrande.timing
================

.. py:module:: riogrande.timing

.. autoapi-nested-parse::

   Provides a simple context manager class for timing code execution and
   recording intermediate durations (laps).



Classes
-------

.. autoapisummary::

   riogrande.timing.TimedTask


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

.. py:class:: TimedTask

   A context manager for measuring elapsed time of code blocks.

   This class allows timing of an entire block of code and
   recording intermediate checkpoints ("laps") within it.
   Internally uses :func:`time.perf_counter` for high-resolution timing.

   .. seealso::

      :meth:`get_duration`
          Return the total elapsed time.
      
      :meth:`new_lab`
          Record an intermediate lap time.

   .. rubric:: Examples

   >>> with TimedTask() as t:
   ...     do_work()
   ...     t.new_lab()
   ...     do_more_work()
   ...
   >>> t.get_duration()
   2.3512  # total seconds elapsed
   >>> t.labs
   [0.7543, 1.5969]  # lap times


   .. py:method:: __enter__()

      Start the timer upon entering the context.

      :returns: The timer instance itself.
      :rtype: TimedTask



   .. py:method:: __exit__(exc_type, exc_value, exc_tb)

      Stop the timer upon exiting the context.

      Records a final lap and stores the total elapsed time
      between start and stop.



   .. py:method:: get_duration()

      Get the total duration measured between start and stop.

      :returns: Total elapsed time in seconds.
      :rtype: float

      .. seealso::

         :meth:`new_lab`
             Record an intermediate lap time.



   .. py:method:: new_lab()

      Record a new lap (checkpoint).

      Each call appends the time elapsed since the previous
      lap (or since the start if it's the first lap).

      .. seealso::

         :meth:`get_duration`
             Return the total elapsed time.



   .. py:attribute:: labs
      :value: []