pytest-fixedpoint 0.1.3__tar.gz

pytest_fixedpoint-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: check
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: format --check
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .
+      - run: pytest tests/ -v

pytest_fixedpoint-0.1.3/.github/workflows/python-publish.yml

@@ -0,0 +1,68 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+name: Upload Python Package
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.12'
+      - name: Install dependencies
+        run: uv sync
+      - name: Build package
+        run: uv run --with build python -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          attestations: false
+
+  cd:
+    needs: deploy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.12'
+      - name: Install released package
+        run: uv pip install --system ${{ github.event.repository.name }}==${{ github.event.release.tag_name }}
+      - name: Verify installation
+        run: python -c "from importlib.metadata import version; print(version('${{ github.event.repository.name }}'))"
+      - name: Deploy to staging
+        run: |
+          echo "Deploying version ${{ github.event.release.tag_name }} to staging..."
+          # Add your staging deployment commands here
+        env:
+          DEPLOY_ENV: staging
+      - name: Run smoke tests
+        run: |
+          uv run python -c "print('Running smoke tests for version ${{ github.event.release.tag_name }}...')"
+          # Add smoke tests against the deployed environment here
+      - name: Deploy to production
+        run: |
+          echo "Deploying version ${{ github.event.release.tag_name }} to production..."
+          # Add your production deployment commands here
+        env:
+          DEPLOY_ENV: production

pytest_fixedpoint-0.1.3/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+cassettes/

pytest_fixedpoint-0.1.3/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

pytest_fixedpoint-0.1.3/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: pytest-fixedpoint
+Version: 0.1.3
+Summary: Pytest plugin for recording and replaying deterministic function calls
+License-Expression: MIT
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pytest>=7.0
+Requires-Dist: pyyaml>=6.0

pytest_fixedpoint-0.1.3/README.md

@@ -0,0 +1,145 @@
+# fixed-point
+
+* Fixed-Point is a pytest plugin designed to record and replay deterministic function calls, making your tests stable and reproducible.
+* Flaky tests are the bane of every developer's existence. I prefer not to rely on retries, mocks that drift from reality, or fragile test setups to keep things green.
+* To tackle this problem, Fixed-Point captures real function outputs and replays them faithfully, so your tests always land on the same answer — a fixed point.
+* It boasts simplicity, making it exceptionally easy to adopt in any pytest project.
+* Fixed-Point serves as a specialized testing tool, particularly tailored for pinning down the behavior of functions that talk to external services. If you encounter any cases not covered by the plugin, please don't hesitate to create an issue for further assistance.
+
+## Installation
+
+You can install pytest-fixedpoint using pip, the Python package manager:
+
+```
+pip install pytest-fixedpoint
+```
+
+## Getting Started
+
+To start using fixed-point in your project, simply decorate the functions you want to pin down with `@recordable`:
+
+```python
+from fixedpoint import recordable
+
+@recordable
+def call_external_api(query):
+    return external_service.search(query)
+
+def test_search(fixedpoint):
+    result = call_external_api("hello")
+    assert result == expected
+```
+
+The first time you run with `--fixedpoint=record_once`, it captures real outputs. Every subsequent run replays them — no network calls, no flakiness.
+
+## Modes
+
+Fixed-Point supports 4 operational modes via the `--fixedpoint` CLI option:
+
+| Mode | Behavior |
+|------|----------|
+| `off` | Default. Plugin is disabled, functions execute normally. |
+| `record_once` | Record new calls, replay existing ones. Ideal for initial setup. |
+| `replay` | Replay only. Fails with `CassetteNotFoundError` if no recording exists. Perfect for CI. |
+| `rewrite` | Always re-execute and overwrite recordings. Use when the real behavior has changed. |
+
+```bash
+# Record cassettes for the first time
+pytest tests/ --fixedpoint=record_once
+
+# Replay from cassettes (safe for CI)
+pytest tests/ --fixedpoint=replay
+
+# Force re-record everything
+pytest tests/ --fixedpoint=rewrite
+
+# Disable (default)
+pytest tests/
+```
+
+## Cassettes
+
+Recordings are stored as human-readable YAML files in `tests/cassettes/`:
+
+```
+tests/cassettes/
+  test_module_name/
+    test_function_name.yaml
+```
+
+A cassette file looks like:
+
+```yaml
+version: 1
+calls:
+  myapp.api.fetch_user:
+    - args: [42]
+      kwargs: {}
+      return: {"name": "Alice", "age": 30}
+```
+
+Cassettes are committed to your repo so the whole team replays the same results.
+
+## Supported Types
+
+The serializer handles these types out of the box:
+
+| Type | Serialized As |
+|------|---------------|
+| `None`, `bool`, `int`, `float`, `str` | Direct values |
+| `bytes` | `{"__bytes__": "<base64>"}` |
+| `tuple` | `{"__tuple__": [...]}` |
+| `set` | `{"__set__": [...]}` |
+| `list`, `dict` | Direct JSON arrays/objects |
+| `dataclass` | `{"__dataclass__": "module.Class", ...fields}` |
+
+## Error Handling
+
+Fixed-Point raises clear errors when things don't match:
+
+| Exception | When |
+|-----------|------|
+| `CassetteNotFoundError` | No cassette file found in `replay` mode |
+| `CassetteMismatchError` | Recorded args don't match actual call, or too many calls |
+| `SerializationError` | Unsupported type passed to a `@recordable` function |
+
+When you see a `CassetteMismatchError`, the error message includes a hint:
+
+> Run with `--fixedpoint=rewrite` to re-record
+
+## Comparison
+
+### vs VCR.py / responses / requests-mock
+
+VCR-style tools record at the **HTTP layer** — every header, cookie, content-type, and redirect ends up in your cassette. This means:
+
+* Cassettes are bloated with details you don't care about (auth tokens, timestamps, trace IDs).
+* An unrelated header change breaks your tests even though the actual data hasn't changed.
+* You're testing HTTP plumbing, not your application logic.
+
+Fixed-Point records at the **function layer**. You choose exactly which functions to pin down with `@recordable`, and the cassette only contains the args and return values — nothing more.
+
+### vs unittest.mock / monkeypatch
+
+Mocking is powerful, but it comes at a cost:
+
+* You have to **manually write** the return values. Guess wrong and your mock drifts from reality.
+* As your code evolves, you spend more time maintaining mocks than writing actual tests.
+* Mocks tell you nothing about what the real function actually returned — they only tell you what you *assumed* it would return.
+
+Fixed-Point records **real outputs** on the first run. No guessing, no hand-crafting fixtures. When reality changes, just `--fixedpoint=rewrite` and you're back in sync.
+
+### Summary
+
+| | VCR.py | mock | fixed-point |
+|---|--------|------|-------------|
+| Records at | HTTP layer | N/A (manual) | Function layer |
+| Setup effort | Low | High | Low |
+| Cassette noise | High (headers, cookies, etc.) | N/A | Low (args + return only) |
+| Stays in sync with reality | Fragile | Drifts over time | `rewrite` to refresh |
+
+## Why fixed-point?
+
+* In math, a fixed point is a value that stays the same no matter what function you throw at it. This project does the same for your tests — run them once, pin the result, replay forever.
+* But honestly, I named it "fixed-point" because of my wife. She's my fixed point — always cute, always kind, and somehow always right. No matter how chaotic things get, she's the constant I can count on.
+* So this one's for her. And if it makes your tests less flaky along the way, that's a nice bonus too.

pytest_fixedpoint-0.1.3/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytest-fixedpoint"
+dynamic = ["version"]
+description = "Pytest plugin for recording and replaying deterministic function calls"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "pytest>=7.0",
+    "pyyaml>=6.0",
+]
+classifiers = [
+    "Framework :: Pytest",
+    "Programming Language :: Python :: 3",
+]
+
+[project.entry-points.pytest11]
+fixedpoint = "fixedpoint.plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools_scm]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["fixedpoint"]

pytest_fixedpoint-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pytest_fixedpoint-0.1.3/src/fixedpoint/__init__.py

@@ -0,0 +1,28 @@
+from fixedpoint._registry import recordable
+
+__version__ = "0.1.0"
+
+
+class FixedPointError(Exception):
+    pass
+
+
+class CassetteNotFoundError(FixedPointError):
+    pass
+
+
+class CassetteMismatchError(FixedPointError):
+    pass
+
+
+class SerializationError(FixedPointError):
+    pass
+
+
+__all__ = [
+    "recordable",
+    "FixedPointError",
+    "CassetteNotFoundError",
+    "CassetteMismatchError",
+    "SerializationError",
+]

pytest_fixedpoint-0.1.3/src/fixedpoint/_cassette.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from fixedpoint._serializer import deserialize_value, serialize_value
+from fixedpoint._types import CallRecord, CassetteData
+
+
+class Cassette:
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._data = CassetteData()
+        self._replay_counters: dict[str, int] = {}
+        self._dirty = False
+
+    @classmethod
+    def load(cls, path: Path) -> Cassette:
+        c = cls(path)
+        raw = yaml.safe_load(path.read_text())
+        if not isinstance(raw, dict):
+            _raise_mismatch(f"Invalid cassette format in {path}")
+        version = raw.get("version", 1)
+        c._data.version = version
+        for func_key, entries in raw.get("calls", {}).items():
+            records = []
+            for entry in entries:
+                records.append(
+                    CallRecord(
+                        args=entry["args"],
+                        kwargs=entry.get("kwargs", {}),
+                        return_value=entry["return"],
+                    )
+                )
+            c._data.calls[func_key] = records
+        return c
+
+    def has_calls(self, func_key: str) -> bool:
+        calls = self._data.calls.get(func_key)
+        if not calls:
+            return False
+        idx = self._replay_counters.get(func_key, 0)
+        return idx < len(calls)
+
+    def record_call(
+        self, func_key: str, args: tuple, kwargs: dict, return_value: Any
+    ) -> None:
+        record = CallRecord(
+            args=serialize_value(args),
+            kwargs=serialize_value(kwargs),
+            return_value=serialize_value(return_value),
+        )
+        self._data.calls.setdefault(func_key, []).append(record)
+        self._dirty = True
+
+    def replay_call(self, func_key: str, args: tuple, kwargs: dict) -> Any:
+        calls = self._data.calls.get(func_key)
+        if not calls:
+            _raise_mismatch(f"No recorded calls for {func_key}")
+        idx = self._replay_counters.get(func_key, 0)
+        if idx >= len(calls):
+            _raise_mismatch(
+                f"Too many calls to {func_key}: expected {len(calls)}, "
+                f"got call #{idx + 1}"
+            )
+        record = calls[idx]
+        serialized_args = serialize_value(args)
+        serialized_kwargs = serialize_value(kwargs)
+        if serialized_args != record.args or serialized_kwargs != record.kwargs:
+            _raise_mismatch(
+                f"Argument mismatch for {func_key} call #{idx + 1}.\n"
+                f"  Expected args={record.args} kwargs={record.kwargs}\n"
+                f"  Got      args={serialized_args} kwargs={serialized_kwargs}\n"
+                f"  Hint: Run with --fixedpoint=rewrite to re-record."
+            )
+        self._replay_counters[func_key] = idx + 1
+        return deserialize_value(record.return_value)
+
+    def save(self) -> None:
+        if not self._dirty:
+            return
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        raw: dict = {
+            "version": self._data.version,
+            "calls": {
+                key: [
+                    {
+                        "args": r.args,
+                        "kwargs": r.kwargs,
+                        "return": r.return_value,
+                    }
+                    for r in records
+                ]
+                for key, records in self._data.calls.items()
+            },
+        }
+        self._path.write_text(yaml.dump(raw, default_flow_style=False, sort_keys=False))
+
+
+def _raise_mismatch(msg: str) -> None:
+    from fixedpoint import CassetteMismatchError
+
+    raise CassetteMismatchError(msg)

pytest_fixedpoint-0.1.3/src/fixedpoint/_interceptor.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fixedpoint._cassette import Cassette
+from fixedpoint._registry import set_active_interceptor
+
+
+class Interceptor:
+    def __init__(self, cassette: Cassette, mode: str) -> None:
+        self._cassette = cassette
+        self._mode = mode
+
+    def install(self) -> None:
+        set_active_interceptor(self)
+
+    def uninstall(self) -> None:
+        set_active_interceptor(None)
+
+    def intercept(self, key: str, original: Any, args: tuple, kwargs: dict) -> Any:
+        mode = self._mode
+        cassette = self._cassette
+
+        if mode in ("replay", "record_once") and cassette.has_calls(key):
+            return cassette.replay_call(key, args, kwargs)
+        if mode in ("record_once", "rewrite"):
+            result = original(*args, **kwargs)
+            cassette.record_call(key, args, kwargs, result)
+            return result
+        if mode == "replay":
+            from fixedpoint import CassetteNotFoundError
+
+            raise CassetteNotFoundError(
+                f"No cassette entry for {key} and mode is 'replay'.\n"
+                f"  Hint: Run with --fixedpoint=record_once to create it."
+            )
+        return original(*args, **kwargs)

pytest_fixedpoint-0.1.3/src/fixedpoint/_registry.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import functools
+import warnings
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+_REGISTRY: dict[str, Callable] = {}
+_active_interceptor: Any = None
+
+F = TypeVar("F", bound=Callable)
+
+
+def recordable(fn: F) -> F:
+    key = f"{fn.__module__}.{fn.__qualname__}"
+    if "<locals>" in key:
+        warnings.warn(
+            f"fixedpoint: {key} is a locally-defined function. "
+            "Cassettes may break if the enclosing function is renamed.",
+            stacklevel=2,
+        )
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        interceptor = _active_interceptor
+        if interceptor is not None:
+            return interceptor.intercept(key, fn, args, kwargs)
+        return fn(*args, **kwargs)
+
+    wrapper.__wrapped__ = fn  # type: ignore[attr-defined]
+    wrapper.__fixedpoint_recordable__ = True  # type: ignore[attr-defined]
+    wrapper.__fixedpoint_key__ = key  # type: ignore[attr-defined]
+    _REGISTRY[key] = fn
+    return wrapper  # type: ignore[return-value]
+
+
+def get_registry() -> dict[str, Callable]:
+    return _REGISTRY
+
+
+def clear_registry() -> None:
+    _REGISTRY.clear()
+
+
+def set_active_interceptor(interceptor: Any) -> None:
+    global _active_interceptor
+    _active_interceptor = interceptor

pytest_fixedpoint-0.1.3/src/fixedpoint/_serializer.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import base64
+import dataclasses
+import importlib
+from typing import Any
+
+
+def serialize_value(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, bytes):
+        return {"__bytes__": base64.b64encode(value).decode("ascii")}
+    if isinstance(value, tuple):
+        return {"__tuple__": [serialize_value(v) for v in value]}
+    if isinstance(value, set):
+        return {"__set__": sorted(serialize_value(v) for v in value)}
+    if isinstance(value, list):
+        return [serialize_value(v) for v in value]
+    if isinstance(value, dict):
+        for k in value:
+            if not isinstance(k, str):
+                _raise(f"Dict keys must be strings, got {type(k).__name__}")
+        return {k: serialize_value(v) for k, v in value.items()}
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        cls = type(value)
+        data: dict[str, Any] = {
+            "__dataclass__": f"{cls.__module__}.{cls.__qualname__}",
+        }
+        for f in dataclasses.fields(value):
+            data[f.name] = serialize_value(getattr(value, f.name))
+        return data
+    _raise(f"Cannot serialize type {type(value).__qualname__}")
+
+
+def deserialize_value(data: Any) -> Any:
+    if data is None or isinstance(data, (bool, int, float, str)):
+        return data
+    if isinstance(data, list):
+        return [deserialize_value(v) for v in data]
+    if isinstance(data, dict):
+        if "__bytes__" in data:
+            return base64.b64decode(data["__bytes__"])
+        if "__tuple__" in data:
+            return tuple(deserialize_value(v) for v in data["__tuple__"])
+        if "__set__" in data:
+            return {deserialize_value(v) for v in data["__set__"]}
+        if "__dataclass__" in data:
+            fqn = data["__dataclass__"]
+            module_name, _, class_name = fqn.rpartition(".")
+            mod = importlib.import_module(module_name)
+            cls = getattr(mod, class_name)
+            fields = {
+                f.name: deserialize_value(data[f.name]) for f in dataclasses.fields(cls)
+            }
+            return cls(**fields)
+        return {k: deserialize_value(v) for k, v in data.items()}
+    _raise(f"Cannot deserialize type {type(data).__qualname__}")
+
+
+def _raise(msg: str) -> None:
+    from fixedpoint import SerializationError
+
+    raise SerializationError(msg)

pytest_fixedpoint-0.1.3/src/fixedpoint/_types.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class CallRecord:
+    args: Any
+    kwargs: Any
+    return_value: Any
+
+
+@dataclass
+class CassetteData:
+    version: int = 1
+    calls: dict[str, list[CallRecord]] = field(default_factory=dict)