cot.tmppath 0.1.0__tar.gz

cot_tmppath-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    cooldown:
+      default-days: 7
+    groups:
+      actions:
+        patterns: ["*"]

cot_tmppath-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0  # hatch-vcs derives the version from tags
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7  # v10.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - run: uv run --frozen pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.14"
+
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd  # v3.0.1

cot_tmppath-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0  # hatch-vcs derives the version from tags
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7  # v10.2.0
+        with:
+          python-version: "3.14"
+          # A release builds from a clean slate: a restored cache is one more
+          # thing that could influence what ends up on PyPI.
+          enable-cache: false
+
+      # The tag is what the version comes from, so a release must not ship a
+      # tree that fails its own suite.
+      - run: uv run --frozen pytest -q
+
+      - run: uv build
+
+      # A wheel that cannot be imported from a clean environment is the one
+      # failure mode the test suite cannot see.
+      - name: smoke-test the built wheel
+        run: |
+          uv run --isolated --no-project --with dist/*.whl \
+            python -c "import cot.tmppath; print(cot.tmppath.__all__)"
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2

cot_tmppath-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/

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

@@ -0,0 +1,28 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+    - id: check-toml
+    - id: check-yaml
+    - id: end-of-file-fixer
+    - id: trailing-whitespace
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.16.9
+  hooks:
+    - id: ruff-check
+      args: [ --fix, --show-fixes ]
+    - id: ruff-format
+
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v2.3.1
+  hooks:
+    - id: mypy
+      # checks what [tool.mypy] names, not the staged files alone
+      pass_filenames: false
+      additional_dependencies: [ pytest ]
+
+- repo: https://github.com/zizmorcore/zizmor-pre-commit
+  rev: v1.30.1
+  hooks:
+    - id: zizmor

cot_tmppath-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ronny Pfannschmidt
+
+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.

cot_tmppath-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.5
+Name: cot.tmppath
+Version: 0.1.0
+Summary: Hardened, fast management of related temporary folders
+Project-URL: Source, https://github.com/cogs-of-testing/cot.tmppath
+Author-email: Ronny Pfannschmidt <opensource@ronnypfannschmidt.de>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cot.tmppath
+
+A hardened, fast building block for related temporary folders: one folder
+per run, items side by side inside it, kept or removed by policy, safe with
+concurrent processes. For test runners (a pytest binding) and for
+cot.runsomewhere's bootstrap staging and worker scratch.
+
+Not built yet. The goals are in [docs/goals.md](docs/goals.md) and the
+background in [docs/research.md](docs/research.md). `src/cot/tmppath` holds
+the intended API as stubs that raise `NotImplementedError`, and `testing/`
+states the goals as tests, marked xfail until each behaviour lands.
+
+```bash
+uv run pytest -q
+uv run mypy
+uv run --group bench pytest benchmarks
+```
+
+pytest projects can opt in to having pytest's `tmp_path`, `tmp_path_factory`,
+`tmpdir` and `tmpdir_factory` replaced:
+
+```ini
+[pytest]
+addopts = -p cot.tmppath.overtake_pytest
+```
+
+How and why is in [docs/pytest-replacement.md](docs/pytest-replacement.md).
+
+Old runs can be removed by hand; it lists them and asks before removing:
+
+```bash
+python -m cot.tmppath prune --all-projects --older-than 7d
+```

cot_tmppath-0.1.0/README.md

@@ -0,0 +1,33 @@
+# cot.tmppath
+
+A hardened, fast building block for related temporary folders: one folder
+per run, items side by side inside it, kept or removed by policy, safe with
+concurrent processes. For test runners (a pytest binding) and for
+cot.runsomewhere's bootstrap staging and worker scratch.
+
+Not built yet. The goals are in [docs/goals.md](docs/goals.md) and the
+background in [docs/research.md](docs/research.md). `src/cot/tmppath` holds
+the intended API as stubs that raise `NotImplementedError`, and `testing/`
+states the goals as tests, marked xfail until each behaviour lands.
+
+```bash
+uv run pytest -q
+uv run mypy
+uv run --group bench pytest benchmarks
+```
+
+pytest projects can opt in to having pytest's `tmp_path`, `tmp_path_factory`,
+`tmpdir` and `tmpdir_factory` replaced:
+
+```ini
+[pytest]
+addopts = -p cot.tmppath.overtake_pytest
+```
+
+How and why is in [docs/pytest-replacement.md](docs/pytest-replacement.md).
+
+Old runs can be removed by hand; it lists them and asks before removing:
+
+```bash
+python -m cot.tmppath prune --all-projects --older-than 7d
+```

cot_tmppath-0.1.0/benchmarks/test_bench.py

@@ -0,0 +1,108 @@
+"""Benchmarks against pytest's own tmp_path machinery (docs/goals.md, G3).
+
+Each scenario runs once with pytest's ``TempPathFactory`` and once with
+cot.tmppath. The cot.tmppath side is xfail until the core is built.
+
+    uv run --group bench pytest benchmarks
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import pytest
+from _pytest.tmpdir import TempPathFactory
+
+from cot.tmppath import Outcome, Retention, Root
+
+not_built = pytest.mark.xfail(
+    raises=NotImplementedError, reason="core not built yet (docs/goals.md)"
+)
+
+# pytest scans the base folder on every mktemp, so cost grows with siblings
+ITEMS = [100, 1000]
+
+
+def _pytest_factory(base: Path) -> TempPathFactory:
+    return TempPathFactory(
+        given_basetemp=base,
+        retention_count=3,
+        retention_policy="all",
+        trace=lambda *args: None,
+        _ispytest=True,
+    )
+
+
+class _Fresh:
+    """Hands out a new, empty folder per benchmark round."""
+
+    def __init__(self, base: Path) -> None:
+        self._base = base
+        self._count = 0
+
+    def __call__(self) -> Path:
+        self._count += 1
+        return self._base / f"round{self._count}"
+
+
+@pytest.fixture
+def fresh(tmp_path: Path) -> _Fresh:
+    return _Fresh(tmp_path)
+
+
+@pytest.mark.parametrize("count", ITEMS)
+def test_items_pytest(benchmark, fresh: _Fresh, count: int) -> None:
+    def make() -> None:
+        factory = _pytest_factory(fresh())
+        for _ in range(count):
+            factory.mktemp("test_something_parametrized_", numbered=True)
+
+    benchmark.pedantic(make, rounds=5, iterations=1)
+
+
+@not_built
+@pytest.mark.parametrize("count", ITEMS)
+def test_items_cot(benchmark, fresh: _Fresh, count: int) -> None:
+    def make() -> None:
+        with Root(fresh()).start_run() as run:
+            for _ in range(count):
+                run.item("test_something_parametrized_")
+
+    benchmark.pedantic(make, rounds=5, iterations=1)
+
+
+def _filled(path: Path) -> Path:
+    path.mkdir(parents=True)
+    for index in range(200):
+        (path / f"f{index}").write_bytes(b"x" * 512)
+    return path
+
+
+def test_removal_pytest(benchmark, fresh: _Fresh) -> None:
+    # what tmp_path's teardown does under tmp_path_retention_policy=failed
+    def setup() -> tuple[tuple[Path], dict[str, object]]:
+        return (_filled(fresh() / "item"),), {}
+
+    benchmark.pedantic(
+        lambda item: shutil.rmtree(item, ignore_errors=True),
+        setup=setup,
+        rounds=20,
+    )
+
+
+@not_built
+def test_removal_cot(benchmark, fresh: _Fresh) -> None:
+    root = Root(fresh(), retention=Retention(keep_failed_only=True))
+    with root.start_run() as run:
+
+        def setup() -> tuple[tuple[Path], dict[str, object]]:
+            item = run.item("item")
+            _filled(item / "data")
+            return (item,), {}
+
+        benchmark.pedantic(
+            lambda item: run.finish_item(item, Outcome.PASSED),
+            setup=setup,
+            rounds=20,
+        )

cot_tmppath-0.1.0/docs/assessment.md

@@ -0,0 +1,154 @@
+# Assessment: hardening, pytest policies, cleanup
+
+*Written by Claude via Claude Code from Ronny's brief; Ronny prompted it.*
+
+Status as of 2026-10-05. Checked against `main`, pytest 9.1.1 and
+pytest-xdist 3.8. **(verified)** means it was run, not read.
+
+## Summary
+
+- **The core implements no hardening yet.** Everything in `_api.py` raises
+  `NotImplementedError`. What exists is a specification: 4 hardening tests
+  in `testing/test_hardening.py`, all xfail. Today cot.tmppath is not safer
+  than pytest, it is a plan to be.
+- **The specification has real gaps** (below), the largest being that the
+  default root has no per-user part, which reproduces pytest's shared-`/tmp`
+  denial of service.
+- **The pytest plugin is the only working code.** Its `--basetemp` check had
+  a symlink hole, now fixed; three compatibility gaps were fixed, and three
+  semantic differences from pytest remain open.
+- **A cleanup command is worth having**, as a thin wrapper over
+  `Root.prune`, mainly for runsomewhere targets and for projects that are no
+  longer run. Recommendation below.
+
+## 1. Hardening
+
+### What the tests specify
+
+| Property | Test | State |
+|---|---|---|
+| root, run and item folders are 0o700 | `test_folders_are_private` | xfail |
+| a symlinked root is refused, target untouched | `test_symlinked_root_is_refused` | xfail |
+| an existing folder we did not create is refused, not wiped | `test_existing_folder_it_did_not_create_is_refused_not_wiped` | xfail |
+| a root owned by another user is refused | `test_root_owned_by_another_user_is_refused` | xfail, runs only as root |
+| an existing `--basetemp` is refused, contents untouched | `test_existing_basetemp_is_refused` | **passes** |
+| a symlink to a fresh empty folder is refused as `--basetemp` | `test_symlink_to_a_fresh_empty_folder_is_refused` | **passes** (fixed today) |
+
+### Gaps in the specification
+
+These are not covered by any test and not decided in `goals.md`:
+
+1. **No per-user part in the default root** (decided: added, as
+   `{temproot}/cot.tmppath-{user}/{project}`, see goals G2). `Root.for_project(project)`
+   puts the root under the system temp folder by project name alone. On a
+   shared `/tmp`, user B pre-creating `/tmp/<project>` makes user A's runs
+   fail the ownership check: the same denial of service pytest accepts for
+   `pytest-of-{user}`. The default root needs the user in its name (uid on
+   POSIX), and the parent should be checked for the sticky bit when it is
+   world-writable.
+2. **TOCTOU between check and use is untested.** G1 promises `dir_fd` and
+   `O_NOFOLLOW`, but no test swaps a folder for a symlink between the check
+   and the `mkdir` of an item, or replaces a run folder while a run is live.
+3. **The plugin's `--basetemp` check is advisory.** It runs at configure
+   time; the folder is created on first use. Only the core creating the root
+   with an exclusive `mkdir` (and refusing on `EEXIST` unless it is the
+   accepted fresh folder) closes that window.
+4. **Windows has no equivalent of 0o700.** `chmod` there only toggles the
+   read-only flag. Protection rests on `%TEMP%` being per-user. Not stated in
+   the goals, not tested; a root outside the user profile is unprotected.
+5. **Lock liveness is unspecified at the edge cases**: pid reuse after a
+   reboot (hence the boot id in G5), and a lock on a filesystem shared
+   between hosts.
+6. **Read-only content.** Tests that `chmod` their files read-only made pytest
+   crash on the next run (pytest #5524). No test covers removal of read-only
+   files and folders, or of folders a test made unreadable.
+7. **The marker is unspecified.** "Only deletes what it created" depends on a
+   marker; its content, how it is checked, and that it cannot be planted by
+   another user (the ownership check covers that on POSIX) need writing down.
+
+## 2. pytest's policies and our mapping
+
+What pytest does, observed with `count=2` over five runs with one passing and
+one failing test, then one all-passing run **(verified)**:
+
+| Policy | pytest keeps | All-passing run | Our mapping |
+|---|---|---|---|
+| `all` | last *count* runs, every test folder | kept, counts as a run | `keep_runs=count` |
+| `failed` | last *count* runs, only failed test folders | whole run folder removed at session end | `keep_failed_only=True, keep_runs=count` |
+| `none` | nothing, not even the current run after it ends | removed | `keep_runs=0` |
+
+Where we differ:
+
+1. **`failed`: an all-passing run leaves an empty run folder.** pytest
+   removes it. We should remove a run that ends with no items, or the empty
+   folders pile up to *count*. Small; belongs in the core's `close()`.
+2. **`none`: whether `keep_runs=0` removes the current run at close is not
+   specified.** pytest does. Our concurrency test only says a *live* run
+   survives another process's prune. A test should pin that closing with
+   `keep_runs=0` removes the run.
+3. **Whole outcome, not `call`.** Deliberately different: we keep folders of
+   setup and teardown failures, pytest discards them
+   (`test_failed_policy_keeps_setup_and_teardown_failures`).
+4. **`--basetemp`.** Deliberately different: no wiping, no retention, refuse
+   an existing folder (issue #1 tracks the option's name).
+
+Plugin compatibility, checked against pytest's `tmpdir.py` and
+`legacypath.py`:
+
+| pytest behaviour | Plugin | State |
+|---|---|---|
+| `tmpdir_factory` returns `py.path` objects | returned `Path` | **fixed today** |
+| `PYTEST_DEBUG_TEMPROOT` overrides the temp root | ignored | **fixed today** |
+| retention ini values validated, error on bad value | `UsageError` | ok |
+| `mktemp(name, numbered=False)` creates exactly `name`, fails if it exists | always unique name | **open**: breaks code that relies on the exact name |
+| `getbasetemp()` is per process; under xdist `getbasetemp().parent` is the shared run folder | the process's own folder, named by the controller | **fixed**: `getbasetemp().parent` is the run |
+| `mktemp` rejects absolute and non-normalised names (#5686) | passed to `Run.item`, which flattens them | **open**: decide whether to reject like pytest |
+| `tmp_path` is a resolved real path (#4653) | depends on the core | open, add to the core tests |
+| test folder names truncated to 30 characters | full sanitized name, the core shortens to at most 64 | intended |
+
+`getbasetemp()` now returns a per-process folder inside the run, named by
+the manager (`Run.process_folder`), so `getbasetemp().parent` means "the
+run" as it does with pytest under xdist.
+
+## 3. Do we need a cleanup command?
+
+**Who cleans up today.** pytest removes old runs only when the same user runs
+pytest again, and only in its own `pytest-of-{user}`. Our retention is the
+same: it runs when a run closes, per project. So nothing ever removes:
+
+- the runs of a project that is not run again;
+- the runs left by crashed processes, until that project runs again and the
+  owner is known dead;
+- runsomewhere's staging and scratch on a target host that is not visited
+  again, which the system's `/tmp` cleaning may or may not catch
+  (from memory, not checked here: systemd-tmpfiles typically ages `/tmp`
+  after about 10 days, macOS cleans `/var/folders` after a few days, and
+  containers and long-lived CI runners often never clean at all).
+
+`Root.prune()` already exists in the API, so a command is a thin wrapper.
+
+**Decided: yes, small.** Built as `python -m cot.tmppath prune` (also the
+`cot-tmppath` script):
+
+```text
+python -m cot.tmppath prune [ROOT ...] [--all-projects] [--older-than 7d]
+                            [--dry-run | --delete-without-asking-i-have-read-the-dry-run]
+```
+
+- By default it lists what it would remove and asks; only typing `yes`
+  removes anything. Without a terminal to ask on, it refuses.
+- `--dry-run` only lists.
+- Removing without asking takes a flag that is long on purpose, and
+  argparse abbreviations are off, so `--delete` does not expand to it
+  **(verified: argparse accepts such prefixes by default)**.
+- It removes exactly the listed folders, each checked again first
+  (`PrunePlan.apply`).
+
+- It applies exactly the library's rules: only folders carrying our marker,
+  owned by the current user, whose lock owner is dead; never anything else.
+- `--all-projects` walks every project root under the user's default
+  location, which is the case retention cannot reach.
+- runsomewhere can call `Root.prune` directly over its own connection; the
+  command is for people and cron.
+- A pytest option (`--tmp-prune`) is not needed: the plugin prunes the
+  current project on every run already.