feat: actionable error when a memray Tracker is already active (pytest-memray interop)

[FBumann]

What

Part 3 of #82 — the pytest-memray interop guard.

memray allows only one Tracker per process. So if pytest-memray's --memray is profiling a test and a benchmem fixture runs on that same test, benchmem's nested Tracker raises memray's terse:

RuntimeError: No more than one Tracker instance can be active at the same time

_track_once now catches that specific case and re-raises with the likely cause and the fix:

pytest-benchmem couldn't start its memray pass because another memray Tracker is already active — most likely pytest-memray's --memray running on the same test. … Run the two on different tests (or different sessions): pytest-memray for whole-test limits/leaks, pytest-benchmem for the benchmarked action's memory.

Scope / rationale

This is deliberately just a message upgrade — memray already fails loudly and safely, so the guard prevents nothing new; it makes the failure self-explanatory for the interop case. It matches the existing _compute_statistics guard, which already translates an internal-memray error into actionable guidance. We considered shipping only the doc caveat (memray's own error isn't terrible) but opted to keep the friendlier message, in keeping with the house style.

• Matches on memray's wording ("more than one Tracker"); any other RuntimeError propagates unchanged, and if memray changes the text we fall back to its original error (graceful, low-consequence coupling, pinned by the test).

Tests

test_nested_tracker_raises_actionable_error — opens an outer memray.Tracker (standing in for --memray) and asserts measure_memory(...) raises the actionable RuntimeError. Full test_memray.py: 7 passed. ruff format --diff, ruff check, and mypy src + tests all clean (the exact CI gates).

Docs

README "With pytest-memray" caveat now notes benchmem fails that test with an actionable error rather than a terse memray one.

Closes #82.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 pytest-benchmem | 🛠️ Build #33144698 | 📁 Comparing 414a0d5 against latest (8230ddb)

  🔍 Preview build  

5 files changed · ± 5 modified

± Modified

• compare-plot/index.html
• dims/index.html
• getting-started/index.html
• metrics/index.html
• reference/index.html