TimeRun

TimeRun — Structured timing for Python.

Version Status License Coverage Total Downloads

TimeRun is a single-file Python package with no dependencies beyond the standard library. It records wall-clock time and CPU time when you measure a block or function calls (one Measurement per block or per call) and supports optional metadata (e.g. run id, tags) and callbacks (on_start / on_end) per measurement.

For positioning and the full value proposition, see Overview 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

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. For example:

Print elapsed time when a block finishes:

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

Attach a trace id before each call starts:

>>> from uuid import uuid4
>>> from timerun import Timer
>>> @Timer(on_start=lambda m: m.metadata.update(trace_id=uuid4().hex))
... def func():
...     return
...  
>>> func()
>>> func.measurements[-1].metadata
{'trace_id': '8aa2c000c98843738a2f0d5d3600d052'}

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.

Project links

Data verified by PyPI on Apr 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for hhong from gravatar.com hhong

Credits

Author: HH-MWB

GitHub Statistics

Data verified by PyPI on Apr 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Tags

time measurement elapsed stopwatch timer performance

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

timerun-0.6.2.tar.gz (8.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

timerun-0.6.2-py3-none-any.whl (8.6 kB view details)

Uploaded Python 3

File details

Details for the file timerun-0.6.2.tar.gz.

File metadata

  • Download URL: timerun-0.6.2.tar.gz
  • Upload date:
  • Size: 8.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for timerun-0.6.2.tar.gz
Algorithm Hash digest
SHA256 51fb00243fbd7dabae852369a8d10abe1802a85b318ee105cb8a8854dc80909a
MD5 4e4166373c64fc3b065580956bd610a9
BLAKE2b-256 32e5aab3eaae28bcb565be97a409d7e5da4e6190b5a3adeb2fa33ba2aca88099

See more details on using hashes here.

Provenance

The following attestation bundles were made for timerun-0.6.2.tar.gz:

Publisher: release.yaml on HH-MWB/timerun

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file timerun-0.6.2-py3-none-any.whl.

File metadata

  • Download URL: timerun-0.6.2-py3-none-any.whl
  • Upload date:
  • Size: 8.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for timerun-0.6.2-py3-none-any.whl
Algorithm Hash digest
SHA256 6bc58b86648ed69f4d04a44c2ae038b2686fc34517b26e1135079eb9e40f113a
MD5 97c939303d44081780d388bb03591274
BLAKE2b-256 ca48715bca7892b23aea8c7c05aa6da273532e1fea1a1a21fffe80650272b923

See more details on using hashes here.

Provenance

The following attestation bundles were made for timerun-0.6.2-py3-none-any.whl:

Publisher: release.yaml on HH-MWB/timerun

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.6.2 This release

2 files

0.6.1

2 files

0.5.0

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page