pytest-shm 0.1.0__tar.gz

pytest_shm-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+src/pytest_shm/_version.py
+*.py[cod]
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Tools
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

pytest_shm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bas Nijholt
+
+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_shm-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: pytest-shm
+Version: 0.1.0
+Summary: Put pytest's temporary files on the /dev/shm tmpfs so fsync-heavy suites stop waiting on the disk
+Project-URL: Homepage, https://github.com/basnijholt/pytest-shm
+Project-URL: Repository, https://github.com/basnijholt/pytest-shm
+Project-URL: Documentation, https://github.com/basnijholt/pytest-shm#readme
+Project-URL: Issues, https://github.com/basnijholt/pytest-shm/issues
+Project-URL: Changelog, https://github.com/basnijholt/pytest-shm/releases
+Author-email: Bas Nijholt <bas@nijho.lt>
+Maintainer-email: Bas Nijholt <bas@nijho.lt>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fsync,performance,pytest,shm,tempfile,testing,tmpfs,xdist
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pytest>=8.4
+Description-Content-Type: text/markdown
+
+# pytest-shm
+
+[![PyPI](https://img.shields.io/pypi/v/pytest-shm)](https://pypi.org/project/pytest-shm/)
+[![Python](https://img.shields.io/pypi/pyversions/pytest-shm)](https://pypi.org/project/pytest-shm/)
+[![License](https://img.shields.io/github/license/basnijholt/pytest-shm)](LICENSE)
+[![CI](https://github.com/basnijholt/pytest-shm/actions/workflows/ci.yml/badge.svg)](https://github.com/basnijholt/pytest-shm/actions/workflows/ci.yml)
+
+A pytest plugin that puts your test suite's temporary files on the `/dev/shm` tmpfs, so tests that fsync stop waiting on the disk.
+
+> [!NOTE]
+> Install it and run pytest.
+> On Linux it moves the temp root to `/dev/shm` when that is safe, keeps stray `tempfile` output from collection on inside pytest's base directory, and frees that directory when the session passes.
+> Everywhere else, and whenever you export `TMPDIR`, it leaves the temp root alone.
+
+## Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Why](#why)
+- [Installation](#installation)
+- [How it works](#how-it-works)
+- [When it stays off](#when-it-stays-off)
+- [Configuration](#configuration)
+- [Caveats](#caveats)
+- [Development](#development)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Why
+
+SQLite commits, atomic file replacement, and anything else that promises durability call `fsync`, and on a real disk each call waits for the device.
+A suite that exercises durable storage can spend most of its time there.
+tmpfs lives in memory, so `fsync` returns immediately.
+
+In [MindRoom](https://github.com/mindroom-ai/mindroom)'s suite of about 26,000 tests, summed test time on a 32-worker NVMe machine fell from 5236 s to 1426 s, and the GitHub Actions test step fell from about 16 to 12-15 minutes.
+
+No durability test can observe the difference.
+Such tests simulate a crashed process, and a crashed process never needed its writes to leave the page cache.
+The [caveats](#caveats) list the differences other tests can see.
+
+## Installation
+
+```bash
+uv add --dev pytest-shm
+# or
+pip install pytest-shm
+```
+
+It needs Python 3.10+ and pytest 8.4+, and pytest loads it automatically.
+The report header tells you whether it is active:
+
+```text
+shm: temp root /dev/shm
+```
+
+or why it is not:
+
+```text
+shm: off, TMPDIR is exported
+```
+
+## How it works
+
+1. **Temp root.** Before any `conftest.py` is imported, the plugin sets `TMPDIR=/dev/shm`, so `tmp_path`, `tmp_path_factory`, and every `tempfile` call land in memory.
+2. **Containment.** Tests and the code they drive often call `tempfile.mkdtemp()` without removing the result. On disk that clutters `/tmp`; on tmpfs it would hold memory until reboot. When the session starts, before collection, the plugin points `TMPDIR` at `<basetemp>/shm-tmp`, so that output lives and dies with pytest's own base directory.
+3. **Cleanup.** pytest keeps the last three sessions' base directories. When a session passes, collects no tests, or stops at a usage error, the plugin deletes its base directory right away instead of holding it in memory. A failing session keeps everything for inspection.
+4. **pytest-xdist.** Each worker owns `<basetemp>/popen-gwN` and cleans up after itself, so a failing run keeps only the directories of workers that saw a failure. A `--basetemp` you pass yourself is never deleted, with or without xdist.
+
+Deleting per test is deliberately not offered: pytest would then reuse the freed directory names, and caches keyed by path would hand the next test the previous one's state.
+
+## When it stays off
+
+The plugin leaves the temp root alone, and says why in the report header, when any of these holds:
+
+| Condition | Header |
+| --- | --- |
+| Not running on Linux | `shm: off, not Linux` |
+| `TMPDIR`, `TEMP`, or `TMP` is exported | `shm: off, TMPDIR is exported` |
+| `--basetemp` or `PYTEST_DEBUG_TEMPROOT` puts pytest's base directory outside `/dev/shm` | `shm: off, --basetemp is outside /dev/shm` |
+| pytest's `tmpdir` plugin is disabled (`-p no:tmpdir`) | `shm: off, pytest's tmpdir plugin is disabled` |
+| `/dev/shm` is missing, or not writable and searchable | `shm: off, /dev/shm is missing or not writable` |
+| `/dev/shm` is mounted `noexec` (Docker's default), which would break tests that run scripts they write | `shm: off, /dev/shm is mounted noexec` |
+| `/dev/shm` has less free space than `shm_min_free_gib` (Docker's default is 64 MiB) | `shm: off, /dev/shm has 0.1 GiB free, below shm_min_free_gib = 1` |
+
+To turn it off explicitly, export `TMPDIR` to the directory you want, or pass `-o shm_min_free_gib=inf`.
+`-p no:shm` works too, but pytest then warns about the unknown `shm_min_free_gib` option if you configured it, and `--strict-config` makes that an error.
+
+If you export `TMPDIR=/dev/shm` yourself, the plugin still contains and cleans up temporary files, as long as pytest's base directory is on `/dev/shm` too.
+
+## Configuration
+
+One ini option sets how much free space `/dev/shm` needs before the plugin uses it:
+
+```toml
+[tool.pytest.ini_options]
+shm_min_free_gib = 4
+```
+
+The default is `1`.
+Set it above your suite's peak usage, which you can watch with `df -h /dev/shm` during a run.
+Override it for one run with `-o shm_min_free_gib=8`.
+
+## Caveats
+
+- **Only output during the session is contained.** Temporary files created before the session starts (while the initial `conftest.py` files are imported, in `pytest_configure`, or in other plugins' `pytest_sessionstart` hooks) or after it ends (`pytest_terminal_summary`, `pytest_unconfigure`) land directly in `/dev/shm` and stay there until reboot. Create them in fixtures, or remove them yourself.
+- **Caches under the temp root become per-session.** Libraries that cache downloads under `tempfile.gettempdir()` see the contained directory, which the plugin frees after the session. Pin such caches in your root `conftest.py`, where `tempfile.gettempdir()` is still `/dev/shm`. For tiktoken:
+
+  ```python
+  if "TIKTOKEN_CACHE_DIR" not in os.environ and "DATA_GYM_CACHE_DIR" not in os.environ:
+      os.environ["TIKTOKEN_CACHE_DIR"] = str(Path(tempfile.gettempdir()) / "data-gym-cache")
+  ```
+
+- **Temp files live on another filesystem.** `os.rename` or `os.replace` from a temporary file into your project fails with `EXDEV`, as it already does wherever `/tmp` is tmpfs.
+- **Paths get longer.** `/dev/shm/pytest-of-<user>/pytest-N/popen-gwN/shm-tmp/tmpXXXXXXXX` is much longer than `/tmp/tmpXXXXXXXX`, which matters for the 107-byte limit on `AF_UNIX` socket paths.
+- **Files use RAM.** Everything a session writes counts against memory until the session ends. Base directories of failing sessions stay until the machine reboots or later failing sessions push them out of pytest's retention of three numbered directories; passing sessions reuse the freed number instead of advancing it.
+- **Plugin autoloading.** With `PYTEST_DISABLE_PLUGIN_AUTOLOAD` set, pass `-p shm` to load the plugin.
+
+## Development
+
+```bash
+just install  # uv sync --dev
+just test     # uv run pytest -n auto
+just lint     # ruff, mypy, ty
+```
+
+The tests run real pytest sessions in subprocesses with `pytester` and inspect what they leave behind on `/dev/shm`.
+
+## License
+
+MIT

pytest_shm-0.1.0/README.md

@@ -0,0 +1,132 @@
+# pytest-shm
+
+[![PyPI](https://img.shields.io/pypi/v/pytest-shm)](https://pypi.org/project/pytest-shm/)
+[![Python](https://img.shields.io/pypi/pyversions/pytest-shm)](https://pypi.org/project/pytest-shm/)
+[![License](https://img.shields.io/github/license/basnijholt/pytest-shm)](LICENSE)
+[![CI](https://github.com/basnijholt/pytest-shm/actions/workflows/ci.yml/badge.svg)](https://github.com/basnijholt/pytest-shm/actions/workflows/ci.yml)
+
+A pytest plugin that puts your test suite's temporary files on the `/dev/shm` tmpfs, so tests that fsync stop waiting on the disk.
+
+> [!NOTE]
+> Install it and run pytest.
+> On Linux it moves the temp root to `/dev/shm` when that is safe, keeps stray `tempfile` output from collection on inside pytest's base directory, and frees that directory when the session passes.
+> Everywhere else, and whenever you export `TMPDIR`, it leaves the temp root alone.
+
+## Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Why](#why)
+- [Installation](#installation)
+- [How it works](#how-it-works)
+- [When it stays off](#when-it-stays-off)
+- [Configuration](#configuration)
+- [Caveats](#caveats)
+- [Development](#development)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Why
+
+SQLite commits, atomic file replacement, and anything else that promises durability call `fsync`, and on a real disk each call waits for the device.
+A suite that exercises durable storage can spend most of its time there.
+tmpfs lives in memory, so `fsync` returns immediately.
+
+In [MindRoom](https://github.com/mindroom-ai/mindroom)'s suite of about 26,000 tests, summed test time on a 32-worker NVMe machine fell from 5236 s to 1426 s, and the GitHub Actions test step fell from about 16 to 12-15 minutes.
+
+No durability test can observe the difference.
+Such tests simulate a crashed process, and a crashed process never needed its writes to leave the page cache.
+The [caveats](#caveats) list the differences other tests can see.
+
+## Installation
+
+```bash
+uv add --dev pytest-shm
+# or
+pip install pytest-shm
+```
+
+It needs Python 3.10+ and pytest 8.4+, and pytest loads it automatically.
+The report header tells you whether it is active:
+
+```text
+shm: temp root /dev/shm
+```
+
+or why it is not:
+
+```text
+shm: off, TMPDIR is exported
+```
+
+## How it works
+
+1. **Temp root.** Before any `conftest.py` is imported, the plugin sets `TMPDIR=/dev/shm`, so `tmp_path`, `tmp_path_factory`, and every `tempfile` call land in memory.
+2. **Containment.** Tests and the code they drive often call `tempfile.mkdtemp()` without removing the result. On disk that clutters `/tmp`; on tmpfs it would hold memory until reboot. When the session starts, before collection, the plugin points `TMPDIR` at `<basetemp>/shm-tmp`, so that output lives and dies with pytest's own base directory.
+3. **Cleanup.** pytest keeps the last three sessions' base directories. When a session passes, collects no tests, or stops at a usage error, the plugin deletes its base directory right away instead of holding it in memory. A failing session keeps everything for inspection.
+4. **pytest-xdist.** Each worker owns `<basetemp>/popen-gwN` and cleans up after itself, so a failing run keeps only the directories of workers that saw a failure. A `--basetemp` you pass yourself is never deleted, with or without xdist.
+
+Deleting per test is deliberately not offered: pytest would then reuse the freed directory names, and caches keyed by path would hand the next test the previous one's state.
+
+## When it stays off
+
+The plugin leaves the temp root alone, and says why in the report header, when any of these holds:
+
+| Condition | Header |
+| --- | --- |
+| Not running on Linux | `shm: off, not Linux` |
+| `TMPDIR`, `TEMP`, or `TMP` is exported | `shm: off, TMPDIR is exported` |
+| `--basetemp` or `PYTEST_DEBUG_TEMPROOT` puts pytest's base directory outside `/dev/shm` | `shm: off, --basetemp is outside /dev/shm` |
+| pytest's `tmpdir` plugin is disabled (`-p no:tmpdir`) | `shm: off, pytest's tmpdir plugin is disabled` |
+| `/dev/shm` is missing, or not writable and searchable | `shm: off, /dev/shm is missing or not writable` |
+| `/dev/shm` is mounted `noexec` (Docker's default), which would break tests that run scripts they write | `shm: off, /dev/shm is mounted noexec` |
+| `/dev/shm` has less free space than `shm_min_free_gib` (Docker's default is 64 MiB) | `shm: off, /dev/shm has 0.1 GiB free, below shm_min_free_gib = 1` |
+
+To turn it off explicitly, export `TMPDIR` to the directory you want, or pass `-o shm_min_free_gib=inf`.
+`-p no:shm` works too, but pytest then warns about the unknown `shm_min_free_gib` option if you configured it, and `--strict-config` makes that an error.
+
+If you export `TMPDIR=/dev/shm` yourself, the plugin still contains and cleans up temporary files, as long as pytest's base directory is on `/dev/shm` too.
+
+## Configuration
+
+One ini option sets how much free space `/dev/shm` needs before the plugin uses it:
+
+```toml
+[tool.pytest.ini_options]
+shm_min_free_gib = 4
+```
+
+The default is `1`.
+Set it above your suite's peak usage, which you can watch with `df -h /dev/shm` during a run.
+Override it for one run with `-o shm_min_free_gib=8`.
+
+## Caveats
+
+- **Only output during the session is contained.** Temporary files created before the session starts (while the initial `conftest.py` files are imported, in `pytest_configure`, or in other plugins' `pytest_sessionstart` hooks) or after it ends (`pytest_terminal_summary`, `pytest_unconfigure`) land directly in `/dev/shm` and stay there until reboot. Create them in fixtures, or remove them yourself.
+- **Caches under the temp root become per-session.** Libraries that cache downloads under `tempfile.gettempdir()` see the contained directory, which the plugin frees after the session. Pin such caches in your root `conftest.py`, where `tempfile.gettempdir()` is still `/dev/shm`. For tiktoken:
+
+  ```python
+  if "TIKTOKEN_CACHE_DIR" not in os.environ and "DATA_GYM_CACHE_DIR" not in os.environ:
+      os.environ["TIKTOKEN_CACHE_DIR"] = str(Path(tempfile.gettempdir()) / "data-gym-cache")
+  ```
+
+- **Temp files live on another filesystem.** `os.rename` or `os.replace` from a temporary file into your project fails with `EXDEV`, as it already does wherever `/tmp` is tmpfs.
+- **Paths get longer.** `/dev/shm/pytest-of-<user>/pytest-N/popen-gwN/shm-tmp/tmpXXXXXXXX` is much longer than `/tmp/tmpXXXXXXXX`, which matters for the 107-byte limit on `AF_UNIX` socket paths.
+- **Files use RAM.** Everything a session writes counts against memory until the session ends. Base directories of failing sessions stay until the machine reboots or later failing sessions push them out of pytest's retention of three numbered directories; passing sessions reuse the freed number instead of advancing it.
+- **Plugin autoloading.** With `PYTEST_DISABLE_PLUGIN_AUTOLOAD` set, pass `-p shm` to load the plugin.
+
+## Development
+
+```bash
+just install  # uv sync --dev
+just test     # uv run pytest -n auto
+just lint     # ruff, mypy, ty
+```
+
+The tests run real pytest sessions in subprocesses with `pytester` and inspect what they leave behind on `/dev/shm`.
+
+## License
+
+MIT

pytest_shm-0.1.0/pyproject.toml

@@ -0,0 +1,119 @@
+[project]
+name = "pytest-shm"
+dynamic = ["version"]
+description = "Put pytest's temporary files on the /dev/shm tmpfs so fsync-heavy suites stop waiting on the disk"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Bas Nijholt", email = "bas@nijho.lt" }
+]
+maintainers = [
+    { name = "Bas Nijholt", email = "bas@nijho.lt" }
+]
+requires-python = ">=3.10"
+keywords = [
+    "pytest",
+    "tmpfs",
+    "shm",
+    "fsync",
+    "tempfile",
+    "xdist",
+    "testing",
+    "performance",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "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",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pytest>=8.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/basnijholt/pytest-shm"
+Repository = "https://github.com/basnijholt/pytest-shm"
+Documentation = "https://github.com/basnijholt/pytest-shm#readme"
+Issues = "https://github.com/basnijholt/pytest-shm/issues"
+Changelog = "https://github.com/basnijholt/pytest-shm/releases"
+
+[project.entry-points.pytest11]
+shm = "pytest_shm.plugin"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/pytest_shm/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pytest_shm"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "CPY001",  # no copyright headers; LICENSE covers the project
+    "D203",    # incompatible with D211
+    "D213",    # incompatible with D212
+    "E501",    # formatter handles line length
+    "COM812",  # avoid formatter conflicts
+    "ISC001",  # avoid formatter conflicts
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "S108", "PLR2004", "D103", "ARG001"]  # relaxed for tests
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[[tool.mypy.overrides]]
+module = "pytest_shm._version"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "xdist.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.ty.src]
+exclude = [
+    "src/pytest_shm/_version.py",  # Generated at build time
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.0",
+    "pre-commit>=4.5.0",
+    "pytest>=9.0.2",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.16.0",
+    "ty>=0.0.1a13",
+]

pytest_shm-0.1.0/src/pytest_shm/__init__.py

@@ -0,0 +1,9 @@
+"""Put pytest's temporary files on the `/dev/shm` tmpfs."""
+
+try:
+    from pytest_shm._version import __version__, __version_tuple__
+except ImportError:
+    __version__ = "0.0.0"
+    __version_tuple__ = (0, 0, 0)
+
+__all__ = ["__version__", "__version_tuple__"]

pytest_shm-0.1.0/src/pytest_shm/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

pytest_shm-0.1.0/src/pytest_shm/plugin.py

@@ -0,0 +1,184 @@
+"""Run pytest with its temporary files on the `/dev/shm` tmpfs."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Mapping
+
+    from xdist.workermanage import WorkerController
+
+SHM = Path("/dev/shm")  # noqa: S108
+_TEMP_ROOT_VARIABLES = ("TMPDIR", "TEMP", "TMP")
+_MIN_FREE_INI = "shm_min_free_gib"
+_CONTAINED_NAME = "shm-tmp"
+_OWNS_BASETEMP_KEY = "shm_owns_basetemp"
+_OFF_REASON = pytest.StashKey[str]()
+_CONTAINED = pytest.StashKey[bool]()
+_OWNED_BASETEMP = pytest.StashKey[Path]()
+_NOTHING_TO_INSPECT = (
+    pytest.ExitCode.OK,
+    pytest.ExitCode.NO_TESTS_COLLECTED,
+    pytest.ExitCode.USAGE_ERROR,
+)
+
+
+def off_reason(
+    min_free_gib: float,
+    environ: Mapping[str, str],
+    basetemp: str | None = None,
+) -> str | None:
+    """Return why the temp root should stay where it is, or `None` to move it to `/dev/shm`.
+
+    `basetemp` is the caller's `--basetemp`, which, like `PYTEST_DEBUG_TEMPROOT`,
+    decides where pytest's base directory goes regardless of the temp root.
+    """
+    if sys.platform != "linux":
+        return "not Linux"
+    for name in _TEMP_ROOT_VARIABLES:
+        if name in environ:
+            return f"{name} is exported"
+    base_source, base = (
+        ("--basetemp", basetemp)
+        if basetemp
+        else ("PYTEST_DEBUG_TEMPROOT", environ.get("PYTEST_DEBUG_TEMPROOT"))
+    )
+    if base and not Path(base).resolve().is_relative_to(SHM.resolve()):
+        return f"{base_source} is outside {SHM}"
+    return _shm_off_reason(min_free_gib)
+
+
+def _shm_off_reason(min_free_gib: float) -> str | None:
+    """Return why `/dev/shm` itself cannot hold the session's files, or `None`."""
+    if not SHM.is_dir() or not os.access(SHM, os.W_OK | os.X_OK):
+        return f"{SHM} is missing or not writable"
+    if os.statvfs(SHM).f_flag & os.ST_NOEXEC:
+        return f"{SHM} is mounted noexec"
+    free_gib = shutil.disk_usage(SHM).free / 2**30
+    if free_gib < min_free_gib:
+        return f"{SHM} has {free_gib:.1f} GiB free, below {_MIN_FREE_INI} = {min_free_gib:g}"
+    return None
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Register the free-space threshold."""
+    parser.addini(
+        _MIN_FREE_INI,
+        f"Minimum free GiB {SHM} needs before temporary files move there (default: 1).",
+        type="float",
+        default=1.0,
+    )
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_load_initial_conftests(early_config: pytest.Config) -> None:
+    """Point the temp root at `/dev/shm` before any `conftest.py` can read it."""
+    reason = off_reason(
+        early_config.getini(_MIN_FREE_INI),
+        os.environ,
+        # pytest's tmpdir plugin registers --basetemp, so it is missing when that plugin is.
+        getattr(early_config.known_args_namespace, "basetemp", None),
+    )
+    if reason is None and early_config.pluginmanager.is_blocked("tmpdir"):
+        reason = "pytest's tmpdir plugin is disabled"
+    if reason is not None:
+        early_config.stash[_OFF_REASON] = reason
+        return
+    previous_tempdir = tempfile.tempdir
+    os.environ["TMPDIR"] = str(SHM)
+    tempfile.tempdir = None
+
+    def restore() -> None:
+        # pytest runs cleanups even when the session never configures, such as on a usage error.
+        os.environ.pop("TMPDIR", None)
+        tempfile.tempdir = previous_tempdir
+
+    early_config.add_cleanup(restore)
+
+
+def pytest_report_header(config: pytest.Config) -> str:
+    """Say where temporary files go, or why they stay put."""
+    temp_root = tempfile.gettempdir()
+    if Path(temp_root) == SHM:
+        return f"shm: temp root {SHM}"
+    return f"shm: off, {config.stash.get(_OFF_REASON, f'temp root is {temp_root}')}"
+
+
+def _pytest_chose_basetemp(config: pytest.Config) -> bool:
+    """Tell whether pytest picked the base directory rather than the caller."""
+    workerinput = getattr(config, "workerinput", None)
+    if workerinput is not None:
+        return bool(workerinput.get(_OWNS_BASETEMP_KEY, False))
+    return config.option.basetemp is None
+
+
+@pytest.hookimpl(optionalhook=True)
+def pytest_configure_node(node: WorkerController) -> None:
+    """Tell each xdist worker whether its base directory is pytest's own or the caller's.
+
+    xdist hands every worker its directory as `--basetemp`, so only the controller
+    still knows whether the caller chose one, which must outlive a passing session.
+    """
+    node.workerinput[_OWNS_BASETEMP_KEY] = node.config.option.basetemp is None
+
+
+@pytest.hookimpl(wrapper=True)
+def pytest_sessionstart(session: pytest.Session) -> Generator[None]:
+    """Keep bare `tempfile` output inside pytest's base directory on `/dev/shm`.
+
+    Tests and the code they drive often call `tempfile.mkdtemp()` without removing
+    the result. On disk that only clutters `/tmp`, but on tmpfs it would hold memory
+    until reboot, so from collection on it joins the `tmp_path` directories that
+    `pytest_sessionfinish` frees.
+
+    This runs after every other `pytest_sessionstart`, once xdist has started its
+    workers, so they inherit `/dev/shm` itself rather than this process's directory.
+    Workers never switch the temp root, so this checks where it is rather than
+    whether this process moved it. A worker xdist starts later to replace a crashed
+    one inherits the controller's directory instead, and its files are freed with it.
+    """
+    yield
+    config = session.config
+    # pytest's tmpdir plugin sets this in pytest_configure, and xdist reads it the same way.
+    factory: pytest.TempPathFactory | None = getattr(config, "_tmp_path_factory", None)
+    if factory is None or Path(tempfile.gettempdir()) != SHM:
+        return
+    basetemp = factory.getbasetemp()
+    if not basetemp.is_relative_to(SHM.resolve()):
+        # Containing would move files the caller sent to /dev/shm onto disk.
+        return
+    if _pytest_chose_basetemp(config):
+        config.stash[_OWNED_BASETEMP] = basetemp
+    contained = basetemp / _CONTAINED_NAME
+    contained.mkdir()
+    os.environ["TMPDIR"] = str(contained)
+    tempfile.tempdir = str(contained)
+    config.stash[_CONTAINED] = True
+
+
+@pytest.hookimpl(trylast=True)
+def pytest_sessionfinish(session: pytest.Session, exitstatus: int | pytest.ExitCode) -> None:
+    """Hand back `/dev/shm`, and free the base directory of a session nobody needs to inspect.
+
+    pytest keeps the last three sessions' directories, which on tmpfs pins memory
+    until they are pruned. A session that passed, collected no tests, or stopped at a
+    usage error leaves nothing worth keeping. Each xdist worker owns its own base
+    directory, so a failing session keeps only the workers that saw a failure.
+    Deleting per test is not an option: pytest then reuses the freed names, and
+    caches keyed by path hand the next test the previous one's state.
+    """
+    config = session.config
+    if config.stash.get(_CONTAINED, False):
+        os.environ["TMPDIR"] = str(SHM)
+        tempfile.tempdir = None
+    basetemp = config.stash.get(_OWNED_BASETEMP, None)
+    if basetemp is not None and exitstatus in _NOTHING_TO_INSPECT:
+        shutil.rmtree(basetemp, ignore_errors=True)

pytest_shm-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for pytest-shm."""

pytest_shm-0.1.0/tests/conftest.py

@@ -0,0 +1,3 @@
+"""Shared test configuration."""
+
+pytest_plugins = ["pytester"]

pytest_shm-0.1.0/tests/test_plugin.py

@@ -0,0 +1,403 @@
+"""Behavior of the pytest-shm plugin, observed through real pytest sessions."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pytest_shm.plugin import SHM, off_reason
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+_SHM_OFF = off_reason(1, {})
+needs_shm = pytest.mark.skipif(_SHM_OFF is not None, reason=f"{SHM} is unusable: {_SHM_OFF}")
+
+_TEMP_ROOT_IS_NOT_SHM = """
+import tempfile
+from pathlib import Path
+
+def test_temp_root():
+    temp_root = Path(tempfile.gettempdir()).resolve()
+    assert not temp_root.is_relative_to(Path("/dev/shm").resolve())
+"""
+
+
+@pytest.fixture
+def temproot(pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch) -> Iterator[Path]:
+    """Give inner sessions no exported temp root and their own pytest temp root on /dev/shm.
+
+    Depending on `pytester` makes this override the `PYTEST_DEBUG_TEMPROOT` it sets.
+    """
+    for name in ("TMPDIR", "TEMP", "TMP"):
+        monkeypatch.delenv(name, raising=False)
+    root = Path(tempfile.mkdtemp(dir=SHM, prefix="pytest-shm-test-"))
+    monkeypatch.setenv("PYTEST_DEBUG_TEMPROOT", str(root))
+    yield root
+    shutil.rmtree(root)
+
+
+@pytest.fixture
+def disk_dir() -> Iterator[Path]:
+    """Give a directory outside /dev/shm."""
+    path = Path(tempfile.mkdtemp(dir="/var/tmp", prefix="pytest-shm-test-"))
+    yield path
+    shutil.rmtree(path)
+
+
+def run_pytest(pytester: pytest.Pytester, *args: str) -> pytest.RunResult:
+    """Run pytest in a subprocess without the `--basetemp` that `runpytest_subprocess` forces."""
+    return pytester.run(sys.executable, "-m", "pytest", "-p", "no:cacheprovider", *args, timeout=60)
+
+
+def test_plugin_is_registered(pytestconfig: pytest.Config) -> None:
+    assert pytestconfig.pluginmanager.has_plugin("shm")
+
+
+@needs_shm
+def test_moves_the_temp_root_to_shm_before_conftests_load(
+    pytester: pytest.Pytester, temproot: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # Let pytest derive its base directory from the switched TMPDIR, as it does for users.
+    monkeypatch.delenv("PYTEST_DEBUG_TEMPROOT")
+    pytester.makeconftest(
+        """
+        import tempfile
+
+        IMPORT_TIME_TEMP_ROOT = tempfile.gettempdir()
+
+        def pytest_report_header():
+            return f"conftest saw {IMPORT_TIME_TEMP_ROOT}"
+        """
+    )
+    pytester.makepyfile(
+        """
+        import tempfile
+        from pathlib import Path
+
+        def test_temp_root(tmp_path_factory):
+            shm = Path("/dev/shm").resolve()
+            assert Path(tempfile.gettempdir()).is_relative_to(shm)
+            assert tmp_path_factory.getbasetemp().is_relative_to(shm)
+        """
+    )
+    result = run_pytest(pytester)
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(["shm: temp root /dev/shm", "conftest saw /dev/shm"])
+
+
+@needs_shm
+def test_exported_temp_root_wins(
+    pytester: pytest.Pytester, temproot: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    chosen = pytester.mkdir("chosen")
+    monkeypatch.setenv("TMPDIR", str(chosen))
+    pytester.makepyfile(
+        f"""
+        import tempfile
+
+        def test_temp_root():
+            assert tempfile.gettempdir() == {str(chosen)!r}
+        """
+    )
+    result = run_pytest(pytester)
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(["shm: off, TMPDIR is exported"])
+
+
+@needs_shm
+def test_base_directory_chosen_outside_shm_leaves_the_temp_root_alone(
+    pytester: pytest.Pytester, temproot: Path, disk_dir: Path
+) -> None:
+    pytester.makepyfile(_TEMP_ROOT_IS_NOT_SHM)
+    result = run_pytest(pytester, f"--basetemp={disk_dir / 'basetemp'}")
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(["shm: off, --basetemp is outside /dev/shm"])
+
+
+@needs_shm
+def test_debug_temp_root_outside_shm_leaves_the_temp_root_alone(
+    pytester: pytest.Pytester, temproot: Path, disk_dir: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("PYTEST_DEBUG_TEMPROOT", str(disk_dir))
+    pytester.makepyfile(_TEMP_ROOT_IS_NOT_SHM)
+    result = run_pytest(pytester)
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(["shm: off, PYTEST_DEBUG_TEMPROOT is outside /dev/shm"])
+
+
+@needs_shm
+def test_too_little_free_space_leaves_the_temp_root_alone(
+    pytester: pytest.Pytester, temproot: Path
+) -> None:
+    pytester.makepyfile(_TEMP_ROOT_IS_NOT_SHM)
+    result = run_pytest(pytester, "-o", "shm_min_free_gib=1e9")
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(
+        ["shm: off, /dev/shm has * GiB free, below shm_min_free_gib = 1e+09"]
+    )
+
+
+@needs_shm
+@pytest.mark.skipif(
+    int(pytest.__version__.partition(".")[0]) < 9, reason="native [tool.pytest] needs pytest 9"
+)
+def test_threshold_accepts_a_native_toml_number(pytester: pytest.Pytester, temproot: Path) -> None:
+    pytester.makepyprojecttoml("[tool.pytest]\nshm_min_free_gib = 1e9\n")
+    pytester.makepyfile(_TEMP_ROOT_IS_NOT_SHM)
+    result = run_pytest(pytester)
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(
+        ["shm: off, /dev/shm has * GiB free, below shm_min_free_gib = 1e+09"]
+    )
+
+
+@needs_shm
+def test_disabled_plugin_leaves_the_temp_root_alone(
+    pytester: pytest.Pytester, temproot: Path
+) -> None:
+    pytester.makepyfile(_TEMP_ROOT_IS_NOT_SHM)
+    result = run_pytest(pytester, "-p", "no:shm")
+    result.assert_outcomes(passed=1)
+    result.stdout.no_fnmatch_line("shm:*")
+
+
+def test_disabled_tmpdir_plugin_leaves_sessions_working(pytester: pytest.Pytester) -> None:
+    pytester.makepyfile("def test_pass():\n    pass\n")
+    result = run_pytest(pytester, "-p", "no:tmpdir")
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(["shm: off, *"])
+
+
+@needs_shm
+def test_disabled_tmpdir_plugin_turns_the_plugin_off(
+    pytester: pytest.Pytester, temproot: Path
+) -> None:
+    pytester.makepyfile(_TEMP_ROOT_IS_NOT_SHM)
+    result = run_pytest(pytester, "-p", "no:tmpdir")
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(["shm: off, pytest's tmpdir plugin is disabled"])
+
+
+@needs_shm
+def test_in_process_session_restores_the_callers_environment(
+    pytester: pytest.Pytester, temproot: Path, monkeypatch: pytest.MonkeyPatch, disk_dir: Path
+) -> None:
+    monkeypatch.setattr(tempfile, "tempdir", str(disk_dir))
+    pytester.makepyfile("def test_pass():\n    pass\n")
+    pytester.runpytest_inprocess().assert_outcomes(passed=1)
+    assert "TMPDIR" not in os.environ
+    assert tempfile.tempdir == str(disk_dir)
+
+
+@needs_shm
+def test_in_process_usage_error_restores_the_environment(
+    pytester: pytest.Pytester, temproot: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(tempfile, "tempdir", None)
+    result = pytester.runpytest_inprocess("--no-such-flag")
+    assert result.ret == pytest.ExitCode.USAGE_ERROR
+    assert "TMPDIR" not in os.environ
+    assert not Path(tempfile.gettempdir()).is_relative_to(SHM)
+
+
+@needs_shm
+def test_in_process_session_hands_back_an_exported_shm_temp_root(
+    pytester: pytest.Pytester, temproot: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("TMPDIR", str(SHM))
+    monkeypatch.setattr(tempfile, "tempdir", None)
+    pytester.makepyfile(
+        """
+        import tempfile
+
+        def test_contained():
+            assert tempfile.gettempdir() != "/dev/shm"
+        """
+    )
+    pytester.runpytest_inprocess().assert_outcomes(passed=1)
+    assert os.environ["TMPDIR"] == str(SHM)
+    assert tempfile.tempdir is None
+
+
+@needs_shm
+def test_noexec_shm_is_refused(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(os, "statvfs", lambda _path: SimpleNamespace(f_flag=os.ST_NOEXEC))
+    assert off_reason(0, {}) == "/dev/shm is mounted noexec"
+
+
+@pytest.mark.skipif(sys.platform == "linux", reason="checks the report outside Linux")
+def test_stays_off_outside_linux(pytester: pytest.Pytester) -> None:
+    pytester.makepyfile("def test_pass():\n    pass\n")
+    result = run_pytest(pytester)
+    result.assert_outcomes(passed=1)
+    result.stdout.fnmatch_lines(["shm: off, not Linux"])
+
+
+@needs_shm
+def test_bare_tempfile_output_lands_in_the_base_directory_from_collection_on(
+    pytester: pytest.Pytester, temproot: Path
+) -> None:
+    pytester.makepyfile(
+        """
+        import os
+        import tempfile
+        from pathlib import Path
+
+        COLLECTION_TIME_DIRECTORY = Path(tempfile.mkdtemp())
+
+        def test_contained(tmp_path_factory):
+            contained = tmp_path_factory.getbasetemp() / "shm-tmp"
+            assert COLLECTION_TIME_DIRECTORY.parent == contained
+            assert tempfile.gettempdir() == os.environ["TMPDIR"] == str(contained)
+            assert Path(tempfile.mkdtemp()).parent == contained
+        """
+    )
+    run_pytest(pytester).assert_outcomes(passed=1)
+
+
+@needs_shm
+@pytest.mark.parametrize(
+    ("statement", "outcome"),
+    [("pass", "passed"), ("assert False", "failed")],
+    ids=["passing", "failing"],
+)
+def test_only_a_failing_session_keeps_its_base_directory(
+    pytester: pytest.Pytester, temproot: Path, statement: str, outcome: str
+) -> None:
+    pytester.makepyfile(
+        f"""
+        import tempfile
+        from pathlib import Path
+
+        def test_write(tmp_path):
+            (tmp_path / "state").write_text("x")
+            Path(tempfile.mkdtemp(), "state").write_text("x")
+            {statement}
+        """
+    )
+    run_pytest(pytester).assert_outcomes(**{outcome: 1})
+    numbered = list(temproot.glob("pytest-of-*/pytest-[0-9]*"))
+    if outcome == "passed":
+        assert numbered == []
+    else:
+        (basetemp,) = numbered
+        assert list(basetemp.glob("shm-tmp/tmp*/state"))
+
+
+@needs_shm
+@pytest.mark.parametrize("workers", [(), ("-n", "2")], ids=["serial", "xdist"])
+def test_explicit_basetemp_survives_a_passing_session(
+    pytester: pytest.Pytester, temproot: Path, workers: tuple[str, ...]
+) -> None:
+    pytester.makepyfile("def test_write(tmp_path):\n    (tmp_path / 'kept').write_text('x')\n")
+    basetemp = temproot / "chosen"
+    run_pytest(pytester, f"--basetemp={basetemp}", *workers).assert_outcomes(passed=1)
+    assert list(basetemp.rglob("kept"))
+
+
+@needs_shm
+def test_exported_shm_temp_root_with_base_directory_on_disk_is_left_alone(
+    pytester: pytest.Pytester, temproot: Path, disk_dir: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # Containing would move files the caller sent to /dev/shm onto disk.
+    monkeypatch.setenv("TMPDIR", str(SHM))
+    monkeypatch.setenv("PYTEST_DEBUG_TEMPROOT", str(disk_dir))
+    pytester.makepyfile(
+        """
+        import tempfile
+
+        def test_write(tmp_path):
+            assert tempfile.gettempdir() == "/dev/shm"
+            (tmp_path / "kept").write_text("x")
+        """
+    )
+    run_pytest(pytester).assert_outcomes(passed=1)
+    assert list(disk_dir.glob("pytest-of-*/pytest-[0-9]*/test_write0/kept"))
+
+
+@needs_shm
+def test_exported_shm_temp_root_without_tmpdir_plugin_still_runs(
+    pytester: pytest.Pytester, temproot: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("TMPDIR", str(SHM))
+    pytester.makepyfile("def test_pass():\n    pass\n")
+    run_pytest(pytester, "-p", "no:tmpdir").assert_outcomes(passed=1)
+
+
+@needs_shm
+@pytest.mark.parametrize(
+    ("args", "exit_code"),
+    [(("-k", "no_such_test"), 5), (("no_such_path.py",), 4)],
+    ids=["no-tests-collected", "usage-error"],
+)
+def test_session_that_runs_no_tests_leaves_nothing_behind(
+    pytester: pytest.Pytester, temproot: Path, args: tuple[str, ...], exit_code: int
+) -> None:
+    pytester.makepyfile("def test_pass():\n    pass\n")
+    assert run_pytest(pytester, *args).ret == exit_code
+    assert list(temproot.glob("pytest-of-*/pytest-[0-9]*")) == []
+
+
+@needs_shm
+def test_base_directory_is_freed_after_session_fixtures_finish_with_it(
+    pytester: pytest.Pytester, temproot: Path
+) -> None:
+    # pytest.exit skips the last test's teardown, so pytest tears session fixtures down
+    # in pytest_sessionfinish, which must run before the base directory disappears.
+    pytester.makepyfile(
+        """
+        import pytest
+
+        @pytest.fixture(scope="session")
+        def state(tmp_path_factory):
+            path = tmp_path_factory.mktemp("state")
+            yield path
+            (path / "closed").write_text("x")
+
+        def test_stop(state):
+            pytest.exit("done", returncode=0)
+        """
+    )
+    result = run_pytest(pytester)
+    assert result.ret == 0, result.stdout.str()
+    result.stdout.no_fnmatch_line("*Error*")
+    assert list(temproot.glob("pytest-of-*/pytest-[0-9]*")) == []
+
+
+@needs_shm
+def test_passing_xdist_session_leaves_nothing_behind(
+    pytester: pytest.Pytester, temproot: Path
+) -> None:
+    pytester.makepyfile("def test_write(tmp_path):\n    (tmp_path / 'state').write_text('x')\n")
+    run_pytest(pytester, "-n", "2", "--dist", "each").assert_outcomes(passed=2)
+    assert list(temproot.glob("pytest-of-*/pytest-[0-9]*")) == []
+
+
+@needs_shm
+def test_xdist_keeps_only_the_failing_workers_directory(
+    pytester: pytest.Pytester, temproot: Path
+) -> None:
+    pytester.makepyfile(
+        """
+        import os
+
+        def test_fails_on_gw1():
+            assert os.environ["PYTEST_XDIST_WORKER"] != "gw1"
+        """
+    )
+    run_pytest(pytester, "-n", "2", "--dist", "each").assert_outcomes(passed=1, failed=1)
+    (basetemp,) = temproot.glob("pytest-of-*/pytest-[0-9]*")
+    assert sorted(path.name for path in basetemp.iterdir()) == ["popen-gw1", "shm-tmp"]
+
+
+def test_loads_without_xdist(pytester: pytest.Pytester) -> None:
+    pytester.makepyfile("def test_pass():\n    pass\n")
+    run_pytest(pytester, "-p", "no:xdist").assert_outcomes(passed=1)