Decorators

mew.benchmark(fn=None, /, *, name=None, tags=None, **options)[source]
Overloads:

  • fn (BenchmarkFn) → BenchmarkFn

  • name (str | None), tags (Iterable[str] | str | None), options (Unpack[BenchmarkOptions]) → Callable[[BenchmarkFn], BenchmarkFn]

Parameters:
Return type:

BenchmarkFn | Callable[[BenchmarkFn], BenchmarkFn]

Register a function as a single benchmark.

Use parametrize() or product() for benchmark families.

Parameters:

  • fn (BenchmarkFn | None) – The benchmark function. When passed positionally (bare @benchmark), registration happens immediately. Omit to apply options first (@benchmark(min_time=...)).

  • name (str | None) – Override the auto-derived path/to/file.py::qualname registration name.

  • tags (Iterable[str] | str | None) – Labels used by mew run --tag <name> for filtering. A single string is treated as one tag.

  • **options (Unpack[BenchmarkOptions]) – Google Benchmark options. See BenchmarkOptions for the accepted keys.

Returns:

BenchmarkFn or Callable[[BenchmarkFn], BenchmarkFn] – The original function (bare form), or a decorator (called form).

Raises:

  • TypeError – If options contains an unknown key.

  • RuntimeError – If the same function is already registered via another decorator.

Return type:

BenchmarkFn | Callable[[BenchmarkFn], BenchmarkFn]

Examples

>>> @mew.benchmark
... def bench_sort(state):
...     for _ in state:
...         sorted([3, 1, 2])
mew.parametrize(parameters, *, name=None, ids=None, tags=None, **options)[source]

Register a parametrized benchmark family.

One benchmark is registered per item in parameters. Each variant binds its kwargs into the wrapped function and appends a [label] suffix to the registration name.

Parameters:

  • parameters (Iterable[dict[str, Any]]) – One dict of kwargs per variant. Snapshotted eagerly, so generators are fine.

  • name (str | None) – Override the auto-derived base name.

  • ids (Sequence[str] | None) – Explicit labels (one per variant). Defaults to labels derived from the kwargs (e.g. n=10-algo=merge).

  • tags (Iterable[str] | str | None) – Labels applied to every variant.

  • **options (Unpack[BenchmarkOptions]) – Google Benchmark options applied to every variant. Same keys as benchmark().

Return type:

Callable[[BenchmarkFn], BenchmarkFn]

Returns:

Callable[[BenchmarkFn], BenchmarkFn] – Decorator that registers the family and returns the original function unchanged.

Raises:

  • ValueError – If ids length doesn’t match parameters.

  • TypeError – If options contains an unknown key.

  • RuntimeError – If the same function is already registered via another decorator.

Examples

>>> @mew.parametrize([
...     {"n": 10, "algo": "merge"},
...     {"n": 100, "algo": "quick"},
... ], min_time=0.05, tags=("sort",))
... def bench_sort(state, n, algo):
...     data = list(range(n, 0, -1))
...     for _ in state:
...         sorted(data)
mew.product(*, name=None, ids=None, tags=None, min_time=None, min_warmup_time=None, iterations=None, repetitions=None, unit=None, use_real_time=False, use_manual_time=False, measure_process_cpu_time=False, report_aggregates_only=False, **iterables)[source]

Register a benchmark family from the cartesian product of iterables.

One benchmark is registered per tuple in the cartesian product over **iterables.

Parameters:

  • name (str | None) – Override the auto-derived base name.

  • ids (Sequence[str] | None) – Explicit labels (one per cartesian-product tuple).

  • tags (Iterable[str] | str | None) – Labels applied to every variant.

  • min_time (float | None) – Per-variant Google Benchmark timing options.

  • min_warmup_time (float | None) – Per-variant Google Benchmark timing options.

  • iterations (int | None) – Per-variant Google Benchmark iteration controls.

  • repetitions (int | None) – Per-variant Google Benchmark iteration controls.

  • unit (Union[Literal['ns', 'us', 'ms', 's'], TimeUnit, None]) – Override Google Benchmark’s reported time unit.

  • use_real_time (bool) – Flag-style Google Benchmark options.

  • use_manual_time (bool) – Flag-style Google Benchmark options.

  • measure_process_cpu_time (bool) – Flag-style Google Benchmark options.

  • report_aggregates_only (bool) – Suppress per-repetition rows when repetitions > 1.

  • **iterables (Iterable[Any]) – Parameter name → iterable of values.

Return type:

Callable[[BenchmarkFn], BenchmarkFn]

Returns:

Callable[[BenchmarkFn], BenchmarkFn] – Decorator that registers the family and returns the original function unchanged.

Raises:

  • TypeError – If no iterables are supplied.

  • RuntimeError – If the same function is already registered via another decorator.

Examples

>>> @mew.product(n=[10, 100], algo=["merge", "quick"], tags=("sort",))
... def bench_sort(state, n, algo):
...     ...

Options

class mew.api.BenchmarkOptions[source]

Bases: TypedDict

Per-benchmark Google Benchmark options accepted by the decorators.

All keys are optional. Omit a key to fall back to Google Benchmark’s default.

min_time: float
min_warmup_time: float
iterations: int
repetitions: int
unit: Literal['ns', 'us', 'ms', 's'] | TimeUnit
use_real_time: bool
use_manual_time: bool
measure_process_cpu_time: bool
report_aggregates_only: bool