timerun 0.6.1

TimeRun is a Python library for time measurements.

TimeRun — Python package for time measurement.

TimeRun is a single-file Python package with no dependencies beyond the standard library. It records wall-clock time and CPU time for code blocks or function calls and supports optional metadata (e.g. run id, tags) per measurement.

For the full value proposition and positioning, see Why TimeRun on the docs site.

Installation

From PyPI:

pip install timerun

From source:

pip install git+https://github.com/HH-MWB/timerun.git

Note: Requires Python 3.10+.

Usage

Time Code Block

Use with Timer() as m: (or async with). The yielded Measurement has wall_time and cpu_time:

>>> from timerun import Timer
>>> with Timer() as m:
...     pass  # code block to be measured
...
>>> m.wall_time.timedelta
datetime.timedelta(microseconds=11)
>>> m.cpu_time.timedelta
datetime.timedelta(microseconds=8)

Note: On block exit the timer records CPU time first, then wall time, so wall time is slightly larger than CPU time even when there is no I/O or scheduling.

Time Function Calls

Use @Timer(). One Measurement per call is appended to the callable’s measurements deque:

>>> from timerun import Timer
>>> @Timer()
... def func():  # function to be measured
...     return
...
>>> func()
>>> func.measurements[-1].wall_time.timedelta
datetime.timedelta(microseconds=11)
>>> func.measurements[-1].cpu_time.timedelta
datetime.timedelta(microseconds=8)

Note: Argument maxlen caps how many measurements are kept (e.g. @Timer(maxlen=10)). By default the deque is unbounded.

Callbacks on Start and End

Optional on_start and on_end callbacks run once per measurement. Both receive the measurement instance (on_start before timings are set, on_end after). Typical uses are logging, forwarding to OpenTelemetry, or enqueueing to a metrics pipeline.

>>> from timerun import Timer
>>> with Timer(on_end=lambda m: print(m.wall_time.timedelta)):
...     pass  # code block to be measured
...  
0:00:00.000008

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, testing, and pull request guidelines.

License

This project is licensed under the MIT License — see the LICENSE file for details.