Metadata-Version: 2.4
Name: benchdiff
Version: 0.1.0
Summary: CLI benchmarking tool with rich terminal output and markdown export.
Keywords: benchmark,cli,performance
Author: Amin Alaee
Author-email: Amin Alaee <mohammadamin.alaee@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Requires-Dist: py-cpuinfo>=9.0.0
Requires-Dist: rich
Requires-Dist: typer
Requires-Dist: matplotlib ; extra == 'svg'
Requires-Python: >=3.10
Project-URL: Documentation, https://github.com/aminalaee/benchdiff
Project-URL: Issues, https://github.com/aminalaee/benchdiff/issues
Project-URL: Source, https://github.com/aminalaee/benchdiff
Provides-Extra: svg
Description-Content-Type: text/markdown

# benchdiff

A CLI benchmarking tool with rich terminal output and markdown export.

## Installation

```bash
pip install benchdiff
```

## Usage

Create a file named `bench_*.py` and define a `__benchmarks__` list:

```python
# bench_strings.py

words = ["hello", "world", "foo", "bar"]


def concat():
    result = ""
    for w in words:
        result += w


def join():
    "".join(words)


def format_string():
    "%s %s %s %s" % tuple(words)


def fstring():
    f"{words[0]} {words[1]} {words[2]} {words[3]}"


__benchmarks__ = [
    ("String concatenation", [concat, join]),
    ("String formatting", [format_string, fstring]),
]
```

Run benchmarks:

```bash
benchdiff benchmarks/
```

```
╭──────────────────────────────── benchdiff ────────────────────────────────╮
│                                                                           │
│   Benchmark                 Min         Median        Max          ×      │
│  ───────────────────────────────────────────────────────────────────────  │
│   String concatenation                                                    │
│     concat                78.333ns     80.833ns     97.750ns    1.711x    │
│     join                  44.250ns     47.250ns     53.125ns    1.000x    │
│   String formatting                                                       │
│     format_string        103.834ns    110.417ns    114.708ns    1.464x    │
│     fstring               75.000ns     75.417ns     76.083ns    1.000x    │
│                                                                           │
│   * times in nanoseconds, lower is better                                 │
│ ───────────────────────────────────────────────────────────────────────── │
│   Python      3.14.2                                                      │
│   Platform    macOS-26.3.1                                                │
│   CPU         Apple M3 Pro                                                │
│   Rounds      5 × 1,000 calls                                             │
│   Date        2026-05-08 10:05:59                                         │
╰───────────────────────────────────────────────────────────────────────────╯
```

## CLI options

```
benchdiff [PATH] [OPTIONS]

Arguments:
  PATH    Path to search for bench_*.py files [default: .]

Options:
  --repeat    Number of measurement loops [default: 5]
  --times     Number of calls per measurement [default: 1000]
  --markdown  Output as GFM markdown table
  --help      Show this message and exit.
```

## Markdown output

```bash
benchdiff benchmarks/ --markdown
```

| Benchmark                |       Min |    Median |       Max |      × |
| :----------------------- | --------: | --------: | --------: | -----: |
| **String concatenation** |           |           |           |        |
| concat                   |  81.000ns |  89.583ns |  95.541ns | 1.795x |
| join                     |  43.041ns |  49.917ns |  50.709ns | 1.000x |
| **String formatting**    |           |           |           |        |
| format_string            | 106.875ns | 110.125ns | 113.292ns | 1.572x |
| fstring                  |  68.709ns |  70.041ns |  74.250ns | 1.000x |

*times in nanoseconds, lower is better*

Python 3.14.2 · macOS-26.3.1 · Apple M3 Pro · 5 × 1,000 rounds · 2026-05-08 10:05:59
