perfclock 0.1.0

Tiny, dependency-free library for measuring execution time: stopwatch, context manager, and sync/async decorator.

perfclock

Tiny, dependency-free library for measuring execution time. Built on time.perf_counter, fully typed, works with sync and async code.

Install

pip install perfclock

Usage

Context manager

from perfclock import Timer

with Timer() as t:
    do_work()

print(t.elapsed)   # seconds as a float, e.g. 0.03241
print(t)           # <Timer stopped, elapsed=32.410 ms>

Decorator (sync or async)

from perfclock import timed

@timed
def crunch():
    ...

@timed(label="fetch users", output=logger.info)
async def fetch_users():
    ...

crunch()
# crunch took 1.204 s

The report goes to print by default; pass any callable taking a string (e.g. logger.info) via output.

Manual stopwatch with laps

t = Timer()
t.start()

step_one();  t.lap()
step_two();  t.lap()

t.stop()
print(t.laps)      # [0.51, 1.72] — seconds per step
print(t.elapsed)   # total; accumulates across start/stop until reset()

elapsed reads live while the timer is running, and start()/stop() can be called repeatedly to accumulate time. reset() clears everything.

Human-readable durations

from perfclock import format_duration

format_duration(0.000004)  # '4.000 µs'
format_duration(2.5)       # '2.500 s'
format_duration(125)       # '2 min 5.0 s'

Development

pip install -e ".[dev]"
pytest

License

MIT