.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/basic-usage.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_basic-usage.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_basic-usage.py:


===================
Basic Usage Example
===================

This is a basic usage example of the `stopuhr` package.

.. GENERATED FROM PYTHON SOURCE LINES 12-13

Stop the time with a simple context manager and print the duration.

.. GENERATED FROM PYTHON SOURCE LINES 13-20

.. code-block:: Python

    import time

    from stopuhr import stopuhr

    with stopuhr("Sleeping"):
        time.sleep(0.1)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Sleeping took 0.10s




.. GENERATED FROM PYTHON SOURCE LINES 21-22

Instead of printing, one can pass any callable to the `printer` argument, e.g. a logger.

.. GENERATED FROM PYTHON SOURCE LINES 22-33

.. code-block:: Python

    import logging

    logger = logging.getLogger(__name__)
    logger.setLevel(logging.INFO)
    handler = logging.StreamHandler()
    handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
    logger.addHandler(handler)

    with stopuhr("Sleeping", printer=logger.info):
        time.sleep(0.1)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    2025-04-01 14:40:02,013 - __main__ - INFO - Sleeping took 0.10s




.. GENERATED FROM PYTHON SOURCE LINES 34-35

By default, the output is rounded to two decimal places. This can be changed with the `res` argument.

.. GENERATED FROM PYTHON SOURCE LINES 35-39

.. code-block:: Python

    with stopuhr("Sleeping", res=3):
        time.sleep(0.16189)






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Sleeping took 0.162s




.. GENERATED FROM PYTHON SOURCE LINES 40-43

Use a stateful timer to measure the time taken in a loop.
This also supports the `printer` and `res` arguments.
The `log` argument of each call can be used to suppress the output.

.. GENERATED FROM PYTHON SOURCE LINES 43-54

.. code-block:: Python

    from stopuhr import StopUhr

    stopuhr = StopUhr()

    for i in range(5):
        with stopuhr("Sleeping", log=False):
            time.sleep(0.2)

    # Print a summary with the mean and standard deviation of the durations.
    stopuhr.summary()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Sleeping took 0.20 ± 0.00s (n=5 -> total=1.00s)




.. GENERATED FROM PYTHON SOURCE LINES 55-56

The `reset`` command resets the state of the timer, note that this function is happening in-place.

.. GENERATED FROM PYTHON SOURCE LINES 56-58

.. code-block:: Python

    stopuhr.reset()








.. GENERATED FROM PYTHON SOURCE LINES 59-61

The previous behavior can be achieved with the `start` and `stop` methods.
Here, the `stop` method also supports the `log` and `res` arguments.

.. GENERATED FROM PYTHON SOURCE LINES 61-68

.. code-block:: Python

    for i in range(5):
        stopuhr.start("Sleeping")
        time.sleep(0.2)
        stopuhr.stop("Sleeping", log=False)

    stopuhr.summary()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Sleeping took 0.20 ± 0.00s (n=5 -> total=1.00s)




.. GENERATED FROM PYTHON SOURCE LINES 69-70

The stateful timer can also measure multiple durations at once.

.. GENERATED FROM PYTHON SOURCE LINES 70-85

.. code-block:: Python


    stopuhr.reset()

    # Single duration
    with stopuhr("A (single 0.2s sleep)", log=False):
        time.sleep(0.2)

    for i in range(5):
        with stopuhr("B (multiple 0.2s sleeps)", log=False):
            time.sleep(0.2)
        with stopuhr("C (multiple 0.1s sleeps)", log=False):
            time.sleep(0.1)

    stopuhr.summary()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    A (single 0.2s sleep) took 0.20s
    B (multiple 0.2s sleeps) took 0.20 ± 0.00s (n=5 -> total=1.00s)
    C (multiple 0.1s sleeps) took 0.10 ± 0.00s (n=5 -> total=0.50s)




.. GENERATED FROM PYTHON SOURCE LINES 86-88

A stateless decorator can be used to measure the duration of a function.
The decorator expects a message / key, just like the others and also supports the `printer` and `res` arguments.

.. GENERATED FROM PYTHON SOURCE LINES 88-98

.. code-block:: Python

    from stopuhr import funkuhr


    @funkuhr("Busy Function")
    def busy_function():
        time.sleep(0.2)


    busy_function()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Busy Function took 0.20s




.. GENERATED FROM PYTHON SOURCE LINES 99-101

A stateful decorator exists as well, which is just a wrapper around the stateful timer.
It supports the same arguments as the stateful timer.

.. GENERATED FROM PYTHON SOURCE LINES 101-115

.. code-block:: Python

    from stopuhr import FunkUhr

    funkuhr = FunkUhr()


    @funkuhr("Busy Function", log=False)
    def busy_function():
        time.sleep(0.1)


    for i in range(5):
        busy_function()

    funkuhr.summary()




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Busy Function took 0.10 ± 0.00s (n=5 -> total=0.50s)





.. _sphx_glr_download_auto_examples_basic-usage.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: basic-usage.ipynb <basic-usage.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: basic-usage.py <basic-usage.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: basic-usage.zip <basic-usage.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_