Metadata-Version: 2.4
Name: larzbench
Version: 0.1.0
Summary: Ergonomic micro-benchmarking in pure Python: time a callable with real stats and compare implementations. Zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzbench
Project-URL: Repository, https://github.com/larz-scripter/larzbench
Project-URL: Issues, https://github.com/larz-scripter/larzbench/issues
Keywords: benchmark,benchmarking,timeit,performance,profiling,timing,compare,micro-benchmark,zero-dependency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

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

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

```bash
pip install larzbench
```

## Usage

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

```bash
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](https://github.com/larz-scripter).

## License

MIT (c) larz-scripter
