stopwatch#

stopuhr.stopwatch = <stopuhr.chrono.Chronometer object>#

Very high level benchmarking contextmanager and decorator.

Example

Measure the time taken in a code block.

>>> import stopuhr

>>> timer = stopuhr.Chronometer()
>>> with timer("Sleeping"):
>>>     time.sleep(0.2)

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

>>> 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)

>>> timer = stopuhr.Chronometer(printer=logger.info)
>>> with timer("Sleeping"):
>>>     time.sleep(0.1)
2025-03-27 19:11:10,912 - __main__ - INFO - Sleeping took 0.10s

The printer can be overridden for each call.

>>> timer = stopuhr.Chronometer(printer=logger.info)
>>> with timer("Sleeping", printer=logger.debug):
>>>     time.sleep(0.1)
2025-03-27 19:11:10,912 - __main__ - DEBUG - Sleeping took 0.10s

By default, the output is rounded to two decimal places. This can be changed with the res argument. The res argument can also be overridden for each call.

>>> timer = stopuhr.Chronometer(res=3)
>>> with timer("Sleeping"):
>>>     time.sleep(0.16189)
Sleeping took 0.162 s

>>> with timer("Sleeping", res=2):
>>>     time.sleep(0.16189)
Sleeping took 0.16 s

The chronometer is stateful and can be used to measure functions inside a loop. The log argument of each call can be used to suppress the output. It can also be set individually for each call.

>>> timer = stopuhr.Chronometer(log=False)

>>> for i in range(5):
>>>     with timer("Sleeping"):
>>>         time.sleep(0.2)

>>> # Print a summary with the mean and standard deviation of the durations.
>>> timer.summary()
Sleeping took 0.20 ± 0.00 s (n=5 -> total=1.00s)

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

>>> timer.reset()

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

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

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

The stateful timer can also measure multiple durations at once.

>>> timer.reset()

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

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

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

The export method can be used to export the durations as a pandas DataFrame.

>>> import pandas as pd

>>> timer.reset()

>>> for i in range(5):
>>>     with timer("Sleeping", log=False):
>>>         time.sleep(0.2)
>>> for i in range(3):
>>>     with timer("Sleeping-2", log=False):
>>>         time.sleep(0.2)

>>> df = timer.export()
>>> print(df)
  Sleeping-2  Sleeping
0  0.2         0.2
1  0.2         0.2
2  0.2         0.2
3  0.2
4  0.2

stopwatch#

This Page