pytest-benchmem 0.2.0__tar.gz → 0.3.0__tar.gz

pytest_benchmem-0.3.0/.github/workflows/ci.yaml

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --group dev
+      - run: uv run ruff check --output-format=github
+      - run: uv run ruff format --diff
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --group dev
+      - run: uv run mypy src/pytest_benchmem tests
+
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04]
+        python-version: ["3.11", "3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run pytest -q
+
+  smoke-install:
+    name: Smoke (built wheel)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Build the wheel
+        run: uv build --wheel
+      - name: Install the built wheel into a clean env and use it
+        run: |
+          set -euxo pipefail
+          WHEEL="$(ls dist/*.whl)"
+          uv venv /tmp/smoke
+          # Only the built artifact (+ the plot extra for the CLI). Its declared
+          # deps must suffice on their own — no dev group to mask a missing one.
+          uv pip install --python /tmp/smoke/bin/python "pytest-benchmem[plot] @ file://$PWD/$WHEEL"
+          # 1) the pytest11 plugin records memory, from the installed wheel
+          printf 'def test_alloc(benchmark_memory):\n    benchmark_memory(lambda: [0] * 500_000)\n' > /tmp/smoke_suite.py
+          /tmp/smoke/bin/python -m pytest /tmp/smoke_suite.py \
+            --benchmark-only --benchmark-json=/tmp/bench.json -p no:cacheprovider
+          # 2) the console script is on PATH and reads what the plugin produced
+          /tmp/smoke/bin/benchmem --help
+          cp /tmp/bench.json /tmp/bench2.json
+          /tmp/smoke/bin/benchmem compare /tmp/bench.json /tmp/bench2.json --columns peak
+          # 3) py.typed is packaged, so downstream type-checkers see our types
+          /tmp/smoke/bin/python -c "from importlib.resources import files; assert files('pytest_benchmem').joinpath('py.typed').is_file()"
+
+  ci-passed:
+    name: CI passed
+    if: always()
+    needs: [lint, typecheck, test, smoke-install]
+    runs-on: ubuntu-24.04
+    steps:
+      - if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

{pytest_benchmem-0.2.0 → pytest_benchmem-0.3.0}/.github/workflows/docs.yaml

@@ -22,7 +22,7 @@ jobs:
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
-      # Build the notebook from its jupytext source, then build+execute the site.
+      # Build the notebooks from their jupytext sources, then build+execute the site.
       - run: uv sync --group docs
-      - run: uv run jupytext --to ipynb docs/walkthrough.md
+      - run: uv run jupytext --to ipynb docs/compare-plot.md
       - run: uv run mkdocs gh-deploy --force

pytest_benchmem-0.3.0/.github/workflows/nightly.yaml

@@ -0,0 +1,40 @@
+name: Deps range (scheduled)
+
+# Verifies our declared dependency range still works, at both ends — neither is a
+# per-PR concern (one is time-triggered, the other rarely regresses), so they run
+# weekly instead of on every push:
+#   - floor:  the lowest versions our pyproject allows (pytest>=7, pytest-benchmark>=4,
+#             memray>=1.11) — proves the declared support range is real.
+#   - latest: the newest *allowed* versions, ignoring the lock — catches an upstream
+#             release that breaks our coupling to their internals (memray._memray
+#             .compute_statistics, pytest-benchmark's pedantic signature) before a
+#             user does. (Upper bounds: memray<2, pytest-benchmark<6.)
+
+on:
+  schedule:
+    - cron: "0 6 * * 1" # Mondays 06:00 UTC
+  workflow_dispatch:
+
+jobs:
+  deps:
+    name: Test (${{ matrix.label }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - label: floor deps
+            python: "3.11"
+            resolution: "--resolution lowest-direct"
+          - label: latest allowed deps
+            python: "3.13"
+            resolution: "--upgrade"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --group dev ${{ matrix.resolution }}
+      - run: uv run pytest -q

pytest_benchmem-0.3.0/.readthedocs.yaml

@@ -0,0 +1,11 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  commands:
+    - pip install uv
+    - uv sync --group docs
+    - uv run jupytext --to ipynb docs/getting-started.md docs/metrics.md docs/dims.md docs/compare-plot.md docs/reference.md
+    - uv run mkdocs build --strict --site-dir "$READTHEDOCS_OUTPUT/html"

pytest_benchmem-0.3.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.0"
+}

pytest_benchmem-0.3.0/CHANGELOG.md

@@ -0,0 +1,151 @@
+# Changelog
+
+## [0.3.0](https://github.com/fluxopt/pytest-benchmem/compare/v0.2.1...v0.3.0) (2026-06-16)
+
+This release reshapes how a memory measurement is taken, stored, and reported. Each
+`benchmark_memory` run now **samples adaptively** and keeps its **full per-repeat series**
+instead of a single number — so you can ask how noisy a metric is (`--stat
+min|mean|max|median|stddev`) — and the terminal prints **one combined timing + memory
+table**. `benchmem compare` is **rebuilt on pytest-benchmark's table model** (rows per
+benchmark × run, a metric × stat column grid, relative `(×)` multipliers, `--group-by` /
+`--columns`). Plus a `benchmem sweep` CLI for cross-version runs, `--where` / `--free-axes`
+plot controls, action-scoped memory ceilings (`@pytest.mark.benchmem(max_peak=...)`), and
+`--benchmark-memory-profile` to keep a memray `.bin` for regressions.
+
+Consolidating the metric surface around the per-repeat series retired a few redundant
+knobs — see the migration notes below.
+
+### ⚠ BREAKING CHANGES
+
+Pre-1.0 changes vs 0.2.1, each quick to migrate:
+
+* **Saved memory JSON from 0.2.x no longer loads.** The blob under
+  `extra_info["benchmem"]` is now three flat per-repeat arrays (`peak_bytes` /
+  `allocations` / `total_bytes`), with the headline derived on read; the old denormalized
+  shape is not parsed. **Migrate:** re-run the suite with `--benchmark-memory` to
+  regenerate the runs. Timing-only pytest-benchmark files are unaffected. ([#75](https://github.com/fluxopt/pytest-benchmem/issues/75))
+* **The `peak_max` metric is removed** — it was `peak` reduced by max (a stat of a stat), so
+  it couldn't itself take a `--stat`. **Migrate:** `--metric peak --stat max`. ([#75](https://github.com/fluxopt/pytest-benchmem/issues/75))
+* **The `memory` alias for `peak` is removed** — it read like a category, not a synonym.
+  **Migrate:** `--metric peak`. ([#75](https://github.com/fluxopt/pytest-benchmem/issues/75))
+* **The `gross` metric and the per-blob `mode` tag are removed** — both were leftovers of the
+  reverted RSS engine (`gross` had no producer and always errored; `mode` was a constant).
+  Reading a legacy blob ignores a stray `mode` key, so **no migration is needed**. ([#67](https://github.com/fluxopt/pytest-benchmem/issues/67))
+
+### Features
+
+**Memory measurement**
+* **Adaptive sampling** — passes run until the peak floor settles instead of a fixed count; `--benchmark-memory-repeats` still forces a fixed count for reproducible gating. ([#97](https://github.com/fluxopt/pytest-benchmem/issues/97), [#79](https://github.com/fluxopt/pytest-benchmem/issues/79))
+* **Per-repeat series** with `--stat` distributions, min/mean/max spread columns, and `--benchmark-memory-columns` / `-stats` selection. ([#72](https://github.com/fluxopt/pytest-benchmem/issues/72), [#76](https://github.com/fluxopt/pytest-benchmem/issues/76))
+* **Action-scoped absolute ceilings** via `@pytest.mark.benchmem(max_peak=…, max_allocated=…, max_allocations=…)`. ([#86](https://github.com/fluxopt/pytest-benchmem/issues/86))
+* **`--benchmark-memory-profile DIR`** keeps the memray `.bin` for regressions (or every measured benchmark), to render with `memray flamegraph`. ([#100](https://github.com/fluxopt/pytest-benchmem/issues/100), closes [#24](https://github.com/fluxopt/pytest-benchmem/issues/24))
+* Actionable error when a memray `Tracker` is already active (e.g. pytest-memray on the same test). ([#89](https://github.com/fluxopt/pytest-benchmem/issues/89))
+
+**Tables & compare**
+* **One combined timing + memory table** by default. ([#65](https://github.com/fluxopt/pytest-benchmem/issues/65), [#68](https://github.com/fluxopt/pytest-benchmem/issues/68))
+* **`benchmem compare` rebuilt on pytest-benchmark's table model** — rows per (benchmark × run), a metric × stat column grid with `--columns` / `--group-by` / `--metric both`, relative `(×)` multipliers, plus `--csv` / `--sort`. ([#98](https://github.com/fluxopt/pytest-benchmem/issues/98), [#101](https://github.com/fluxopt/pytest-benchmem/issues/101), [#74](https://github.com/fluxopt/pytest-benchmem/issues/74))
+
+**Plotting**
+* **`--where KEY=VALUE`** row filter, **`--free-axes x|y|both`** for faceted views, and min…max spread whiskers on scaling plots. ([#93](https://github.com/fluxopt/pytest-benchmem/issues/93), [#95](https://github.com/fluxopt/pytest-benchmem/issues/95), [#99](https://github.com/fluxopt/pytest-benchmem/issues/99))
+
+**CLI**
+* **`benchmem sweep`** — cross-version sweeps without a harness. ([#87](https://github.com/fluxopt/pytest-benchmem/issues/87))
+* Caller-labelled snapshots, decoupling series names from filenames. ([#57](https://github.com/fluxopt/pytest-benchmem/issues/57))
+
+### Bug Fixes
+
+* `compare` no longer crashes when two runs share a file stem. ([#64](https://github.com/fluxopt/pytest-benchmem/issues/64))
+
+## [0.2.1](https://github.com/fluxopt/pytest-benchmem/compare/v0.2.0...v0.2.1) (2026-06-13)
+
+
+### Features
+
+* add `rss` memory mode — kernel resident high-water via a forked child ([#51](https://github.com/fluxopt/pytest-benchmem/issues/51)) ([c4ccd12](https://github.com/fluxopt/pytest-benchmem/commit/c4ccd1267b9b795d88f377e005b6b6f060ccc40a))
+* add peak_max and gross metrics; error on metric/mode mismatch ([#55](https://github.com/fluxopt/pytest-benchmem/issues/55)) ([df45d1f](https://github.com/fluxopt/pytest-benchmem/commit/df45d1fc44ece79db297ae5b0dbc1537f5cb3e8f))
+* built-in node.* dims (module/func/class/group), selectable in plots ([#54](https://github.com/fluxopt/pytest-benchmem/issues/54)) ([937ca0f](https://github.com/fluxopt/pytest-benchmem/commit/937ca0f470d467046d81d1db549a51cfa44dfdd0))
+* tag memory blobs with a `mode` and refuse to mix modes ([#40](https://github.com/fluxopt/pytest-benchmem/issues/40)) ([4251e16](https://github.com/fluxopt/pytest-benchmem/commit/4251e16a79d4ec66d5b39a41c924633c256287ee))
+
+
+### Bug Fixes
+
+* accept str and single-path snapshots in plot_* and load_long_df ([#52](https://github.com/fluxopt/pytest-benchmem/issues/52)) ([fdbc343](https://github.com/fluxopt/pytest-benchmem/commit/fdbc3432c8709ba0c3ed2f4c85df6ff4f45a4a30))
+* keep only scalar dims, dropping unserializable and structured values ([#45](https://github.com/fluxopt/pytest-benchmem/issues/45)) ([71cb05d](https://github.com/fluxopt/pytest-benchmem/commit/71cb05d464d66bb55699e582103261f335a3e1a3))
+* metric ergonomics — correct allocated label, accept memory alias ([#53](https://github.com/fluxopt/pytest-benchmem/issues/53)) ([a61c9be](https://github.com/fluxopt/pytest-benchmem/commit/a61c9befb6aae6feca5f504f9fb9e16b35ed5f3f))
+
+
+### Reverts
+
+* remove the `rss` memory mode ([#51](https://github.com/fluxopt/pytest-benchmem/issues/51)) ([#56](https://github.com/fluxopt/pytest-benchmem/issues/56)) ([99d908d](https://github.com/fluxopt/pytest-benchmem/commit/99d908d582094d982f421cc381639f53b6585a56))
+
+## [0.2.0](https://github.com/fluxopt/pytest-benchmem/compare/v0.1.0...v0.2.0) (2026-06-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* mirror memray's metrics — add total memory allocated ([#39](https://github.com/fluxopt/pytest-benchmem/issues/39))
+* memory regression gate, @pytest.mark.benchmem, bytes blob migration ([#32](https://github.com/fluxopt/pytest-benchmem/issues/32))
+
+### Features
+
+* empirical scaling fit — report O(n^x) over a size sweep ([#36](https://github.com/fluxopt/pytest-benchmem/issues/36)) ([4bc6e46](https://github.com/fluxopt/pytest-benchmem/commit/4bc6e4683142c46c9c60765dbf1f8e39adb3388f))
+* memory regression gate, [@pytest](https://github.com/pytest).mark.benchmem, bytes blob migration ([#32](https://github.com/fluxopt/pytest-benchmem/issues/32)) ([654c582](https://github.com/fluxopt/pytest-benchmem/commit/654c582a15a8f8ef8e79a7c1d41767660d5f962a))
+* mirror memray's metrics — add total memory allocated ([#39](https://github.com/fluxopt/pytest-benchmem/issues/39)) ([0b6fad6](https://github.com/fluxopt/pytest-benchmem/commit/0b6fad6f90ef124b1c80ca368c1d4db6fe5b34af))
+
+
+### Bug Fixes
+
+* correct release-please pre-major key so feat! bumps 0.2.0 not 1.0.0 ([#41](https://github.com/fluxopt/pytest-benchmem/issues/41)) ([fac21e0](https://github.com/fluxopt/pytest-benchmem/commit/fac21e08bfaf5816f067fd78da57aa623c1b563d))
+
+## [0.1.0](https://github.com/fluxopt/pytest-benchmem/compare/v0.1.0...v0.1.0) (2026-06-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* rename package peakbench → pytest-benchmem ([#10](https://github.com/fluxopt/pytest-benchmem/issues/10))
+* pivot to the memory companion to pytest-benchmark ([#7](https://github.com/fluxopt/pytest-benchmem/issues/7))
+
+### Features
+
+* --benchmark-memory flag to augment existing benchmark() calls ([#16](https://github.com/fluxopt/pytest-benchmem/issues/16)) ([aff17c7](https://github.com/fluxopt/pytest-benchmem/commit/aff17c76ad742cedc963e7914bd575846ddc6035))
+* pivot to the memory companion to pytest-benchmark ([#7](https://github.com/fluxopt/pytest-benchmem/issues/7)) ([52f2b6b](https://github.com/fluxopt/pytest-benchmem/commit/52f2b6b56af1ee61f84fcd0ab9dc0947004fd31d))
+* resolve [#2](https://github.com/fluxopt/pytest-benchmem/issues/2) — drop select=, bless filter-before-convert ([89fbfcd](https://github.com/fluxopt/pytest-benchmem/commit/89fbfcdde439eb6f1535df8e65d2295b2ea69add))
+
+
+### Miscellaneous Chores
+
+* release pytest-benchmem as 0.1.0 ([#13](https://github.com/fluxopt/pytest-benchmem/issues/13)) ([8e51760](https://github.com/fluxopt/pytest-benchmem/commit/8e51760d7bdfe4e44ea77856e8a0c4e158de0099))
+
+
+### Code Refactoring
+
+* rename package peakbench → pytest-benchmem ([#10](https://github.com/fluxopt/pytest-benchmem/issues/10)) ([1e48259](https://github.com/fluxopt/pytest-benchmem/commit/1e482590bef2767df1619bcae15a6d132f4cc610))
+
+## [0.1.0](https://github.com/fluxopt/pytest-benchmem/compare/v0.0.1...v0.1.0) (2026-06-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* rename package peakbench → pytest-benchmem ([#10](https://github.com/fluxopt/pytest-benchmem/issues/10))
+* pivot to the memory companion to pytest-benchmark ([#7](https://github.com/fluxopt/pytest-benchmem/issues/7))
+
+### Features
+
+* pivot to the memory companion to pytest-benchmark ([#7](https://github.com/fluxopt/pytest-benchmem/issues/7)) ([52f2b6b](https://github.com/fluxopt/pytest-benchmem/commit/52f2b6b56af1ee61f84fcd0ab9dc0947004fd31d))
+
+
+### Miscellaneous Chores
+
+* release pytest-benchmem as 0.1.0 ([#13](https://github.com/fluxopt/pytest-benchmem/issues/13)) ([8e51760](https://github.com/fluxopt/pytest-benchmem/commit/8e51760d7bdfe4e44ea77856e8a0c4e158de0099))
+
+
+### Code Refactoring
+
+* rename package peakbench → pytest-benchmem ([#10](https://github.com/fluxopt/pytest-benchmem/issues/10)) ([1e48259](https://github.com/fluxopt/pytest-benchmem/commit/1e482590bef2767df1619bcae15a6d132f4cc610))
+
+## 0.0.1 (2026-06-13)
+
+
+### Features
+
+* resolve [#2](https://github.com/fluxopt/pytest-benchmem/issues/2) — drop select=, bless filter-before-convert ([89fbfcd](https://github.com/fluxopt/pytest-benchmem/commit/89fbfcdde439eb6f1535df8e65d2295b2ea69add))

pytest_benchmem-0.3.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: pytest-benchmem
+Version: 0.3.0
+Summary: The memory companion to pytest-benchmark: a memray peak-memory pass on the same test, plus dims-aware plots and cross-version sweeps.
+Project-URL: Homepage, https://github.com/fluxopt/pytest-benchmem
+Project-URL: Documentation, https://fluxopt.github.io/pytest-benchmem/
+Project-URL: Repository, https://github.com/fluxopt/pytest-benchmem
+Project-URL: Issues, https://github.com/fluxopt/pytest-benchmem/issues
+Author: Felix Bumann
+License-Expression: MIT
+License-File: LICENSE
+Keywords: benchmark,memory,memray,performance,pytest,pytest-benchmark
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: memray<2,>=1.11; platform_system == 'Linux' or platform_system == 'Darwin'
+Requires-Dist: pytest-benchmark<6,>=4
+Requires-Dist: pytest>=7
+Requires-Dist: rich>=13
+Provides-Extra: plot
+Requires-Dist: pandas; extra == 'plot'
+Requires-Dist: plotly>=5; extra == 'plot'
+Requires-Dist: typer>=0.12; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# pytest-benchmem
+
+[![CI](https://github.com/fluxopt/pytest-benchmem/actions/workflows/ci.yaml/badge.svg)](https://github.com/fluxopt/pytest-benchmem/actions/workflows/ci.yaml)
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**The memory companion to [pytest-benchmark].** It times your code; pytest-benchmem
+adds a memray **peak-memory** pass to the *same test, in the same run* — one node
+id, one JSON file, both metrics. Plus dims-aware plots and cross-version sweeps.
+
+📖 **[Full documentation](https://fluxopt.github.io/pytest-benchmem/)** — getting
+started, metrics, dims, compare & plot, sweeps, and the reference.
+
+## Quickstart
+
+A **drop-in** for an existing pytest-benchmark suite: add `--benchmark-memory` and every
+`benchmark(...)` call also records peak memory — no test changes.
+
+```python
+import pytest
+
+
+@pytest.mark.parametrize("n", [10_000, 100_000, 1_000_000])
+def test_sort(benchmark, n):          # an ordinary pytest-benchmark test, unchanged
+    benchmark(sorted, list(range(n, 0, -1)))
+```
+
+```bash
+pytest --benchmark-only --benchmark-memory   # both metrics, in pytest-benchmark's own table
+```
+
+```
+ Name (time in us)              Min                  Median         │  peak (MiB)
+ ──────────────────────────────────────────────────────────────────────────────
+  test_sort[10000]           32.5830 (1.0)         41.2080 (1.0)    │       0.08
+  test_sort[100000]         321.2080 (9.86)       419.9160 (10.19)  │       0.76
+  test_sort[1000000]      3,669.2920 (112.61)   4,331.5421 (105.11) │       7.63
+
+ memory (right of │): a separate, untimed pass, not the timed rounds  •  also available via --benchmark-memory-columns: allocated, allocs
+```
+
+Left of the divider is pytest-benchmark's timing, untouched; right is pytest-benchmem's
+memory. The two never overlap — memray measures peak on a *separate, untimed* call, so the
+allocator hooks cost the timing nothing. It's opt-in at the run level: without the flag, your
+suite runs exactly as before. Peak is the headline, so it shows by default; `allocated` and
+`allocs` are one flag away (`--benchmark-memory-columns`).
+
+Add `--benchmark-json=run.json` and both persist under one node id: timing in `stats`,
+memory in `extra_info.benchmem`. Parametrize `params` become the dims the plots scale by —
+see [Grouping by dims](https://fluxopt.github.io/pytest-benchmem/dims/).
+
+## Memory on specific tests — the `benchmark_memory` fixture
+
+`--benchmark-memory` measures the whole suite. To opt in *per test* instead — no run-level
+flag — swap `benchmark` for the `benchmark_memory` fixture on just those tests; it's always
+measured, and adds a `pedantic` form for explicit control:
+
+```python
+def test_sort(benchmark_memory):
+    benchmark_memory(sorted, list(range(1_000_000, 0, -1)))
+```
+
+Memory passes are **adaptive** by default. Peak is allocator demand, not wall-clock jitter, so
+each pass is exact; passes exist only to find the floor (this is sequential sampling, not
+calibration). pytest-benchmem runs until the **minimum** peak settles (≥2 passes, so
+the first pass's one-time warmup — lazy imports, arena growth — is discarded; capped at 10),
+then reports that min. Deterministic code settles in a few passes; noisy code runs more, where
+it helps. Force a fixed, reproducible count with `--benchmark-memory-repeats=N` (suite-wide) or
+`@pytest.mark.benchmem(repeats=N)` (per test); every pass is kept and the headline is the min.
+
+> **Your benchmark must be safe to re-run.** memray measures on an extra call, after
+> pytest-benchmark's timing rounds — so a side-effectful action (mutates a fixture, fills a
+> cache, drains an iterator, writes a file) records its already-warmed state, not a cold
+> run, silently. Benchmark a pure call, or use the fixture's `pedantic` form with a `setup`
+> that rebuilds fresh state each round.
+
+## Reading it back
+
+Timing rides pytest-benchmark's own tooling (`pytest-benchmark compare`,
+`--benchmark-histogram`) — pytest-benchmem doesn't reimplement it. For **memory**,
+and dims-aware views over either metric:
+
+```bash
+benchmem compare base.json head.json                 # per-id table: time+peak, all stats
+benchmem plot    base.json head.json --metric peak   # interactive plotly view
+
+# name the series/columns independently of the filenames (else the file stem):
+benchmem plot v067.json v070.json v080.json -l 0.6.7 -l 0.7.0 -l 0.8.0
+```
+
+```
+id                          base.json    head.json     change  (B)
+--------------------------------------------------------------------
+test_sort[10000]              824 KiB      848 KiB       +2.9%
+test_sort[100000]             7.6 MiB      7.4 MiB       -2.6%
+test_sort[1000000]            76 MiB       91 MiB       +20.0%
+```
+
+**Gate CI on a memory regression** — exit non-zero past a threshold, mirroring
+pytest-benchmark's `--benchmark-compare-fail=min:5%` grammar for memory:
+
+```bash
+# standalone, over two saved JSON files:
+benchmem compare base.json head.json --fail-on peak:10% --fail-on allocated:10% --fail-on allocations:5%
+
+# or inline in the pytest run, against a prior saved run (pytest-benchmark storage):
+pytest --benchmark-only --benchmark-memory \
+       --benchmark-memory-compare --benchmark-memory-compare-fail=peak:10%
+```
+
+Thresholds are percent (`peak:10%`) or absolute (`peak:5MiB`), on `peak`, `allocated`
+(total bytes, catches churn peak hides), or `allocations` (count, near-deterministic and
+often a better tripwire than peak bytes). Add `--benchmark-memory-profile DIR` to the inline
+gate to keep the memray profile (`DIR/<id>.bin`) for each *regressing* id — render the call
+paths behind the delta with `memray flamegraph` (the run prints the exact command), so a
+failed gate is debuggable, not just red.
+
+Or pull the numbers into your own analysis:
+
+```python
+from pytest_benchmem import from_pytest_benchmark, memory_from_pytest_benchmark
+
+_, timing, _ = from_pytest_benchmark("run.json")         # seconds, from stats
+_, memory, _ = memory_from_pytest_benchmark("run.json")  # bytes, from extra_info.benchmem
+```
+
+Outside pytest, `measure_peak(lambda: build_model(1000))` returns the bare peak in
+bytes; `measure_memory(...)` returns the full `MemoryResult` (peak, spread,
+allocation count) — a one-liner for a REPL or notebook.
+
+## Where it sits
+
+Its reason to exist is the gap nothing else fills cleanly: **memray-precision
+memory benchmarking** of your own code, right where you already benchmark. ASV's
+`peakmem` is coarse RSS sampling that misses numpy/C-allocation detail; CodSpeed
+covers CI timing.
+
+| Need | Reach for | pytest-benchmem |
+|---|---|---|
+| CI regression, per-PR dashboard | **CodSpeed** | — (don't rebuild it) |
+| Local timing + A/B compare | **pytest-benchmark** | rides it (timing is its job) |
+| Rigorous perf history across commits | **ASV** | — (heavier, RSS memory) |
+| **Precise local peak memory (numpy/C allocs)** | **memray** | ⭐ the core |
+| Assert a memory limit / catch a leak *in a test* | **[pytest-memray]** | — (use it; see below) |
+| *Which* function allocated, any test (flamegraph) | **[pytest-memray]** or `memray` | — (use them) |
+| *Where* a benchmark's memory **regressed** | — | ⭐ `--benchmark-memory-profile` (keeps the `.bin`) |
+| Memory *in your pytest-benchmark tests* | — | ⭐ fixture **or** `--benchmark-memory` |
+| **Track/compare/plot** memory across inputs, versions, commits | — | ⭐ compare · sweep · plot |
+
+In short: if your core need is *precise local memory* over the benchmarks you already
+write — timing, sweeps, and plots in one vocabulary — that's pytest-benchmem.
+
+### With pytest-memray
+
+[pytest-memray] is the closest neighbor, and the two are **complements, not
+rivals** — both are thin layers over the same memray engine, pointed in opposite
+directions:
+
+- **pytest-memray** is a *guardrail*: `@pytest.mark.limit_memory("100MiB")`,
+  `limit_leaks`, and flamegraphs that fail or diagnose a test. It tracks the
+  **whole test** (fixtures, data construction, teardown) — the right scope for
+  *"did this test use too much / leak?"*.
+- **pytest-benchmem** is a *benchmark*: it measures **only the benchmarked
+  action**, alongside timing under one node id, and lets you **compare, sweep,
+  and plot** that number across inputs, versions, and commits — *"how does memory
+  scale / change?"*. It has no leak detection by design — but when a memory gate
+  flags a regression, `--benchmark-memory-profile` keeps the offending ids' memray
+  `.bin`s, so *which* allocation grew is a `memray flamegraph` away.
+
+They coexist in one suite. One caveat: memray won't nest two trackers, so don't run
+`pytest --memray` and a benchmem fixture on the *same* test.
+
+## Install
+
+```bash
+uv add pytest-benchmem            # the fixture + flag + memray engine
+uv add "pytest-benchmem[plot]"    # + the plot/compare CLI (pandas, plotly, typer)
+```
+
+pytest-benchmark and memray are core deps; memray is Linux/macOS only, so Windows
+installs cleanly with timing-only (the memory pass raises a clear error there).
+
+## Status
+
+Early. Extracted from the linopy internal benchmark suite, where it's the local
+memory-profiling layer. API may move before 1.0.
+
+[pytest-benchmark]: https://pytest-benchmark.readthedocs.io
+[pytest-memray]: https://pytest-memray.readthedocs.io
+[CodSpeed]: https://codspeed.io
+[ASV]: https://asv.readthedocs.io