temper-python 0.1.0__py3-none-any.whl

temper/__init__.py

@@ -0,0 +1,26 @@
+"""Temper adapter for pytest.
+
+Mark a test with what it proves::
+
+    @pytest.mark.covers("store.reserve.never_negative", subject="store.file")
+    def test_reserve(): ...
+
+or claim from inside it, which is how a parametrized scenario runner names its
+scenario::
+
+    temper.covers(request, "alerts.low_stock", scenario="alerts.sold_out")
+"""
+
+from .plugin import add_claim
+
+__all__ = ["covers", "exempts"]
+
+
+def covers(request, ref, *, subject=None, scenario=None):
+    """The running test proves ``ref`` (for ``subject``, when it applies per subject)."""
+    add_claim(request, "covers", ref, subject, scenario)
+
+
+def exempts(request, ref, *, subject=None, scenario=None):
+    """The running test proves ``subject`` is excused from ``ref``."""
+    add_claim(request, "exempts", ref, subject, scenario)

temper/_evidence.py

@@ -0,0 +1,60 @@
+"""The evidence file: append-only, one file per process, one write per line."""
+
+import json
+import os
+import re
+import secrets
+from pathlib import Path
+
+_SEPARATORS = (",", ":")
+
+
+def encode(record):
+    """One record as one UTF-8 line, keys in the order given, compact."""
+    try:
+        return (json.dumps(record, separators=_SEPARATORS, ensure_ascii=False) + "\n").encode("utf-8")
+    except UnicodeEncodeError:
+        # A lone surrogate (an odd test id) cannot be UTF-8; JSON can still escape it.
+        return (json.dumps(record, separators=_SEPARATORS, ensure_ascii=True) + "\n").encode("utf-8")
+
+
+class Writer:
+    """Appends records to ``<level>-<pid>-<8 hex>.jsonl`` in a directory.
+
+    The file is created on the first record, never opened for truncation, and
+    never shared: a forked child opens its own.
+    """
+
+    def __init__(self, directory, level):
+        self._dir = Path(directory)
+        self._level = level
+        self._fd = None
+        self._pid = None
+
+    def ensure_directory(self):
+        self._dir.mkdir(parents=True, exist_ok=True)
+
+    def write(self, record):
+        data = encode(record)
+        fd = self._open()
+        written = os.write(fd, data)
+        while written < len(data):  # a short write is rare; finish the line
+            written += os.write(fd, data[written:])
+
+    def close(self):
+        if self._fd is not None and self._pid == os.getpid():
+            os.close(self._fd)
+        self._fd = None
+
+    def _open(self):
+        pid = os.getpid()
+        if self._fd is not None and self._pid == pid:
+            return self._fd
+        self._fd = None  # inherited across a fork: leave the parent's file alone
+        self.ensure_directory()
+        safe = re.sub(r"[^A-Za-z0-9._-]", "_", self._level)
+        name = f"{safe}-{pid}-{secrets.token_hex(4)}.jsonl"
+        flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_EXCL
+        self._fd = os.open(self._dir / name, flags, 0o644)
+        self._pid = pid
+        return self._fd

temper/plugin.py

@@ -0,0 +1,140 @@
+"""The pytest plugin: reads what each test claims, records how it ended.
+
+The level and the evidence directory come from ``TEMPER_LEVEL`` and
+``TEMPER_EVIDENCE``, read once when pytest starts. Without both, the plugin
+does nothing.
+"""
+
+import os
+from datetime import datetime, timezone
+
+import pytest
+
+from ._evidence import Writer
+
+CLAIM_KINDS = ("covers", "exempts")
+_KEYWORDS = ("subject", "scenario")
+
+_CLAIMS = pytest.StashKey()  # runtime claims made through temper.covers / temper.exempts
+_OUTCOMES = pytest.StashKey()  # one outcome per phase report
+_STATE = pytest.StashKey()
+
+_PRECEDENCE = ("error", "fail", "skip", "pass")  # first one present wins
+
+
+class _State:
+    def __init__(self, level, directory, run):
+        self.level = level
+        self.run = run
+        self.writer = Writer(directory, level)
+
+
+def _claim(kind, args, kwargs, where):
+    """Validate one claim and return (kind, ref, subject, scenario)."""
+    if len(args) != 1 or not isinstance(args[0], str) or not args[0]:
+        raise ValueError(f"{where}: {kind} takes one non-empty reference, as a string")
+    for key in kwargs:
+        if key not in _KEYWORDS:
+            hint = " (the level comes from the runner, never the test)" if key == "level" else ""
+            raise ValueError(f"{where}: {kind} has no keyword {key!r}{hint}; use subject or scenario")
+    for key in _KEYWORDS:
+        value = kwargs.get(key)
+        if value is not None and (not isinstance(value, str) or not value):
+            raise ValueError(f"{where}: {kind} {key} must be a non-empty string")
+    return kind, args[0], kwargs.get("subject"), kwargs.get("scenario")
+
+
+def add_claim(request, kind, ref, subject=None, scenario=None):
+    """Claim from inside a test; the claim follows the test's outcome."""
+    node = getattr(request, "node", None)
+    if not isinstance(node, pytest.Item):
+        raise TypeError(f"temper.{kind} needs the `request` fixture of a test")
+    kwargs = {k: v for k, v in (("subject", subject), ("scenario", scenario)) if v is not None}
+    claim = _claim(kind, (ref,), kwargs, node.nodeid)
+    node.stash.setdefault(_CLAIMS, []).append(claim)
+
+
+def _claims(item):
+    seen, out = set(), []
+    marked = [_claim(m.name, m.args, m.kwargs, item.nodeid) for m in item.iter_markers() if m.name in CLAIM_KINDS]
+    for claim in marked + item.stash.get(_CLAIMS, []):
+        if claim not in seen:
+            seen.add(claim)
+            out.append(claim)
+    return out
+
+
+def pytest_configure(config):
+    config.addinivalue_line("markers", "covers(ref, subject=None, scenario=None): the test proves this Temper claim")
+    config.addinivalue_line("markers", "exempts(ref, subject=None, scenario=None): the test proves this exemption")
+    level = os.environ.get("TEMPER_LEVEL", "")
+    directory = os.environ.get("TEMPER_EVIDENCE", "")
+    if not level or not directory:
+        return
+    state = _State(level, directory, os.environ.get("TEMPER_RUN", ""))
+    try:
+        state.writer.ensure_directory()
+    except OSError as err:
+        raise pytest.UsageError(f"temper: cannot write evidence to TEMPER_EVIDENCE={directory!r}: {err}")
+    config.stash[_STATE] = state
+
+
+def pytest_unconfigure(config):
+    state = config.stash.get(_STATE, None)
+    if state is not None:
+        state.writer.close()
+
+
+def pytest_collection_modifyitems(config, items):
+    if config.stash.get(_STATE, None) is None:
+        return
+    for item in items:
+        try:
+            _claims(item)
+        except ValueError as err:
+            raise pytest.UsageError(f"temper: {err}")
+
+
+def _outcome(report, call):
+    if hasattr(report, "wasxfail"):
+        return "fail"  # an expected failure never proves anything, whichever way it went
+    if report.skipped:
+        return "skip"
+    if report.passed:
+        return "pass"
+    if report.when != "call":
+        return "error"  # setup or teardown broke
+    excinfo = call.excinfo
+    if excinfo is None or isinstance(excinfo.value, (AssertionError, pytest.fail.Exception)):
+        return "fail"
+    return "error"
+
+
+@pytest.hookimpl(hookwrapper=True, tryfirst=True)
+def pytest_runtest_makereport(item, call):
+    outcome = yield
+    if item.config.stash.get(_STATE, None) is None:
+        return
+    item.stash.setdefault(_OUTCOMES, []).append(_outcome(outcome.get_result(), call))
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_protocol(item, nextitem):
+    yield
+    state = item.config.stash.get(_STATE, None)
+    outcomes = item.stash.get(_OUTCOMES, None)
+    if state is None or not outcomes:
+        return
+    final = next(o for o in _PRECEDENCE if o in outcomes)
+    at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    for kind, ref, subject, scenario in _claims(item):
+        record = {kind: ref}
+        if subject:
+            record["subject"] = subject
+        if scenario:
+            record["scenario"] = scenario
+        record.update(test=item.nodeid, level=state.level, outcome=final)
+        if state.run:
+            record["run"] = state.run
+        record["at"] = at
+        state.writer.write(record)

temper_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: temper-python
+Version: 0.1.0
+Summary: pytest adapter for Temper: tests state what they prove, and write evidence.
+Project-URL: Homepage, https://github.com/turbolytics/temper-python
+Project-URL: Temper, https://github.com/turbolytics/temper
+License: MIT
+License-File: LICENSE
+Classifier: Framework :: Pytest
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pytest>=7
+Provides-Extra: dev
+Requires-Dist: pytest-xdist; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# temper-python
+
+The [Temper](https://github.com/turbolytics/temper) adapter for pytest. A test
+states what it proves; the adapter records how it ended; `temper matrix` turns
+those records into a matrix of what is proven and what is not.
+
+## Getting started
+
+You need the `temper` CLI ([install](https://github.com/turbolytics/temper#install))
+and a project with `temper.yml` and a `temper/` directory of declarations.
+`temper guide` explains both.
+
+**1. Install the adapter.**
+
+```sh
+pip install temper-python
+```
+
+It is a pytest plugin: nothing to import or enable.
+
+**2. Mark each test with what it proves.**
+
+```python
+import pytest
+
+@pytest.mark.covers("store.reserve.never_negative", subject="store.file")
+def test_reserve_never_goes_negative(): ...
+
+@pytest.mark.exempts("store.persists_across_restart", subject="store.memory")
+def test_memory_store_forgets_on_restart(): ...
+```
+
+**3. Run the tests through `temper run`, then build the matrix.**
+
+```sh
+temper clean
+temper run --level unit -- pytest
+temper matrix --all-levels
+```
+
+That is the whole integration. Plain `pytest` behaves exactly as before: without
+the variables `temper run` sets, the plugin records nothing.
+
+## What a test can say
+
+| Mark | Meaning |
+|---|---|
+| `@pytest.mark.covers(ref)` | The test proves a feature or lattice member (`lattice/key`). |
+| `@pytest.mark.covers(ref, subject=id)` | The test proves an invariant or lattice member for that subject. |
+| `@pytest.mark.exempts(ref, subject=id)` | The test proves the subject is excused. Use it only in the test a declaration names in `proven_by`. |
+| `scenario=id` (on either) | The claim came from that declared scenario. |
+
+Marks on a class or a module apply to every test inside. A test may carry many
+marks; each is one record with the same outcome.
+
+A scenario runner that parametrizes one test over many scenarios claims from
+inside the test, where the scenario is known:
+
+```python
+import temper
+
+@pytest.mark.parametrize("sid", SCENARIOS)
+def test_scenario(request, sid):
+    temper.covers(request, "alerts.low_stock", scenario=sid)
+    temper.covers(request, sid, scenario=sid)
+    ...
+```
+
+`temper.exempts(request, ref, subject=...)` is the same for exemptions.
+
+There is no way to set a level. The runner does (`temper run --level`), and a
+test that changes `TEMPER_LEVEL` in its own environment changes nothing: the
+environment is read once, when pytest starts.
+
+A malformed mark (no reference, a stray keyword such as `level=`, a non-string)
+stops the run with a message naming the test, when the runner is active.
+
+## How outcomes are recorded
+
+A record is written once the test is final, after fixtures have torn down.
+
+| Outcome | When |
+|---|---|
+| `pass` | The test, its setup and its teardown all passed. The only outcome that counts. |
+| `fail` | An assertion failed, `pytest.fail` was called, or the test was `xfail` (whether it failed or passed). |
+| `skip` | The test was skipped, in any phase. |
+| `error` | An exception other than a failed assertion, or any failure in setup or teardown. |
+
+A test that fails and then skips records `fail`. Evidence goes to one new file
+per process, `<level>-<pid>-<8 hex>.jsonl`, opened for append, one write per
+line. Existing evidence is never truncated, so `pytest-xdist` works without
+configuration. The contract every adapter follows is
+[docs/adapters.md](https://github.com/turbolytics/temper/blob/main/docs/adapters.md).
+
+Not verified: retry plugins such as `pytest-rerunfailures`.
+
+## Development
+
+```sh
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+make matrix        # clean, run the tests through temper, rebuild MATRIX.md
+make check-matrix  # fail if the committed matrix is stale
+```
+
+This project is declared with Temper in `temper/`, and its own tests prove the
+adapter claims with the adapter: see [MATRIX.md](MATRIX.md).
+
+## Releasing
+
+Set `version` in `pyproject.toml`, merge, then push the matching tag:
+
+```sh
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The release workflow checks the tag matches the version, runs the tests, builds,
+and publishes to PyPI through trusted publishing.

temper_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+temper/__init__.py,sha256=PeOWgYHJbTderl4JJjMsPMtT8ZcuXz_bLYzcv0OPiys,804
+temper/_evidence.py,sha256=sKT71KPbBX2M3ep43E2KpDZcTjne91tg5d6wLU5rBPY,2003
+temper/plugin.py,sha256=GbAkF--zjhomP18s28FJw67kEkzGsEakRYsToLO-oAs,5085
+temper_python-0.1.0.dist-info/METADATA,sha256=rRUOfJ4IrofhVqp3BZ3_0H-PPNid-A6Y6cRUOmJiRXk,4757
+temper_python-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+temper_python-0.1.0.dist-info/entry_points.txt,sha256=2eoBjS7NuMZfmbdIML3l4wXXTPhiMEA-J67DJ1YsZlA,34
+temper_python-0.1.0.dist-info/licenses/LICENSE,sha256=hrlBpg_NtMec1X4UblatT5hOiwVgDS1JZwvALSbMThY,1068
+temper_python-0.1.0.dist-info/RECORD,,

temper_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

temper_python-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+temper = temper.plugin

temper_python-0.1.0.dist-info/licenses/LICENSE

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