CLI reference¶
Auto-generated from mew … --help. For an introduction and examples,
see Command-line interface.
mew¶
$ mew --help
usage: mew [-h] [--version] <command> [<args>]
Microbenchmarking for Python via Google Benchmark.
options:
-h, --help show this help message and exit
--version show program's version number and exit
commands:
list (ls) List discovered benchmarks.
run Discover and run benchmarks.
compare Compare benchmark result files.
completions Print a shell-completion script for eval/install.
mew ls¶
$ mew list --help
usage: mew list [-h] [-k <pattern>] [-F] [-t <tag>] [--show-tags]
[--show-cases] [-n]
[<paths> ...]
positional arguments:
<paths> Files, directories, or `<path>::<filter>` selectors to
discover benchmarks from. Defaults to `[tool.mew]
benchpaths`.
options:
-h, --help show this help message and exit
-k <pattern>, --pattern <pattern>
List benchmarks whose name matches this regex
(re.search, so a plain word works as a substring). A
family case also matches by its `name[label]` form;
pass --literal to match `[...]` without escaping.
-F, --literal Match -k as a literal string, not a regex (e.g. paste
`bench_sort[n=1000]`).
-t <tag>, --tag <tag>
Filter benchmarks by tag. Repeatable, OR semantics.
--show-tags Show tags alongside each name.
--show-cases Expand each parametrized family into one row per case
(`name[label]`).
-n, --names-only Print the bare name without the `file.py::` prefix.
Path-free, so `mew list -n | mew run --stdin` round-
trips from any directory.
mew run¶
$ mew run --help
usage: mew run [-h] [-k <pattern>] [-F] [--stdin] [-t <tag>] [-o <output>]
[--format (rich|json|jsonl)] [--min-time <min-time>]
[--min-warmup-time <min-warmup-time>] [--repetitions <N>]
[--random-interleaving] [--session-tag <session-tag>]
[--append] [--strict] [--profile-memory]
[--flamegraph <flamegraph>] [--sample]
[--sample-interval <sample-interval>]
[--sample-html <sample-html>]
[<paths> ...]
positional arguments:
<paths> Files, directories, or `<path>::<filter>` selectors to
discover benchmarks from. Defaults to `[tool.mew]
benchpaths`.
options:
-h, --help show this help message and exit
-k <pattern>, --pattern <pattern>
Only run benchmarks whose name matches this regex
(re.search). A family case also matches by its
`name[label]` form; pass --literal to match `[...]`.
-F, --literal Match -k as a literal string.
--stdin Read newline-delimited selectors from stdin (`mew list
| mew run --stdin`). Lines match literally; a path-
free name is resolved against run's own discovery.
-t <tag>, --tag <tag>
Filter benchmarks by tag. Repeatable, OR semantics.
-o <output>, --output <output>
Output sink, repeatable: `-`/`stdout` for the
terminal, `<path>.json` / `<path>.jsonl` /
`<path>.jsonl.gz` for a file. Default: `-`.
--format (rich|json|jsonl)
Format of stdout output: `rich` (table), `json`, or
`jsonl`. Use json/jsonl to pipe machine-readable rows
(`mew run --format jsonl | jq`).
--min-time <min-time>
Min time per benchmark, seconds (e.g. `0.5`) or iters
(`100x`).
--min-warmup-time <min-warmup-time>
Warmup time per benchmark before measurement starts
(seconds, or a duration like `200ms`).
--repetitions <N> Repeat each benchmark N times.
--random-interleaving
Randomly interleave repetitions across benchmarks to
decorrelate thermal/load drift (effective with
--repetitions > 1).
--session-tag <session-tag>
Label this run's output as a session (e.g. `before`),
addressable later as `mew compare
results.jsonl@before`. Runs sharing a tag are compared
as one session.
--append Append as a new session to existing `.jsonl[.gz]`
sinks.
--strict Error instead of skipping when threaded benchmarks
(threads / thread_range) are selected on a GIL
interpreter, where they can't run.
--profile-memory Profile memory allocations with `memray`, via Google
Benchmark's memory manager (an extra untimed pass per
repetition).
--flamegraph <flamegraph>
Write an HTML allocation flame graph to this path.
Implies --profile-memory.
--sample Sample CPU in-process with `pyinstrument` (Python
frames).
--sample-interval <sample-interval>
pyinstrument sampling interval in seconds (default
1e-4).
--sample-html <sample-html>
Write a pyinstrument HTML report to this path. Implies
--sample.
mew compare¶
$ mew compare --help
usage: mew compare [-h] [-m <metric>] [--key <key>] [-k <pattern>] [-F]
[--stddev] [--by <by>] [--baseline <baseline>]
[--statistic <statistic>] [--regression-threshold <N%>]
[--exit-non-zero-on-regression]
[--regressions-config <regressions-config>]
<files> [<files> ...]
positional arguments:
<files> Result files; the last is the baseline.
options:
-h, --help show this help message and exit
-m <metric>, --metric <metric>
Metric: real_time, cpu_time, iterations, or (for
--profile-memory results) memory.peak_bytes /
memory.allocations_per_iteration.
--key <key> How benchmarks are matched: `name` (full) or `func`
(strip the `file.py::` prefix). Defaults to `func`
with --by, `name` otherwise.
-k <pattern>, --pattern <pattern>
Regex filter (re.search).
-F, --literal Match -k as a literal string.
--stddev Show stddev columns if present.
--by <by> Pivot one file on a field instead of comparing files,
e.g. `context.engine` (set per suite with
mew.set_context).
--baseline <baseline>
With --by, the baseline column (default: first
written).
--statistic <statistic>
Reducer over per-repetition values, for display and
the regression gate: min, max, mean, median, gmean, or
a pNN percentile like p95. Default: median. Overrides
[tool.mew] statistic.
--regression-threshold <N%>
Regression magnitude that triggers a REGRESSED
verdict, e.g. `5%`. Always prints the regression
panel; pair with --exit-non-zero-on-regression to also
fail the command. Defaults to [tool.mew.regressions]
default_threshold.
--exit-non-zero-on-regression
Exit 2 if any benchmark regressed past the threshold
(the [tool.mew.regressions] default when no
--regression-threshold is given). Without this, the
regression panel is informational only and the exit
code is unaffected.
--regressions-config <regressions-config>
TOML file with [tool.mew.regressions] (default:
./pyproject.toml).
mew completions¶
$ mew completions --help
usage: mew completions [-h] <shell>
positional arguments:
<shell> Target shell: bash, zsh, fish.
options:
-h, --help show this help message and exit