pytest-warmup 0.1.1__tar.gz

pytest_warmup-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -q
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package metadata rendering
+        run: python -m twine check dist/*
+
+      - name: Smoke test built wheel
+        shell: bash
+        run: |
+          set -euo pipefail
+          tmpdir="$(mktemp -d)"
+          python -m venv "$tmpdir/.venv"
+          "$tmpdir/.venv/bin/python" -m pip install --upgrade pip
+          "$tmpdir/.venv/bin/python" -m pip install dist/pytest_warmup-*.whl pytest
+          cp examples/basic_usage.py "$tmpdir/test_basic_usage.py"
+          cp examples/warmup.snapshot.json "$tmpdir/warmup.snapshot.json"
+          (cd "$tmpdir" && "$tmpdir/.venv/bin/python" -m pytest -q)

pytest_warmup-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install build tooling
+        run: python -m pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package metadata rendering
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pytest_warmup-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.pyc
+.idea/
+dist/
+build/

pytest_warmup-0.1.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.1
+
+- Initial public alpha extraction from the prototype workspace.
+- Explicit `WarmupPlan.require(...)` declaration model.
+- `@warmup_param(...)` injection for fixtures and test functions.
+- Optional producer conveniences through `producer_fixture="..."` and a project-local `warmup_autoresolve_producer` fixture.
+- File-based snapshot overrides through `prepare(snapshot_file=...)`.
+- Initial validation coverage for cycles, producer-chain errors, distributed declarations, snapshot file failures, and package surface boundaries.
+- Public-package hygiene: executable examples, built-wheel smoke testing, and `twine check` validation.
+- Trusted Publishing workflow and release documentation for GitHub Actions based PyPI publication.

pytest_warmup-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+This repository is still in an early alpha phase. The most important contribution rule is to keep the public API narrow and explicit.
+
+## Development Setup
+
+```bash
+uv venv .venv
+uv pip install --python .venv/bin/python -e ".[dev]"
+```
+
+## Verification
+
+Run the local checks before proposing changes:
+
+```bash
+./.venv/bin/python -m pytest -q
+./.venv/bin/python -m build
+./.venv/bin/python -m twine check dist/*
+```
+
+Before publishing or cutting a release candidate, also do one external-user smoke check from the built wheel: create a fresh virtual environment, install the wheel from `dist/`, and run one of the example tests without editable-install path hacks.
+
+For the repository-side release flow, see [`docs/publishing.md`](docs/publishing.md).
+
+## Scope Rules
+
+Changes are welcome, but the package should stay focused on:
+
+- requirement declaration through `WarmupPlan.require(...)`;
+- explicit producer preparation through `warmup_mgr.use(...).prepare(...)`;
+- injection through `@warmup_param(...)`;
+- file-based snapshot overrides;
+- batch preparation and distribution of expensive test resources.
+
+The package should not grow into:
+
+- a general factory framework;
+- a generic snapshot assertion library;
+- a service/container orchestration framework;
+- a domain-specific toolkit.
+
+## Public API Hygiene
+
+Before widening the public surface, check whether the change can stay internal instead.
+
+In particular, keep these internal unless there is a strong reason otherwise:
+
+- graph normalization helpers;
+- runtime/store implementation details;
+- test-support demo plans;
+- fake external API helpers.

pytest_warmup-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timothy Rabbit
+
+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_warmup-0.1.1/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: pytest-warmup
+Version: 0.1.1
+Summary: Batch preparation and distribution of expensive test resources for pytest.
+Project-URL: Homepage, https://github.com/kaor4bp/pytest-warmup
+Project-URL: Repository, https://github.com/kaor4bp/pytest-warmup
+Project-URL: Issues, https://github.com/kaor4bp/pytest-warmup/issues
+Author: OpenAI Codex collaboration
+License: MIT License
+        
+        Copyright (c) 2026 Timothy Rabbit
+        
+        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: batch,fixtures,pytest,pytest-plugin,testing,warmup
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.13
+Requires-Dist: pytest>=8.4
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.4; extra == 'dev'
+Requires-Dist: twine>=6.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytest-warmup
+
+`pytest-warmup` is a pytest plugin for batch preparation and distribution of expensive test resources.
+
+Use it when ordinary fixture-by-fixture setup becomes too slow or too hard to reason about because objects are expensive to create, depend on one another, or require extra orchestration after creation.
+
+Typical cases:
+
+- creating external-domain objects in batches before a module or session runs;
+- waiting for synchronization, indexing, or propagation after creation;
+- reusing one prepared upstream object across multiple tests;
+- creating per-test instances only where the declaration explicitly asks for it;
+- replacing selected prepared values from a snapshot file for debugging.
+
+## Installation
+
+```bash
+pip install pytest-warmup
+```
+
+## Public API
+
+This package is intentionally narrow:
+
+- `WarmupPlan`
+- `WarmupRequirement`
+- `WarmupError`
+- `@warmup_param(...)`
+- `warmup_mgr.use(...).prepare(...)`
+
+## Quick Start
+
+Declare resource requirements in plan classes:
+
+```python
+from pytest_warmup import WarmupPlan, WarmupRequirement
+
+
+class ProfilePlan(WarmupPlan):
+    def require(
+        self,
+        *,
+        profile_name: str,
+        id: str | None = None,
+        is_per_test: bool | None = None,
+    ) -> WarmupRequirement:
+        return super().require(
+            payload={"profile_name": profile_name},
+            dependencies={},
+            id=id,
+            is_per_test=is_per_test,
+        )
+
+    def prepare(self, nodes, runtime) -> None:
+        for node in nodes:
+            runtime.set(
+                node,
+                {
+                    "profile_id": f"profile-{node.payload['profile_name']}",
+                    "profile_name": node.payload["profile_name"],
+                },
+            )
+```
+
+Build requirements from those plans:
+
+```python
+profile = ProfilePlan("profile")
+profile_main = profile.require(profile_name="main", id="profile_main")
+```
+
+Create one explicit producer fixture:
+
+```python
+import pytest
+
+
+@pytest.fixture(scope="module")
+def prepare_data(warmup_mgr):
+    return warmup_mgr.use(profile).prepare()
+```
+
+Inject the prepared resource into a test or fixture:
+
+```python
+from pytest_warmup import warmup_param
+
+
+@warmup_param("prepared_profile", profile_main)
+def test_profile(prepare_data, prepared_profile):
+    assert prepared_profile["profile_id"].startswith("profile-")
+```
+
+`is_per_test=True` on a requirement means that requirement is materialized separately for each collected test item. If omitted, the requirement inherits per-test behavior from upstream dependencies, otherwise it stays shared within the producer scope.
+
+For full runnable examples, see:
+
+- [`examples/basic_usage.py`](examples/basic_usage.py)
+- [`examples/autoresolve_usage.py`](examples/autoresolve_usage.py) for fixture-side autoresolve binding
+- [`examples/named_producer_usage.py`](examples/named_producer_usage.py)
+
+## Producer Patterns
+
+The default model stays explicit: a test or fixture depends on a producer fixture in the ordinary pytest dependency chain.
+
+Recommended order:
+
+1. use an explicit producer argument for the default, most readable path;
+2. use `warmup_autoresolve_producer` when you want less producer boilerplate but still keep one clearly defined producer seam;
+3. use `producer_fixture="..."` only to disambiguate between producers that are already present in the pytest dependency chain.
+
+Producer resolution rules:
+
+1. if `producer_fixture="..."` is provided, that fixture must already be part of the pytest dependency chain and is used as the producer;
+2. otherwise, if the dependency chain already contains exactly one prepared producer, that producer is used;
+3. otherwise, `warmup_autoresolve_producer` is used as a narrow fallback if it exists;
+4. otherwise, producer resolution fails fast.
+
+Producer convenience does not bypass normal pytest scope rules. A narrower producer is still invalid for a wider-scope consumer, and `warmup_autoresolve_producer` does not widen fixture visibility.
+
+Example of the fallback fixture:
+
+```python
+@pytest.fixture
+def warmup_autoresolve_producer(prepare_data):
+    return prepare_data
+
+
+@pytest.fixture
+@warmup_param("prepared_profile", profile_main)
+def prepared_profile_fixture(prepared_profile):
+    return prepared_profile
+```
+
+## Snapshot File Overrides
+
+Debug replacement is file-based through `prepare(snapshot_file=...)`.
+
+The current JSON shape is:
+
+```json
+{
+  "shared": {
+    "profile_main": {
+      "profile_id": "debug-profile"
+    }
+  },
+  "tests": {
+    "tests/test_module.py::test_case": {
+      "items_alpha": {
+        "items_id": "debug-items"
+      }
+    }
+  }
+}
+```
+
+Rules:
+
+- shared nodes are addressed by `id`;
+- per-test nodes are addressed by `tests[nodeid][id]`;
+- declarations that are effectively per-test may not be overridden through `shared`.
+
+## Troubleshooting
+
+Common producer-resolution errors usually mean one of these:
+
+- `no producer fixture found in pytest dependency chain ...`
+  The decorated test or fixture is not connected to any producer fixture, and no `warmup_autoresolve_producer` fallback exists.
+- `multiple producer fixtures found in pytest dependency chain`
+  The current dependency chain exposes more than one prepared producer. Simplify the chain or use `producer_fixture="..."` to pick one explicitly.
+- `producer fixture '...' is not in this dependency chain`
+  The named producer exists, but the current test or fixture does not depend on it through ordinary pytest wiring.
+- `producer fixture '...' must return a prepared warmup scope`
+  The selected fixture returned an ordinary value instead of the prepared scope returned by `warmup_mgr.use(...).prepare(...)`.
+- `... cannot be shared because dependency ... is per-test`
+  A shared declaration depends on a branch that is effectively per-test. Either inherit that branch or split the declaration differently.
+
+## Scope Boundary
+
+`pytest-warmup` is not trying to be:
+
+- a general-purpose factory framework;
+- a generic snapshot assertion library;
+- a container or infrastructure manager;
+- a hidden autouse preparation layer;
+- a domain-specific toolkit.
+
+It focuses on one problem: batch creation and targeted distribution of expensive test resources.
+
+Further design details live in:
+
+- [`docs/design.md`](docs/design.md)
+- [`docs/publishing.md`](docs/publishing.md)
+- [`examples/README.md`](examples/README.md)
+- [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- [`CHANGELOG.md`](CHANGELOG.md)
+
+## Development
+
+```bash
+uv venv .venv
+uv pip install --python .venv/bin/python -e ".[dev]"
+./.venv/bin/python -m pytest -q
+./.venv/bin/python -m build
+```
+
+Before publishing, also do one smoke check from the built wheel in a fresh virtual environment.
+
+## Attribution
+
+The initial code, tests, and documentation in this repository were generated and iteratively refined with ChatGPT/Codex plus collaborating agents.
+
+Named collaborating agents from the design and spike process:
+
+- Lovelace is an adversarial, QA-minded reviewer focused on user-facing clarity. She pushed the ergonomics tests, debug/override edge cases, and the API critiques that kept the package honest from a user perspective.
+- Herschel is a graph-minded, skeptical contributor who prefers explicit execution boundaries over hidden magic. He drove the selected-roots to reachable-subgraph execution model and kept edge-case behavior small and defensible.
+- Chandrasekhar is a no-magic, contract-first contributor focused on clear binding and injection rules. He helped shape the public injection model and the readable fail-fast behavior around overrides and producer discovery.
+- Pauli is a direct, readability-first contributor who focused on the debug surface and shared-vs-per-test semantics. He helped keep snapshot addressing and distributed-declaration behavior explicit and testable.
+- Kuhn is a pragmatic builder who prefers simple, reviewable orchestration over framework cleverness. He contributed to the manager/runtime seams and the explicit lifecycle shape used by the public prototype.
+
+All generated material still requires human review. The repository treats generated output as draft engineering work, not as an authority.