[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fhunterdsp%2Fbenchmarkme%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)

# benchmarkme

Ergonomic Python interface to the built-in [`timeit`](
    https://docs.python.org/3/library/timeit.html) utility for quick-look
profiling.

## Out-Of-The-Box Features

- Python API with enhanced reporting
- Yields configuration, best & worst times and processing rates
- Default autoranging
- Automatic looping & repeat
- Customizable environment

## Usage

Minimal example

```{console=python}
>>> from time import sleep
>>> from benchmarkme import BenchMark
>>> b = BenchMark(f=sleep, fargs=[0.2,])
>>> b() # call the instance directly to run the main utility
Benchmark Results
-----------------
* Ran 1 trials 5 times.
* Time of one independent trial: 200 msec
* Best time of subsequent trials: 200 msec
* Worst time of subsequent trials: 200 msec
* Best speed: 5 items / sec
* Worst speed: 4.99 items / sec

```

Provide the items processed to get rate in the desired units (from
`benchmarkme/examples/basic.py`)

```{script}
import math
from benchmarkme import BenchMark

def fmath(x: list) -> None:
    """Calculate somethig complex-looking to time."""        
    return [math.log(math.acos(item / 1e5)) ** 2 / 1733 for item in x]

items = 100000
bmrk_math = BenchMark(
    f=fmath, 
    fargs=[[*range(items)],], 
    item_units='numbers', 
    items_processed=items
)

if __name__ == "__main__":
    bmrk_math()
```

You'll get something like the following, i.e. the function computes around 10
million numbers per second on this machine.

```{console=bash}
Benchmark Results
-----------------
* Ran 50 trials 5 times.
* Time of one independent trial: 8.92 msec
* Best time of subsequent trials: 8.89 msec
* Worst time of subsequent trials: 12.1 msec
* Best speed: 11.2 Mnumbers / sec
* Worst speed: 8.28 Mnumbers / sec
```
