larzbench

Ergonomic micro-benchmarking. Pure Python, zero dependencies.

timeit works, but it's awkward - stringy, one number. larzbench measures a callable across several rounds, auto-calibrates the iteration count, and gives you real statistics plus a one-call compare() that ranks several implementations.

from larzbench import benchmark, compare

r = benchmark(lambda: sum(range(1000)))
print(r)      # <lambda>: best 8.10us  mean 8.44us  118,000 ops/s

compare({
    "listcomp": lambda: [x*x for x in range(1000)],
    "map":      lambda: list(map(lambda x: x*x, range(1000))),
}).report()
# listcomp   42.10us/op  23,753 ops/s  (fastest)
# map        61.30us/op  16,313 ops/s  1.46x slower

Why

• Real stats, not one number. best / mean / median / stdev and ops-per-second, over multiple rounds with a warmup - so noise and cold caches don't fool you.
• Auto-calibration. It picks an iteration count that runs long enough to be meaningful, so you don't guess.
• compare() is the killer feature. Pass a dict of implementations; get them ranked fastest-first with relative slowdowns and a printable report.
• Testable. Pass a clock to make timings deterministic (this repo's tests do exactly that).
• Zero dependencies.

Install

pip install larzbench

Usage

from larzbench import benchmark, compare

benchmark(func, *args, rounds=5, iterations=None, warmup=True, name=None, **kwargs)
# -> Result: .best .mean .median .stdev .ops_per_sec .per_op

compare({"a": fn_a, "b": fn_b}, rounds=7).report()

Tests

python -m unittest discover -s tests -v   # 7 tests (deterministic via a fake clock)

The Larz stack

One of 30+ pure-Python, zero-dependency libraries at github.com/larz-scripter.

License

MIT (c) larz-scripter