pytest-gc-steward 0.1.0__tar.gz

pytest_gc_steward-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+.installed.cfg
+MANIFEST
+
+# Virtualenvs
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+.uv/
+uv.lock
+
+# Tooling
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# django-run-site / django-dev-helpers dotfiles
+.dev_helpers_token
+.dev_helpers_port
+.dev_helpers_pg_port
+.dev_helpers_redis_port
+.run-site-*
+
+# Django
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Test artifacts
+.tox/
+.cache/
+test-output/
+
+# Examples — generated at runtime
+examples/test_site/.venv/
+examples/test_site/db.sqlite3

pytest_gc_steward-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- First release: `--gc-freeze`, `--gc-every`, `--gc-rss-growth`, `--gc-disable`,
+  `--gc-report` (per type / test / module census of what the cyclic GC
+  reclaims), ini equivalents, pytest-xdist aggregation.

pytest_gc_steward-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michał Pasternak
+
+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_gc_steward-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: pytest-gc-steward
+Version: 0.1.0
+Summary: Keep pytest workers from bloating: gc.freeze(), periodic or RSS-triggered garbage collection, and reports of what the cyclic GC collects.
+Project-URL: Funding, https://buymeacoffee.com/mpasternak
+Project-URL: Homepage, https://github.com/iplweb/pytest-gc-steward
+Project-URL: Source, https://github.com/iplweb/pytest-gc-steward
+Project-URL: Issues, https://github.com/iplweb/pytest-gc-steward/issues
+Author-email: Michał Pasternak <michal.dtz@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Michał Pasternak
+        
+        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.
+License-File: LICENSE
+Keywords: garbage collection,gc,memory,pytest,reference cycles,xdist
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pytest>=7
+Provides-Extra: dev
+Requires-Dist: psutil>=5; extra == 'dev'
+Requires-Dist: pytest-xdist>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
+Provides-Extra: rss
+Requires-Dist: psutil>=5; extra == 'rss'
+Description-Content-Type: text/markdown
+
+# pytest-gc-steward
+
+**Stop pytest workers from bloating.** A pytest plugin that takes charge of
+Python's cyclic garbage collector during a test session — `gc.freeze()` at
+startup, collections every N tests or after N MB of growth — and tells you
+**what** the collector keeps reclaiming, so you can fix the source.
+
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-%E2%98%95-yellow)](https://buymeacoffee.com/mpasternak)
+
+```bash
+pip install pytest-gc-steward
+pytest --gc-freeze --gc-every 25        # keep memory flat
+pytest --gc-report gc.json              # find out where the garbage comes from
+```
+
+---
+
+## Why would I need this?
+
+Most Python objects die the moment their reference count drops to zero. Objects
+caught in a **reference cycle** (A → B → A) never get there — they wait for the
+cyclic garbage collector. Test suites produce a lot of them: test-client
+responses, rendered templates and their contexts, tracebacks holding frames
+holding every local variable...
+
+If the collector reclaims that garbage more slowly than your tests produce it,
+**each process quietly grows** for the whole session. With `pytest-xdist` you
+pay that once per worker.
+
+### A real case
+
+This plugin was written while debugging a Django project with ~11 000 tests.
+`pytest -n auto` (14 workers) on a 14 GB laptop froze the machine: swap
+thrashing, hard reset. What we found:
+
+| | time | RSS of one worker after 1266 tests |
+|---|---|---|
+| before | 247 s | **1801 MB** |
+| `gc.collect()` after *every* test | 719 s | 581 MB |
+| `--gc-freeze --gc-every 25` | **239 s** | **624 MB** |
+
+`--gc-report` then showed *why*: about 85% of what the collector reclaimed was
+compiled template nodes. Three things had stacked up:
+
+1. **Python 3.14.0–3.14.4** shipped an incremental GC that, on large heaps,
+   collected cycles far too slowly. It was
+   [reverted in 3.14.5](https://discuss.python.org/t/reverting-the-incremental-gc-in-python-3-14-and-3-15/107014).
+2. The project's test settings used **uncached template loaders**, so every
+   render re-parsed every template.
+3. **Django's test client** puts every response in a reference cycle
+   (`response.json = partial(self._parse_json, response)`), and the response
+   carries all rendered templates and contexts with it.
+
+Fixing the source (cached loaders, a current Python) brought the worker to the
+same 625 MB **without** forced collections. The plugin pointed at all three;
+the reproducer for the third is being reported upstream.
+
+### When it helps
+
+- Memory of test processes grows steadily over a session, and `gc.collect()`
+  makes it drop. That's the signature of cyclic garbage, not of a real leak.
+- You run many xdist workers and RAM, not CPU, is what limits `-n`.
+- You are stuck on a Python with lazy cycle collection (e.g. 3.14.0–3.14.4).
+- You want to *find* which tests and which object types produce cycles.
+
+If `gc.collect()` does **not** reduce memory, you have objects that are still
+referenced (caches, globals, fixtures): a real leak. This plugin won't fix that,
+although the report still shows you what isn't garbage.
+
+---
+
+## Usage
+
+Everything is **off by default**. Installing the plugin changes nothing until
+you turn something on, from the command line or `pytest.ini` /
+`pyproject.toml`:
+
+| Option | ini | What it does |
+|---|---|---|
+| `--gc-freeze` | `gc_steward_freeze = true` | Before the first test: `gc.collect()` + `gc.freeze()`. Everything imported and collected so far (often millions of objects in a Django project) moves to the permanent generation, so later collections don't rescan it. This is what makes frequent collections cheap. |
+| `--gc-every N` | `gc_steward_every = N` | Force `gc.collect()` after every N tests. |
+| `--gc-rss-growth MB` | `gc_steward_rss_growth = MB` | Force `gc.collect()` when the process grew by MB since the last forced collection. The baseline resets after each collection, because CPython rarely gives memory back to the OS. |
+| `--gc-disable` | `gc_steward_disable = true` | Turn the automatic collector off during tests (setup before the first test still runs with it on). Use together with `--gc-every` / `--gc-rss-growth`, or you may be the one who freezes the laptop. |
+| `--gc-report PATH` | `gc_steward_report = PATH` | Diagnostics: after **every** test collect with `gc.DEBUG_SAVEALL`, count what was reclaimed by object type, test and module, print the top entries and write a JSON report. Slow — run it once, on a subset. |
+| `--gc-report-top N` | `gc_steward_report_top = N` | Entries per report section (default 25). |
+
+Command-line options win over ini values.
+
+### Recommended setup
+
+```ini
+# pytest.ini
+[pytest]
+gc_steward_freeze = true
+gc_steward_every = 25
+```
+
+`--gc-every 25` with `--gc-freeze` cost us nothing measurable; the run was even
+slightly faster, because the process wasn't dragging a 1.8 GB heap around.
+Without `--gc-freeze`, each full collection rescans the whole heap — in our
+project ~0.4 s each.
+
+### pytest-xdist
+
+Each worker steers its own collector. The controller gathers the numbers and
+prints one line per worker, and `--gc-report` merges all workers into one file:
+
+```
+============================== gc-steward ==============================
+gw0: 412 tests, RSS 351 -> 598 MB (peak 640); forced 16x (1.84 s, 1203391 objects); automatic gen0 1832, gen1 166, gen2 3 (0.91 s, 88213 objects); frozen 2154007
+gw1: 397 tests, RSS 350 -> 571 MB (peak 612); forced 15x (1.71 s, 1176502 objects); automatic gen0 1790, gen1 162, gen2 2 (0.88 s, 84117 objects); frozen 2154011
+```
+
+### Reading a report
+
+```bash
+pytest tests/admin --gc-report gc.json -p no:randomly
+```
+
+```
+objects reclaimed by the cyclic GC, by type (top 25):
+     2132705  django.template.base.Token
+     1201038  django.template.base.TextNode
+      988340  django.template.base.FilterExpression
+      ...
+by test (top 25):
+      281339  tests/admin/test_home_links.py::test_admin_home_links_resolve
+      ...
+```
+
+- **Types** say *what* is in the cycles. Template nodes point at template
+  compilation; `frame` / `traceback` point at stored exceptions; your own
+  classes point at your own code.
+- **Tests / modules** say *where*. A handful of tests standing out is a
+  local bug; an even spread points at shared infrastructure (a test client,
+  a base class, middleware).
+- To find the cycle itself, take one suspect object and walk
+  `gc.get_referents()` until you are back where you started. Usually it's one
+  attribute pointing back at its owner (`self.callback = partial(f, self)`).
+
+The JSON file holds per-process stats (`processes`) and merged counters
+(`merged.types`, `merged.tests_top`, `merged.modules`).
+
+### Terminal line, explained
+
+`forced` are the collections the plugin ran; `automatic` are the interpreter's
+own, per generation, observed through `gc.callbacks`. `objects` is what each
+kind reclaimed. If `forced` reclaims a lot while `automatic gen2` stays near
+zero, the interpreter wasn't getting around to your cycles.
+
+---
+
+## How it works
+
+Hooks around `pytest_runtest_protocol`: the first call optionally collects and
+freezes; after each test it decides whether to collect (counter or RSS
+growth). RSS comes from `/proc/self/statm` on Linux, `psutil` elsewhere if it is
+installed (`pip install pytest-gc-steward[rss]`), and peak RSS from
+`resource.getrusage` as a last resort. At session end the freeze is undone and
+the automatic collector re-enabled.
+
+Requires Python ≥ 3.10 and pytest ≥ 7.
+
+## Support
+
+If this saved your laptop (or your CI bill), you can
+[buy me a coffee](https://buymeacoffee.com/mpasternak) ☕.
+
+Issues and pull requests: https://github.com/iplweb/pytest-gc-steward
+
+## License
+
+MIT

pytest_gc_steward-0.1.0/README.md

@@ -0,0 +1,173 @@
+# pytest-gc-steward
+
+**Stop pytest workers from bloating.** A pytest plugin that takes charge of
+Python's cyclic garbage collector during a test session — `gc.freeze()` at
+startup, collections every N tests or after N MB of growth — and tells you
+**what** the collector keeps reclaiming, so you can fix the source.
+
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-%E2%98%95-yellow)](https://buymeacoffee.com/mpasternak)
+
+```bash
+pip install pytest-gc-steward
+pytest --gc-freeze --gc-every 25        # keep memory flat
+pytest --gc-report gc.json              # find out where the garbage comes from
+```
+
+---
+
+## Why would I need this?
+
+Most Python objects die the moment their reference count drops to zero. Objects
+caught in a **reference cycle** (A → B → A) never get there — they wait for the
+cyclic garbage collector. Test suites produce a lot of them: test-client
+responses, rendered templates and their contexts, tracebacks holding frames
+holding every local variable...
+
+If the collector reclaims that garbage more slowly than your tests produce it,
+**each process quietly grows** for the whole session. With `pytest-xdist` you
+pay that once per worker.
+
+### A real case
+
+This plugin was written while debugging a Django project with ~11 000 tests.
+`pytest -n auto` (14 workers) on a 14 GB laptop froze the machine: swap
+thrashing, hard reset. What we found:
+
+| | time | RSS of one worker after 1266 tests |
+|---|---|---|
+| before | 247 s | **1801 MB** |
+| `gc.collect()` after *every* test | 719 s | 581 MB |
+| `--gc-freeze --gc-every 25` | **239 s** | **624 MB** |
+
+`--gc-report` then showed *why*: about 85% of what the collector reclaimed was
+compiled template nodes. Three things had stacked up:
+
+1. **Python 3.14.0–3.14.4** shipped an incremental GC that, on large heaps,
+   collected cycles far too slowly. It was
+   [reverted in 3.14.5](https://discuss.python.org/t/reverting-the-incremental-gc-in-python-3-14-and-3-15/107014).
+2. The project's test settings used **uncached template loaders**, so every
+   render re-parsed every template.
+3. **Django's test client** puts every response in a reference cycle
+   (`response.json = partial(self._parse_json, response)`), and the response
+   carries all rendered templates and contexts with it.
+
+Fixing the source (cached loaders, a current Python) brought the worker to the
+same 625 MB **without** forced collections. The plugin pointed at all three;
+the reproducer for the third is being reported upstream.
+
+### When it helps
+
+- Memory of test processes grows steadily over a session, and `gc.collect()`
+  makes it drop. That's the signature of cyclic garbage, not of a real leak.
+- You run many xdist workers and RAM, not CPU, is what limits `-n`.
+- You are stuck on a Python with lazy cycle collection (e.g. 3.14.0–3.14.4).
+- You want to *find* which tests and which object types produce cycles.
+
+If `gc.collect()` does **not** reduce memory, you have objects that are still
+referenced (caches, globals, fixtures): a real leak. This plugin won't fix that,
+although the report still shows you what isn't garbage.
+
+---
+
+## Usage
+
+Everything is **off by default**. Installing the plugin changes nothing until
+you turn something on, from the command line or `pytest.ini` /
+`pyproject.toml`:
+
+| Option | ini | What it does |
+|---|---|---|
+| `--gc-freeze` | `gc_steward_freeze = true` | Before the first test: `gc.collect()` + `gc.freeze()`. Everything imported and collected so far (often millions of objects in a Django project) moves to the permanent generation, so later collections don't rescan it. This is what makes frequent collections cheap. |
+| `--gc-every N` | `gc_steward_every = N` | Force `gc.collect()` after every N tests. |
+| `--gc-rss-growth MB` | `gc_steward_rss_growth = MB` | Force `gc.collect()` when the process grew by MB since the last forced collection. The baseline resets after each collection, because CPython rarely gives memory back to the OS. |
+| `--gc-disable` | `gc_steward_disable = true` | Turn the automatic collector off during tests (setup before the first test still runs with it on). Use together with `--gc-every` / `--gc-rss-growth`, or you may be the one who freezes the laptop. |
+| `--gc-report PATH` | `gc_steward_report = PATH` | Diagnostics: after **every** test collect with `gc.DEBUG_SAVEALL`, count what was reclaimed by object type, test and module, print the top entries and write a JSON report. Slow — run it once, on a subset. |
+| `--gc-report-top N` | `gc_steward_report_top = N` | Entries per report section (default 25). |
+
+Command-line options win over ini values.
+
+### Recommended setup
+
+```ini
+# pytest.ini
+[pytest]
+gc_steward_freeze = true
+gc_steward_every = 25
+```
+
+`--gc-every 25` with `--gc-freeze` cost us nothing measurable; the run was even
+slightly faster, because the process wasn't dragging a 1.8 GB heap around.
+Without `--gc-freeze`, each full collection rescans the whole heap — in our
+project ~0.4 s each.
+
+### pytest-xdist
+
+Each worker steers its own collector. The controller gathers the numbers and
+prints one line per worker, and `--gc-report` merges all workers into one file:
+
+```
+============================== gc-steward ==============================
+gw0: 412 tests, RSS 351 -> 598 MB (peak 640); forced 16x (1.84 s, 1203391 objects); automatic gen0 1832, gen1 166, gen2 3 (0.91 s, 88213 objects); frozen 2154007
+gw1: 397 tests, RSS 350 -> 571 MB (peak 612); forced 15x (1.71 s, 1176502 objects); automatic gen0 1790, gen1 162, gen2 2 (0.88 s, 84117 objects); frozen 2154011
+```
+
+### Reading a report
+
+```bash
+pytest tests/admin --gc-report gc.json -p no:randomly
+```
+
+```
+objects reclaimed by the cyclic GC, by type (top 25):
+     2132705  django.template.base.Token
+     1201038  django.template.base.TextNode
+      988340  django.template.base.FilterExpression
+      ...
+by test (top 25):
+      281339  tests/admin/test_home_links.py::test_admin_home_links_resolve
+      ...
+```
+
+- **Types** say *what* is in the cycles. Template nodes point at template
+  compilation; `frame` / `traceback` point at stored exceptions; your own
+  classes point at your own code.
+- **Tests / modules** say *where*. A handful of tests standing out is a
+  local bug; an even spread points at shared infrastructure (a test client,
+  a base class, middleware).
+- To find the cycle itself, take one suspect object and walk
+  `gc.get_referents()` until you are back where you started. Usually it's one
+  attribute pointing back at its owner (`self.callback = partial(f, self)`).
+
+The JSON file holds per-process stats (`processes`) and merged counters
+(`merged.types`, `merged.tests_top`, `merged.modules`).
+
+### Terminal line, explained
+
+`forced` are the collections the plugin ran; `automatic` are the interpreter's
+own, per generation, observed through `gc.callbacks`. `objects` is what each
+kind reclaimed. If `forced` reclaims a lot while `automatic gen2` stays near
+zero, the interpreter wasn't getting around to your cycles.
+
+---
+
+## How it works
+
+Hooks around `pytest_runtest_protocol`: the first call optionally collects and
+freezes; after each test it decides whether to collect (counter or RSS
+growth). RSS comes from `/proc/self/statm` on Linux, `psutil` elsewhere if it is
+installed (`pip install pytest-gc-steward[rss]`), and peak RSS from
+`resource.getrusage` as a last resort. At session end the freeze is undone and
+the automatic collector re-enabled.
+
+Requires Python ≥ 3.10 and pytest ≥ 7.
+
+## Support
+
+If this saved your laptop (or your CI bill), you can
+[buy me a coffee](https://buymeacoffee.com/mpasternak) ☕.
+
+Issues and pull requests: https://github.com/iplweb/pytest-gc-steward
+
+## License
+
+MIT

pytest_gc_steward-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytest-gc-steward"
+version = "0.1.0"
+description = "Keep pytest workers from bloating: gc.freeze(), periodic or RSS-triggered garbage collection, and reports of what the cyclic GC collects."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Michał Pasternak", email = "michal.dtz@gmail.com" },
+]
+keywords = ["pytest", "gc", "garbage collection", "memory", "xdist", "reference cycles"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = ["pytest>=7"]
+
+[project.optional-dependencies]
+rss = ["psutil>=5"]
+dev = [
+    "pytest>=8",
+    "pytest-xdist>=3",
+    "psutil>=5",
+    "ruff>=0.15,<0.16",
+]
+
+[project.entry-points.pytest11]
+gc_steward = "pytest_gc_steward.plugin"
+
+[project.urls]
+Funding = "https://buymeacoffee.com/mpasternak"
+Homepage = "https://github.com/iplweb/pytest-gc-steward"
+Source = "https://github.com/iplweb/pytest-gc-steward"
+Issues = "https://github.com/iplweb/pytest-gc-steward/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pytest_gc_steward"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-p pytester"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]

pytest_gc_steward-0.1.0/src/pytest_gc_steward/__init__.py

@@ -0,0 +1,3 @@
+"""pytest-gc-steward: garbage-collector control and diagnostics for pytest."""
+
+__version__ = "0.1.0"

pytest_gc_steward-0.1.0/src/pytest_gc_steward/plugin.py

@@ -0,0 +1,345 @@
+"""pytest plugin: steer the cyclic garbage collector and report what it finds.
+
+Why this exists: objects caught in reference cycles are not freed by reference
+counting; they wait for the cyclic GC. In long test sessions (test clients,
+templates, tracebacks...) that garbage can pile up faster than the automatic
+collector reclaims it, and every pytest-xdist worker bloats. The plugin can:
+
+* ``gc.freeze()`` everything that exists before the first test (imported
+  modules, collected items), so later collections don't rescan it;
+* force ``gc.collect()`` every N tests and/or whenever RSS grew by N MB since
+  the last forced collection;
+* optionally disable the automatic collector for the session;
+* report, per object type / test / module, what the collector reclaims, to
+  find where the cycles come from.
+
+All options are off by default: installing the plugin changes nothing until
+you enable something.
+"""
+
+from __future__ import annotations
+
+import gc
+import json
+import time
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from .rss import current_rss_mb
+
+_KEY = "gc_steward"
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("gc-steward", "garbage collector control and diagnostics")
+    group.addoption(
+        "--gc-freeze",
+        action="store_true",
+        default=None,
+        help="gc.freeze() all objects alive before the first test, so later "
+        "collections skip them (ini: gc_steward_freeze).",
+    )
+    group.addoption(
+        "--gc-every",
+        type=int,
+        default=None,
+        metavar="N",
+        help="force gc.collect() after every N tests; 0 = off (ini: gc_steward_every).",
+    )
+    group.addoption(
+        "--gc-rss-growth",
+        type=float,
+        default=None,
+        metavar="MB",
+        help="force gc.collect() when RSS grew by MB since the last forced "
+        "collection; 0 = off (ini: gc_steward_rss_growth).",
+    )
+    group.addoption(
+        "--gc-disable",
+        action="store_true",
+        default=None,
+        help="disable the automatic collector during tests; combine with "
+        "--gc-every / --gc-rss-growth (ini: gc_steward_disable).",
+    )
+    group.addoption(
+        "--gc-report",
+        default=None,
+        metavar="PATH",
+        help="collect after EVERY test with gc.DEBUG_SAVEALL and write a JSON "
+        "report of what the GC reclaimed (by type, test and module). Slow: "
+        "diagnostics only (ini: gc_steward_report).",
+    )
+    group.addoption(
+        "--gc-report-top",
+        type=int,
+        default=None,
+        metavar="N",
+        help="how many entries to keep / show per report section "
+        "(default 25, ini: gc_steward_report_top).",
+    )
+    parser.addini("gc_steward_freeze", "see --gc-freeze", type="bool", default=False)
+    parser.addini("gc_steward_every", "see --gc-every", default="0")
+    parser.addini("gc_steward_rss_growth", "see --gc-rss-growth", default="0")
+    parser.addini("gc_steward_disable", "see --gc-disable", type="bool", default=False)
+    parser.addini("gc_steward_report", "see --gc-report", default="")
+    parser.addini("gc_steward_report_top", "see --gc-report-top", default="25")
+
+
+def _opt(config: pytest.Config, name: str, ini: str, cast):
+    value = config.getoption(name)
+    if value is None:
+        value = config.getini(ini)
+    return cast(value) if value not in ("", None) else cast()
+
+
+def _type_key(obj: object) -> str:
+    cls = type(obj)
+    module = cls.__dict__.get("__module__")
+    if not isinstance(module, str) or module == "builtins":
+        return cls.__qualname__
+    return f"{module}.{cls.__qualname__}"
+
+
+class Steward:
+    def __init__(self, config: pytest.Config) -> None:
+        self.config = config
+        self.freeze = bool(_opt(config, "gc_freeze", "gc_steward_freeze", bool))
+        self.every = _opt(config, "gc_every", "gc_steward_every", int)
+        self.rss_growth = _opt(config, "gc_rss_growth", "gc_steward_rss_growth", float)
+        self.disable = bool(_opt(config, "gc_disable", "gc_steward_disable", bool))
+        self.report_path = _opt(config, "gc_report", "gc_steward_report", str)
+        self.top = _opt(config, "gc_report_top", "gc_steward_report_top", int) or 25
+        self.active = bool(
+            self.freeze or self.every or self.rss_growth or self.disable
+        ) or bool(self.report_path)
+
+        self.tests = 0
+        self.started = False
+        self.was_enabled = gc.isenabled()
+        self.rss_start = current_rss_mb()
+        self.rss_peak = self.rss_start or 0.0
+        self.rss_baseline = self.rss_start
+        self.frozen = 0
+        self.forced = 0
+        self.forced_seconds = 0.0
+        self.forced_objects = 0
+        self.auto = Counter()  # generation -> runs
+        self.auto_seconds = 0.0
+        self.auto_objects = 0
+        self._auto_t0 = 0.0
+        self._in_forced = False
+        self.types: Counter[str] = Counter()
+        self.per_test: Counter[str] = Counter()
+        self.per_module: Counter[str] = Counter()
+
+    # -- automatic collections (observed, not driven) -----------------------
+    def _callback(self, phase: str, info: dict[str, Any]) -> None:
+        if self._in_forced:
+            return
+        if phase == "start":
+            self._auto_t0 = time.perf_counter()
+        else:
+            self.auto_seconds += time.perf_counter() - self._auto_t0
+            self.auto[info.get("generation", -1)] += 1
+            self.auto_objects += info.get("collected", 0)
+
+    # -- forced collections --------------------------------------------------
+    def _collect(self) -> int:
+        self._in_forced = True
+        t0 = time.perf_counter()
+        try:
+            collected = gc.collect()
+        finally:
+            self.forced_seconds += time.perf_counter() - t0
+            self._in_forced = False
+        self.forced += 1
+        self.forced_objects += collected
+        return collected
+
+    def _census(self, nodeid: str) -> None:
+        """Collect with DEBUG_SAVEALL and count what would have been freed."""
+        old = gc.get_debug()
+        gc.set_debug(old | gc.DEBUG_SAVEALL)
+        try:
+            self._collect()
+        finally:
+            gc.set_debug(old)
+        found = Counter(_type_key(o) for o in gc.garbage)
+        gc.garbage.clear()
+        self._collect()  # now really free what DEBUG_SAVEALL kept alive
+        total = sum(found.values())
+        if total:
+            self.types.update(found)
+            self.per_test[nodeid] += total
+            self.per_module[nodeid.split("::", 1)[0]] += total
+
+    # -- hooks ---------------------------------------------------------------
+    def start(self) -> None:
+        self.started = True
+        gc.callbacks.append(self._callback)
+        if self.freeze:
+            self._collect()
+            gc.freeze()
+            self.frozen = gc.get_freeze_count()
+        if self.disable:
+            gc.disable()
+        self.rss_baseline = current_rss_mb()
+
+    @pytest.hookimpl(hookwrapper=True)
+    def pytest_runtest_protocol(self, item: pytest.Item, nextitem):
+        if not self.started:
+            self.start()
+        yield
+        self.tests += 1
+        rss = current_rss_mb()
+        if rss is not None:
+            self.rss_peak = max(self.rss_peak, rss)
+        if self.report_path:
+            self._census(item.nodeid)
+            self.rss_baseline = current_rss_mb()
+            return
+        due = bool(self.every) and self.tests % self.every == 0
+        if not due and self.rss_growth and rss is not None and self.rss_baseline:
+            due = rss - self.rss_baseline >= self.rss_growth
+        if due:
+            self._collect()
+            self.rss_baseline = current_rss_mb()
+
+    def stop(self) -> None:
+        if self._callback in gc.callbacks:
+            gc.callbacks.remove(self._callback)
+        if self.freeze:
+            gc.unfreeze()
+        if self.disable and self.was_enabled:
+            gc.enable()
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "tests": self.tests,
+            "frozen": self.frozen,
+            "forced": self.forced,
+            "forced_seconds": round(self.forced_seconds, 3),
+            "forced_objects": self.forced_objects,
+            "auto": {str(k): v for k, v in sorted(self.auto.items())},
+            "auto_seconds": round(self.auto_seconds, 3),
+            "auto_objects": self.auto_objects,
+            "rss_start_mb": round(self.rss_start, 1) if self.rss_start else None,
+            "rss_end_mb": _round(current_rss_mb()),
+            "rss_peak_mb": round(self.rss_peak, 1) if self.rss_peak else None,
+            "types": dict(self.types.most_common(self.top * 4)),
+            "tests_top": dict(self.per_test.most_common(self.top * 4)),
+            "modules": dict(self.per_module.most_common(self.top * 4)),
+        }
+
+
+def _round(value: float | None) -> float | None:
+    return round(value, 1) if value is not None else None
+
+
+def _is_xdist_controller(config: pytest.Config) -> bool:
+    return config.pluginmanager.hasplugin("dsession") and not hasattr(
+        config, "workerinput"
+    )
+
+
+@pytest.hookimpl(trylast=True)
+def pytest_configure(config: pytest.Config) -> None:
+    steward = Steward(config)
+    config.stash[_STASH] = steward
+    config.stash[_WORKERS] = {}
+    if not steward.active:
+        return
+    if not _is_xdist_controller(config):
+        config.pluginmanager.register(steward, "gc-steward-runtime")
+    if config.pluginmanager.hasplugin("xdist"):
+        config.pluginmanager.register(_XdistController(config), "gc-steward-xdist")
+
+
+def pytest_unconfigure(config: pytest.Config) -> None:
+    steward = config.stash.get(_STASH, None)
+    if steward is not None and steward.started:
+        steward.stop()
+
+
+def pytest_sessionfinish(session: pytest.Session) -> None:
+    config = session.config
+    steward = config.stash.get(_STASH, None)
+    if steward is None or not steward.active:
+        return
+    if hasattr(config, "workerinput"):  # xdist worker: ship stats to controller
+        config.workeroutput[_KEY] = steward.stats()
+
+
+class _XdistController:
+    def __init__(self, config: pytest.Config) -> None:
+        self.config = config
+
+    @pytest.hookimpl(optionalhook=True)
+    def pytest_testnodedown(self, node, error) -> None:
+        stats = getattr(node, "workeroutput", {}).get(_KEY)
+        if stats:
+            self.config.stash[_WORKERS][node.gateway.id] = stats
+
+
+_STASH = pytest.StashKey[Steward]()
+_WORKERS = pytest.StashKey[dict]()
+
+
+def _merge(stats: list[dict[str, Any]]) -> dict[str, Counter]:
+    merged = {"types": Counter(), "tests_top": Counter(), "modules": Counter()}
+    for s in stats:
+        for key in merged:
+            merged[key].update(s.get(key, {}))
+    return merged
+
+
+def _line(name: str, s: dict[str, Any]) -> str:
+    auto = ", ".join(f"gen{g} {n}" for g, n in s["auto"].items()) or "none"
+    rss = "?"
+    if s["rss_start_mb"] is not None:
+        rss = f"{s['rss_start_mb']:.0f} -> {s['rss_end_mb']:.0f} MB"
+        rss += f" (peak {s['rss_peak_mb']:.0f})"
+    return (
+        f"{name}: {s['tests']} tests, RSS {rss}; forced {s['forced']}x "
+        f"({s['forced_seconds']:.2f} s, {s['forced_objects']} objects); "
+        f"automatic {auto} ({s['auto_seconds']:.2f} s, "
+        f"{s['auto_objects']} objects); frozen {s['frozen']}"
+    )
+
+
+def pytest_terminal_summary(terminalreporter, exitstatus, config: pytest.Config):
+    steward = config.stash.get(_STASH, None)
+    if steward is None or not steward.active or hasattr(config, "workerinput"):
+        return
+    workers = config.stash.get(_WORKERS, {})
+    per_process = (
+        dict(sorted(workers.items())) if workers else {"main": steward.stats()}
+    )
+    tr = terminalreporter
+    tr.write_sep("=", "gc-steward")
+    for name, s in per_process.items():
+        tr.write_line(_line(name, s))
+    if not steward.report_path:
+        return
+    merged = _merge(list(per_process.values()))
+    top = steward.top
+    for title, key in (
+        ("objects reclaimed by the cyclic GC, by type", "types"),
+        ("by test", "tests_top"),
+        ("by module", "modules"),
+    ):
+        tr.write_line("")
+        tr.write_line(f"{title} (top {top}):")
+        for name, count in merged[key].most_common(top):
+            tr.write_line(f"  {count:>10}  {name}")
+    report = {
+        "processes": per_process,
+        "merged": {k: dict(v.most_common()) for k, v in merged.items()},
+    }
+    path = Path(steward.report_path)
+    path.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n")
+    tr.write_line("")
+    tr.write_line(f"gc-steward report written to {path}")

pytest_gc_steward-0.1.0/src/pytest_gc_steward/rss.py

@@ -0,0 +1,47 @@
+"""Current resident set size of this process, in megabytes."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_PAGE = os.sysconf("SC_PAGE_SIZE") if hasattr(os, "sysconf") else 4096
+
+
+def _linux() -> float | None:
+    try:
+        with open("/proc/self/statm", "rb") as f:
+            return int(f.read().split()[1]) * _PAGE / 1048576
+    except (OSError, ValueError, IndexError):
+        return None
+
+
+def _psutil() -> float | None:
+    try:
+        import psutil
+    except ImportError:
+        return None
+    return psutil.Process().memory_info().rss / 1048576
+
+
+def _peak() -> float | None:
+    """Peak RSS: a last resort; it never goes down."""
+    try:
+        import resource
+    except ImportError:
+        return None
+    peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    # Linux reports KiB, macOS bytes.
+    return peak / (1048576 if sys.platform == "darwin" else 1024)
+
+
+def current_rss_mb() -> float | None:
+    """Best available measure of the current RSS, or ``None`` if unknown."""
+    if sys.platform.startswith("linux"):
+        value = _linux()
+        if value is not None:
+            return value
+    value = _psutil()
+    if value is not None:
+        return value
+    return _peak()

pytest_gc_steward-0.1.0/tests/test_plugin.py

@@ -0,0 +1,129 @@
+import json
+
+import pytest
+
+CYCLES = """
+import gc
+
+class Leaky:
+    def __init__(self):
+        self.me = self
+        self.payload = [object() for _ in range(10)]
+
+def make():
+    for _ in range(50):
+        Leaky()
+"""
+
+
+def test_inactive_by_default(pytester):
+    pytester.makepyfile("def test_a():\n    pass\n")
+    result = pytester.runpytest()
+    result.assert_outcomes(passed=1)
+    result.stdout.no_fnmatch_line("*= gc-steward =*")
+
+
+def test_freeze_moves_startup_objects_to_permanent_generation(pytester):
+    pytester.makepyfile(
+        """
+        import gc
+
+        def test_frozen():
+            assert gc.get_freeze_count() > 0
+        """
+    )
+    result = pytester.runpytest("--gc-freeze")
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(["*gc-steward*", "main: 1 tests*frozen [1-9]*"])
+
+
+def test_gc_every_forces_collections(pytester):
+    pytester.makepyfile("\n".join(f"def test_{i}():\n    pass\n" for i in range(10)))
+    result = pytester.runpytest("--gc-every", "3")
+    result.assert_outcomes(passed=10)
+    result.stdout.fnmatch_lines(["main: 10 tests*forced 3x*"])
+
+
+def test_ini_options(pytester):
+    pytester.makeini("[pytest]\ngc_steward_every = 2\n")
+    pytester.makepyfile("\n".join(f"def test_{i}():\n    pass\n" for i in range(4)))
+    result = pytester.runpytest()
+    result.stdout.fnmatch_lines(["main: 4 tests*forced 2x*"])
+
+
+def test_cli_overrides_ini(pytester):
+    pytester.makeini("[pytest]\ngc_steward_every = 2\n")
+    pytester.makepyfile("\n".join(f"def test_{i}():\n    pass\n" for i in range(4)))
+    result = pytester.runpytest("--gc-every", "4")
+    result.stdout.fnmatch_lines(["main: 4 tests*forced 1x*"])
+
+
+def test_disable_turns_off_automatic_gc_during_tests_only(pytester):
+    pytester.makepyfile(
+        """
+        import gc
+
+        def test_off():
+            assert not gc.isenabled()
+        """
+    )
+    result = pytester.runpytest("--gc-disable", "--gc-every", "1")
+    result.assert_outcomes(passed=1)
+
+
+def test_rss_growth_triggers_collection(pytester):
+    pytester.makepyfile(
+        """
+        import gc
+
+        keep = []
+
+        def test_grow():
+            keep.append(bytearray(64 * 1024 * 1024))
+
+        def test_after():
+            pass
+        """
+    )
+    result = pytester.runpytest_subprocess("--gc-rss-growth", "32")
+    result.assert_outcomes(passed=2)
+    result.stdout.fnmatch_lines(["main: 2 tests*forced [1-9]x*"])
+
+
+def test_report_counts_cycle_types_per_test(pytester):
+    pytester.makepyfile(
+        test_cycles=CYCLES
+        + """
+def test_leaks():
+    make()
+
+def test_clean():
+    [object() for _ in range(100)]
+"""
+    )
+    report = pytester.path / "gc.json"
+    result = pytester.runpytest("--gc-report", str(report))
+    result.assert_outcomes(passed=2)
+    result.stdout.fnmatch_lines(
+        ["*objects reclaimed by the cyclic GC, by type*", "*test_cycles.Leaky*"]
+    )
+    data = json.loads(report.read_text())
+    merged = data["merged"]
+    assert merged["types"]["test_cycles.Leaky"] == 50
+    assert "test_cycles.py::test_leaks" in merged["tests_top"]
+    assert "test_cycles.py::test_clean" not in merged["tests_top"]
+
+
+def test_xdist_workers_are_aggregated(pytester):
+    pytest.importorskip("xdist")
+    pytester.makepyfile(
+        test_cycles=CYCLES
+        + "\n".join(f"\ndef test_{i}():\n    make()\n" for i in range(6))
+    )
+    report = pytester.path / "gc.json"
+    result = pytester.runpytest("-n", "2", "--gc-report", str(report))
+    result.assert_outcomes(passed=6)
+    result.stdout.fnmatch_lines(["gw0: * tests*", "gw1: * tests*"])
+    data = json.loads(report.read_text())
+    assert set(data["processes"]) == {"gw0", "gw1"}
+    assert data["merged"]["types"]["test_cycles.Leaky"] == 300