pytest-benchmem 0.1.0__tar.gz

pytest_benchmem-0.1.0/.github/dependabot.yml

@@ -0,0 +1,34 @@
+version: 2
+
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore"
+    groups:
+      linting:
+        patterns:
+          - "ruff"
+          - "mypy"
+          - "pre-commit"
+      testing:
+        patterns:
+          - "pytest*"
+      documentation:
+        patterns:
+          - "mkdocs*"
+          - "jupytext"
+          - "ipykernel"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "ci"

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

@@ -0,0 +1,53 @@
+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/ruff-action@v3
+      - run: ruff check --output-format=github
+      - 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
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "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

pytest_benchmem-0.1.0/.github/workflows/dependabot-auto-merge.yaml

@@ -0,0 +1,27 @@
+name: Dependabot auto-merge
+
+on:
+  pull_request:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    name: Auto-merge patch
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: dependabot/fetch-metadata@v3
+        id: metadata
+
+      # No GitHub App / secrets: just enable auto-merge with the default token.
+      # The PR merges once required checks pass (no separate approval step,
+      # which the default GITHUB_TOKEN can't give a bot PR anyway).
+      - name: Enable auto-merge for patch updates
+        if: steps.metadata.outputs.update-type == 'version-update:semver-patch'
+        run: gh pr merge "$PR" --auto --squash
+        env:
+          PR: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ github.token }}

pytest_benchmem-0.1.0/.github/workflows/docs.yaml

@@ -0,0 +1,28 @@
+name: Docs
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Build & deploy
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      # Build the notebook from its jupytext source, then build+execute the site.
+      - run: uv sync --group docs
+      - run: uv run jupytext --to ipynb docs/walkthrough.md
+      - run: uv run mkdocs gh-deploy --force

pytest_benchmem-0.1.0/.github/workflows/pr-title.yaml

@@ -0,0 +1,32 @@
+name: PR Title
+
+on:
+  push:
+    branches: ["release-please--**"]
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  validate:
+    name: Validate conventional commit format
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    permissions:
+      pull-requests: read
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        with:
+          types: |
+            feat
+            fix
+            refactor
+            perf
+            docs
+            test
+            build
+            ci
+            chore
+            revert
+            style
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

pytest_benchmem-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,70 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to (re)publish to PyPI, e.g. v0.0.1"
+        required: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    name: Release Please
+    if: github.event_name == 'push'
+    runs-on: ubuntu-24.04
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      # Default GITHUB_TOKEN — no GitHub App / secrets. Publishing is a
+      # downstream job in this same run, so the "GITHUB_TOKEN won't trigger
+      # another workflow" limitation never applies.
+      - uses: googleapis/release-please-action@v5
+        id: release
+        with:
+          config-file: .release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    name: Build & publish to PyPI
+    needs: release-please
+    # Auto: when release-please cuts a release. Manual: workflow_dispatch with a
+    # tag (always() lets this run even though release-please is skipped on dispatch).
+    if: |
+      always() &&
+      (needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pytest-benchmem
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: uv build
+
+      # OIDC trusted publishing — no API token. The PyPI publisher must point at
+      # this workflow file (release.yaml) and the 'pypi' environment.
+      - uses: pypa/gh-action-pypi-publish@release/v1

pytest_benchmem-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.benchmarks/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.bin
+
+# lockfile not tracked for a library — resolve fresh against current deps
+uv.lock
+
+# jupytext-built notebooks (source is the .md) + mkdocs build
+docs/*.ipynb
+site/
+.cache/
+
+# editors
+.idea/
+.vscode/

pytest_benchmem-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src/pytest_benchmem
+        language: system
+        pass_filenames: false
+        files: ^src/
+        types: [python]

pytest_benchmem-0.1.0/.release-please-config.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "bootstrap-sha": "384d876391b7d0c496ee01f34f25731f4c8487f9",
+  "include-component-in-tag": false,
+  "packages": {
+    ".": {
+      "release-type": "simple",
+      "package-name": "pytest-benchmem",
+      "bump-minor-for-major-pre-major": true,
+      "bump-patch-for-minor-pre-major": true,
+      "changelog-path": "CHANGELOG.md",
+      "initial-version": "0.0.1"
+    }
+  }
+}

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

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

pytest_benchmem-0.1.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## [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.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Bumann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_benchmem-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: pytest-benchmem
+Version: 0.1.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>=1.11; platform_system == 'Linux' or platform_system == 'Darwin'
+Requires-Dist: pytest-benchmark<6,>=4
+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.
+
+## Quickstart
+
+Write a normal pytest-benchmark test; swap `benchmark` for `benchmark_memory`:
+
+```python
+import pytest
+
+
+@pytest.mark.parametrize("n", [10_000, 100_000, 1_000_000])
+def test_sort(benchmark_memory, n):
+    data = list(range(n, 0, -1))
+    benchmark_memory(sorted, data)
+```
+
+```bash
+pytest --benchmark-only --benchmark-json=run.json
+```
+
+One run, one `run.json`, for each benchmark id — both metrics, one node id:
+
+- `stats: {min, mean, median, …}` — **timing**, from pytest-benchmark.
+- `extra_info: {"peak_mib": 3.81}` — **peak memory**, from pytest-benchmem.
+
+The two passes never overlap: pytest-benchmark times the action untracked, then
+memray measures peak on a *separate, untimed* call — so the allocator hooks cost
+the timing nothing. The parametrize `params` become the analysis dims the plots
+scale by.
+
+## Already have a pytest-benchmark suite?
+
+Don't rewrite a thing — add `--benchmark-memory` and every `benchmark(...)` call
+also records peak memory:
+
+```python
+def test_sort(benchmark):            # unchanged
+    benchmark(sorted, list(range(1_000_000, 0, -1)))
+```
+
+```bash
+pytest --benchmark-only --benchmark-memory   # timing + peak_mib for the whole suite
+```
+
+It's opt-in at the run level: without the flag, plain `benchmark` tests are
+untouched. (Reach for the `benchmark_memory` fixture when you want memory on
+specific tests only, or `pedantic` control.)
+
+## 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 --metric memory   # per-id delta table
+benchmem plot    base.json head.json --metric memory   # interactive plotly view
+```
+
+```
+id                          base.json    head.json     change  (MiB)
+--------------------------------------------------------------------
+test_sort[10000]                0.076        0.078       +2.6%
+test_sort[100000]               0.76         0.74        -2.6%
+test_sort[1000000]              7.63         9.155       +20.0%
+```
+
+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")  # MiB, from extra_info
+```
+
+Outside pytest, `measure_peak(lambda: build_model(1000))` is the bare memray
+engine — a one-liner peak number 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 |
+| Memory *in your pytest-benchmark tests* | — | ⭐ fixture **or** `--benchmark-memory` |
+| Same runs across installed versions | — | ⭐ `sweep` |
+
+> **Not** a CI dashboard (use [CodSpeed]) and **not** a rigorous perf-history
+> system (use [ASV]). If your core need is *precise local memory* over the
+> benchmarks you already write — timing/sweeps/plots in one vocabulary — that's
+> pytest-benchmem.
+
+## 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
+[CodSpeed]: https://codspeed.io
+[ASV]: https://asv.readthedocs.io

pytest_benchmem-0.1.0/README.md

@@ -0,0 +1,126 @@
+# 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.
+
+## Quickstart
+
+Write a normal pytest-benchmark test; swap `benchmark` for `benchmark_memory`:
+
+```python
+import pytest
+
+
+@pytest.mark.parametrize("n", [10_000, 100_000, 1_000_000])
+def test_sort(benchmark_memory, n):
+    data = list(range(n, 0, -1))
+    benchmark_memory(sorted, data)
+```
+
+```bash
+pytest --benchmark-only --benchmark-json=run.json
+```
+
+One run, one `run.json`, for each benchmark id — both metrics, one node id:
+
+- `stats: {min, mean, median, …}` — **timing**, from pytest-benchmark.
+- `extra_info: {"peak_mib": 3.81}` — **peak memory**, from pytest-benchmem.
+
+The two passes never overlap: pytest-benchmark times the action untracked, then
+memray measures peak on a *separate, untimed* call — so the allocator hooks cost
+the timing nothing. The parametrize `params` become the analysis dims the plots
+scale by.
+
+## Already have a pytest-benchmark suite?
+
+Don't rewrite a thing — add `--benchmark-memory` and every `benchmark(...)` call
+also records peak memory:
+
+```python
+def test_sort(benchmark):            # unchanged
+    benchmark(sorted, list(range(1_000_000, 0, -1)))
+```
+
+```bash
+pytest --benchmark-only --benchmark-memory   # timing + peak_mib for the whole suite
+```
+
+It's opt-in at the run level: without the flag, plain `benchmark` tests are
+untouched. (Reach for the `benchmark_memory` fixture when you want memory on
+specific tests only, or `pedantic` control.)
+
+## 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 --metric memory   # per-id delta table
+benchmem plot    base.json head.json --metric memory   # interactive plotly view
+```
+
+```
+id                          base.json    head.json     change  (MiB)
+--------------------------------------------------------------------
+test_sort[10000]                0.076        0.078       +2.6%
+test_sort[100000]               0.76         0.74        -2.6%
+test_sort[1000000]              7.63         9.155       +20.0%
+```
+
+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")  # MiB, from extra_info
+```
+
+Outside pytest, `measure_peak(lambda: build_model(1000))` is the bare memray
+engine — a one-liner peak number 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 |
+| Memory *in your pytest-benchmark tests* | — | ⭐ fixture **or** `--benchmark-memory` |
+| Same runs across installed versions | — | ⭐ `sweep` |
+
+> **Not** a CI dashboard (use [CodSpeed]) and **not** a rigorous perf-history
+> system (use [ASV]). If your core need is *precise local memory* over the
+> benchmarks you already write — timing/sweeps/plots in one vocabulary — that's
+> pytest-benchmem.
+
+## 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
+[CodSpeed]: https://codspeed.io
+[ASV]: https://asv.readthedocs.io