snapfix 0.1.0__py3-none-any.whl

snapfix/__init__.py

@@ -0,0 +1,6 @@
+from snapfix.capture import capture
+from snapfix.config import DEFAULT_SCRUB_FIELDS, SnapfixConfig
+from snapfix.reconstruct import reconstruct
+
+__all__ = ["capture", "reconstruct", "SnapfixConfig", "DEFAULT_SCRUB_FIELDS"]
+__version__ = "0.1.0"

snapfix/capture.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import asyncio
+import datetime
+import functools
+import pathlib
+import warnings
+from collections.abc import Callable
+
+from snapfix.codegen import SnapfixCodegen
+from snapfix.config import SnapfixConfig
+from snapfix.scrubber import SnapfixScrubber
+from snapfix.serializer import SnapfixSerializer
+from snapfix.store import SnapfixStore
+
+_default_config: SnapfixConfig | None = None
+
+
+def _get_config(cfg: SnapfixConfig | None) -> SnapfixConfig:
+    global _default_config
+    if cfg is not None:
+        return cfg
+    if _default_config is None:
+        yaml_path = pathlib.Path("snapfix.yaml")
+        _default_config = SnapfixConfig.from_yaml(yaml_path)
+    return _default_config
+
+
+def capture(
+    name: str,
+    scrub: list[str] | None = None,
+    max_depth: int | None = None,
+    max_size_bytes: int | None = None,
+    config: SnapfixConfig | None = None,
+) -> Callable:
+    """Decorator: capture function return value and emit a pytest fixture."""
+    def decorator(fn: Callable) -> Callable:
+        if asyncio.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def async_wrapper(*args, **kwargs):
+                result = await fn(*args, **kwargs)
+                _record(name, result, scrub, max_depth, max_size_bytes, config)
+                return result
+            return async_wrapper
+        else:
+            @functools.wraps(fn)
+            def sync_wrapper(*args, **kwargs):
+                result = fn(*args, **kwargs)
+                _record(name, result, scrub, max_depth, max_size_bytes, config)
+                return result
+            return sync_wrapper
+    return decorator
+
+
+def _record(name, obj, extra_scrub, max_depth, max_size_bytes, cfg_override):
+    cfg = _get_config(cfg_override)
+    if not cfg.enabled:
+        return
+    effective_depth = max_depth if max_depth is not None else cfg.max_depth
+    effective_size  = max_size_bytes if max_size_bytes is not None else cfg.max_size_bytes
+    scrub_fields = list(cfg.default_scrub_fields)
+    if extra_scrub:
+        scrub_fields = list(set(scrub_fields) | set(extra_scrub))
+
+    serializer = SnapfixSerializer(max_depth=effective_depth, max_size_bytes=effective_size)
+    scrubber   = SnapfixScrubber(scrub_fields)
+    codegen    = SnapfixCodegen()
+    store      = SnapfixStore(cfg.output_dir)
+
+    try:
+        serialized = serializer.serialize(obj)
+        scrubbed, scrubbed_keys = scrubber.scrub(serialized)
+        source = codegen.generate(
+            name=name,
+            data=scrubbed,
+            scrubbed_fields=scrubbed_keys,
+            captured_at=datetime.datetime.utcnow(),
+        )
+        store.write(name, source, {
+            "scrubbed_fields": scrubbed_keys,
+            "captured_at": str(datetime.datetime.utcnow()),
+        })
+    except Exception as e:
+        warnings.warn(f"snapfix: failed to capture '{name}': {e}", stacklevel=3)

snapfix/cli.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import pathlib
+
+import typer
+
+from snapfix.config import SnapfixConfig
+from snapfix.store import SnapfixStore
+
+app = typer.Typer(
+    name="snapfix",
+    help="Capture real Python objects, scrub PII, emit pytest fixtures.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _store(output_dir: pathlib.Path | None = None) -> SnapfixStore:
+    cfg = SnapfixConfig.from_env()
+    return SnapfixStore(output_dir or cfg.output_dir)
+
+
+@app.command("list")
+def list_fixtures(
+    output_dir: pathlib.Path | None = typer.Option(
+        None, "--dir", "-d", help="Fixture output directory (default: from config)."
+    ),
+) -> None:
+    """List all captured fixtures."""
+    store   = _store(output_dir)
+    entries = store.list()
+    if not entries:
+        typer.echo("No fixtures captured yet.")
+        raise typer.Exit(0)
+    for e in entries:
+        path     = e.get("path", "?")
+        scrubbed = e.get("scrubbed_fields", [])
+        captured = e.get("captured_at", "")
+        typer.echo(f"  {path}")
+        if captured:
+            typer.echo(f"    captured : {captured}")
+        if scrubbed:
+            typer.echo(f"    scrubbed : {', '.join(scrubbed)}")
+
+
+@app.command("show")
+def show_fixture(
+    name: str = typer.Argument(..., help="Fixture name (without snapfix_ prefix)."),
+    output_dir: pathlib.Path | None = typer.Option(None, "--dir", "-d"),
+) -> None:
+    """Print a captured fixture to stdout."""
+    store = _store(output_dir)
+    idx   = store._load_index()
+    if name not in idx:
+        typer.echo(f"No fixture named '{name}'.", err=True)
+        raise typer.Exit(1)
+    p = pathlib.Path(idx[name]["path"])
+    if not p.exists():
+        typer.echo(f"File missing: {p}", err=True)
+        raise typer.Exit(1)
+    typer.echo(p.read_text())
+
+
+@app.command("clear")
+def clear_fixture(
+    name: str = typer.Argument(..., help="Fixture name to delete."),
+    output_dir: pathlib.Path | None = typer.Option(None, "--dir", "-d"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Delete a captured fixture."""
+    store = _store(output_dir)
+    if not store.exists(name):
+        typer.echo(f"No fixture named '{name}'.", err=True)
+        raise typer.Exit(1)
+    if not yes:
+        typer.confirm(f"Delete fixture '{name}'?", abort=True)
+    deleted = store.delete(name)
+    typer.echo(f"Deleted '{name}': {deleted}")
+
+
+@app.command("clear-all")
+def clear_all(
+    output_dir: pathlib.Path | None = typer.Option(None, "--dir", "-d"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Delete all captured fixtures."""
+    store   = _store(output_dir)
+    entries = store.list()
+    if not entries:
+        typer.echo("Nothing to clear.")
+        raise typer.Exit(0)
+    if not yes:
+        typer.confirm(f"Delete all {len(entries)} fixture(s)?", abort=True)
+    for e in entries:
+        name = pathlib.Path(e["path"]).stem.removeprefix("snapfix_")
+        store.delete(name)
+    typer.echo(f"Cleared {len(entries)} fixture(s).")

snapfix/codegen.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import ast
+import datetime
+import re
+import textwrap
+from typing import Any
+
+_FIXTURE_HEADER = (
+    "# Generated by snapfix -- do not edit manually\n"
+    "# Regenerate: re-run the @snapfix.capture decorated function\n"
+    "# Captured : {captured_at}\n"
+    "# Scrubbed : {scrubbed_fields}\n"
+    "import pytest\n"
+    "from snapfix import reconstruct\n"
+    "\n"
+)
+
+
+def _to_literal(obj: Any, indent: int = 2) -> str:
+    """Render a JSON-serialisable object as a pretty-printed Python literal."""
+    ind = " " * indent
+    if obj is None:
+        return "None"
+    if isinstance(obj, bool):
+        return "True" if obj else "False"
+    if isinstance(obj, (int, float, str)):
+        return repr(obj)
+    if isinstance(obj, list):
+        if not obj:
+            return "[]"
+        items = ",\n".join(ind + "    " + _to_literal(x, indent + 4) for x in obj)
+        return "[\n" + items + ",\n" + ind + "]"
+    if isinstance(obj, dict):
+        if not obj:
+            return "{}"
+        parts = []
+        for k, v in obj.items():
+            parts.append(ind + "    " + repr(k) + ": " + _to_literal(v, indent + 4))
+        return "{\n" + ",\n".join(parts) + ",\n" + ind + "}"
+    return repr(obj)
+
+
+class SnapfixCodegen:
+    def generate(
+        self,
+        name: str,
+        data: Any,
+        scrubbed_fields: list[str],
+        captured_at: datetime.datetime,
+    ) -> str:
+        fn_name = _sanitize(name)
+        header = _FIXTURE_HEADER.format(
+            captured_at=captured_at.isoformat(),
+            scrubbed_fields=", ".join(scrubbed_fields) or "none",
+        )
+        body = _to_literal(data)
+        source = (
+            header
+            + "@pytest.fixture\n"
+            + f"def {fn_name}():\n"
+            + "    return reconstruct(\n"
+            + textwrap.indent(body, "        ")
+            + "\n    )\n"
+        )
+        try:
+            ast.parse(source)
+        except SyntaxError as e:
+            raise ValueError(f"Generated invalid Python source: {e}") from e
+        return source
+
+
+def _sanitize(name: str) -> str:
+    s = re.sub(r"[^a-zA-Z0-9_]", "_", name)
+    if s and s[0].isdigit():
+        s = "_" + s
+    return s or "_unnamed"

snapfix/config.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import os
+import pathlib
+from dataclasses import dataclass, field
+
+import yaml
+
+DEFAULT_SCRUB_FIELDS: list[str] = [
+    "email","password","passwd","token","secret","api_key","apikey",
+    "access_token","refresh_token","ssn","credit_card","card_number",
+    "cvv","phone","mobile","dob","date_of_birth","address","ip_address",
+    "authorization","auth","bearer",
+]
+
+@dataclass
+class SnapfixConfig:
+    output_dir: pathlib.Path = pathlib.Path("tests/fixtures")
+    default_scrub_fields: list[str] = field(default_factory=lambda: list(DEFAULT_SCRUB_FIELDS))
+    max_depth: int = 10
+    max_size_bytes: int = 500_000
+    enabled: bool = True
+
+    @classmethod
+    def from_env(cls) -> SnapfixConfig:
+        return cls(
+            output_dir=pathlib.Path(os.environ.get("SNAPFIX_OUTPUT_DIR", "tests/fixtures")),
+            max_depth=int(os.environ.get("SNAPFIX_MAX_DEPTH", 10)),
+            max_size_bytes=int(os.environ.get("SNAPFIX_MAX_SIZE", 500_000)),
+            enabled=os.environ.get("SNAPFIX_ENABLED", "true").lower() != "false",
+        )
+
+    @classmethod
+    def from_yaml(cls, path: pathlib.Path) -> SnapfixConfig:
+        if not path.exists():
+            return cls.from_env()
+        try:
+            data = yaml.safe_load(path.read_text()) or {}
+        except Exception:
+            return cls.from_env()
+        sf = data.get("snapfix", {})
+        cfg = cls.from_env()
+        if "output_dir" in sf:
+            cfg.output_dir = pathlib.Path(sf["output_dir"])
+        if "max_depth" in sf:
+            cfg.max_depth = int(sf["max_depth"])
+        if "max_size_bytes" in sf:
+            cfg.max_size_bytes = int(sf["max_size_bytes"])
+        if "enabled" in sf:
+            cfg.enabled = bool(sf["enabled"])
+        return cfg

snapfix/reconstruct.py

@@ -0,0 +1,8 @@
+from snapfix.serializer import SnapfixSerializer
+
+_global_serializer = SnapfixSerializer()
+
+
+def reconstruct(data):
+    """Restore __snapfix_type__ markers in a captured fixture to Python types."""
+    return _global_serializer.deserialize(data)

snapfix/scrubber.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+
+_SCRUBBED_STR = "***SCRUBBED***"
+_SCRUBBED_NUM = -1
+
+
+class SnapfixScrubber:
+    def __init__(self, fields: list[str], *, numeric_replacement: int = _SCRUBBED_NUM):
+        self._fields = [f.lower() for f in fields]
+        self._numeric_replacement = numeric_replacement
+
+    def _is_sensitive(self, key: str) -> bool:
+        k = str(key).lower()
+        return any(f in k for f in self._fields)
+
+    def _scrub_value(self, value: Any) -> Any:
+        if isinstance(value, (int, float)):
+            return self._numeric_replacement
+        return _SCRUBBED_STR
+
+    def scrub(self, data: Any, _scrubbed: list[str] | None = None) -> tuple[Any, list[str]]:
+        """Returns (scrubbed_copy, list_of_scrubbed_key_paths).
+        Does NOT mutate the input.
+        """
+        top_level = _scrubbed is None
+        if top_level:
+            _scrubbed = []
+        result = self._scrub_node(data, _scrubbed, path="")
+        return result, _scrubbed
+
+    def _scrub_node(self, data: Any, scrubbed: list[str], path: str) -> Any:
+        if isinstance(data, dict):
+            out = {}
+            for k, v in data.items():
+                key_path = f"{path}.{k}" if path else str(k)
+                if self._is_sensitive(k):
+                    out[k] = self._scrub_value(v)
+                    scrubbed.append(key_path)
+                else:
+                    out[k] = self._scrub_node(v, scrubbed, key_path)
+            return out
+        if isinstance(data, list):
+            return [
+                self._scrub_node(item, scrubbed, f"{path}[{i}]")
+                for i, item in enumerate(data)
+            ]
+        return data

snapfix/serializer.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import base64
+import dataclasses
+import datetime
+import decimal
+import enum
+import json
+import math
+import pathlib
+import uuid
+from typing import Any
+
+_MARKER = "__snapfix_type__"
+_UNSZ   = "__snapfix_unserializable__"
+_CIRC   = "__snapfix_circular__"
+_TRUNC  = "__snapfix_truncated__"
+_DEPTH  = "__snapfix_maxdepth__"
+
+
+class SnapfixSerializer:
+    def __init__(self, max_depth: int = 10, max_size_bytes: int = 500_000):
+        self.max_depth = max_depth
+        self.max_size_bytes = max_size_bytes
+        self._size_counter = 0
+
+    def serialize(self, obj: Any, _depth: int = 0, _seen: set | None = None) -> Any:
+        if _seen is None:
+            _seen = set()
+            self._size_counter = 0
+
+        result = self._dispatch(obj, _depth, _seen)
+
+        try:
+            self._size_counter += len(json.dumps(result, default=str))
+        except Exception:
+            self._size_counter += 1024
+        if self._size_counter > self.max_size_bytes:
+            return {_TRUNC: True, "__snapfix_size__": self._size_counter}
+
+        return result
+
+    def _dispatch(self, obj: Any, depth: int, seen: set) -> Any:
+        # depth guard (also in serialize() but _dispatch calls itself directly)
+        if depth > self.max_depth:
+            return {_DEPTH: True, "__snapfix_repr__": repr(obj)[:200]}
+        # circular reference guard — must be per-_dispatch call, not just in serialize()
+        if isinstance(obj, (dict, list, tuple, set, frozenset)):
+            try:
+                obj_id = id(obj)
+                if obj_id in seen:
+                    return {_CIRC: True}
+                seen.add(obj_id)
+            except Exception:
+                pass
+        # Singletons / primitives
+        if obj is None or isinstance(obj, bool):
+            return obj
+        if isinstance(obj, int):
+            return obj
+        if isinstance(obj, str):
+            return obj
+        if isinstance(obj, float):
+            if math.isnan(obj):
+                return {_MARKER: "float", "value": "nan"}
+            if math.isinf(obj):
+                return {_MARKER: "float", "value": "inf" if obj > 0 else "-inf"}
+            return obj
+        if isinstance(obj, datetime.datetime):
+            return {_MARKER: "datetime", "value": obj.isoformat()}
+        if isinstance(obj, datetime.date):
+            return {_MARKER: "date", "value": obj.isoformat()}
+        if isinstance(obj, datetime.time):
+            return {_MARKER: "time", "value": obj.isoformat()}
+        if isinstance(obj, datetime.timedelta):
+            return {_MARKER: "timedelta", "value": obj.total_seconds()}
+        if isinstance(obj, uuid.UUID):
+            return {_MARKER: "uuid", "value": str(obj)}
+        if isinstance(obj, decimal.Decimal):
+            return {_MARKER: "decimal", "value": str(obj)}
+        if isinstance(obj, bytes):
+            return {_MARKER: "bytes", "value": base64.b64encode(obj).decode()}
+        if isinstance(obj, bytearray):
+            return {_MARKER: "bytearray", "value": base64.b64encode(bytes(obj)).decode()}
+        if isinstance(obj, pathlib.PurePath):
+            return {_MARKER: "path", "value": str(obj)}
+        if isinstance(obj, enum.Enum):
+            return {_MARKER: "enum", "cls": type(obj).__name__,
+                    "value": self._dispatch(obj.value, depth + 1, seen)}
+        if isinstance(obj, (set, frozenset)):
+            tag = "frozenset" if isinstance(obj, frozenset) else "set"
+            try:
+                items = sorted([self._dispatch(x, depth + 1, seen) for x in obj], key=str)
+            except TypeError:
+                items = [self._dispatch(x, depth + 1, seen) for x in obj]
+            return {_MARKER: tag, "value": items}
+        if isinstance(obj, tuple):
+            return {_MARKER: "tuple",
+                    "value": [self._dispatch(x, depth + 1, seen) for x in obj]}
+        if isinstance(obj, list):
+            return [self._dispatch(x, depth + 1, seen) for x in obj]
+        if isinstance(obj, dict):
+            return {str(k): self._dispatch(v, depth + 1, seen) for k, v in obj.items()}
+        if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+            try:
+                return self._dispatch(dataclasses.asdict(obj), depth, seen)
+            except Exception:
+                pass
+        # pydantic v2
+        try:
+            return self._dispatch(obj.model_dump(), depth, seen)
+        except AttributeError:
+            pass
+        # pydantic v1
+        try:
+            return self._dispatch(obj.dict(), depth, seen)
+        except AttributeError:
+            pass
+        # __dict__ fallback
+        try:
+            return self._dispatch(vars(obj), depth, seen)
+        except TypeError:
+            pass
+        return {_UNSZ: True, "__snapfix_repr__": repr(obj)[:200],
+                "__snapfix_type_name__": type(obj).__name__}
+
+    def deserialize(self, data: Any) -> Any:
+        if data is None or isinstance(data, (bool, int, float, str)):
+            return data
+        if isinstance(data, list):
+            return [self.deserialize(x) for x in data]
+        if isinstance(data, dict):
+            marker = data.get(_MARKER)
+            if marker == "datetime":
+                return datetime.datetime.fromisoformat(data["value"])
+            if marker == "date":
+                return datetime.date.fromisoformat(data["value"])
+            if marker == "time":
+                return datetime.time.fromisoformat(data["value"])
+            if marker == "timedelta":
+                return datetime.timedelta(seconds=float(data["value"]))
+            if marker == "uuid":
+                return uuid.UUID(data["value"])
+            if marker == "decimal":
+                return decimal.Decimal(data["value"])
+            if marker == "bytes":
+                return base64.b64decode(data["value"].encode())
+            if marker == "bytearray":
+                return bytearray(base64.b64decode(data["value"].encode()))
+            if marker == "path":
+                return pathlib.Path(data["value"])
+            if marker == "enum":
+                return self.deserialize(data["value"])
+            if marker in ("set", "frozenset"):
+                items = [self.deserialize(x) for x in data["value"]]
+                return frozenset(items) if marker == "frozenset" else set(items)
+            if marker == "tuple":
+                # Tuples become lists on roundtrip — documented behavior matching JSON's type system
+                return [self.deserialize(x) for x in data["value"]]
+            if marker == "float":
+                v = data["value"]
+                return float("nan") if v == "nan" else float(v)
+            if any(k in data for k in (_UNSZ, _CIRC, _TRUNC, _DEPTH)):
+                return data
+            return {k: self.deserialize(v) for k, v in data.items()}
+        return data

snapfix/store.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import builtins
+import json
+import pathlib
+import re
+from typing import Any
+
+
+class SnapfixStore:
+    def __init__(self, output_dir: pathlib.Path):
+        self.output_dir = pathlib.Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self._index_path = self.output_dir / ".snapfix_index.json"
+
+    def _load_index(self) -> dict:
+        if self._index_path.exists():
+            try:
+                return json.loads(self._index_path.read_text())
+            except Exception:
+                return {}
+        return {}
+
+    def _save_index(self, idx: dict):
+        tmp = self._index_path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(idx, indent=2, default=str))
+        tmp.replace(self._index_path)
+
+    def write(self, name: str, source: str, metadata: dict[str, Any]) -> pathlib.Path:
+        safe = _sanitize(name)
+        path = self.output_dir / f"snapfix_{safe}.py"
+        tmp  = path.with_suffix(".tmp")
+        tmp.write_text(source, encoding="utf-8")
+        tmp.replace(path)
+        idx = self._load_index()
+        idx[name] = {"path": str(path), **metadata}
+        self._save_index(idx)
+        return path
+
+    def list(self) -> builtins.list[dict]:
+        return list(self._load_index().values())
+
+    def exists(self, name: str) -> bool:
+        return name in self._load_index()
+
+    def delete(self, name: str) -> bool:
+        idx = self._load_index()
+        entry = idx.pop(name, None)
+        if entry and pathlib.Path(entry["path"]).exists():
+            pathlib.Path(entry["path"]).unlink()
+        self._save_index(idx)
+        return entry is not None
+
+
+def _sanitize(name: str) -> str:
+    s = re.sub(r"[^a-zA-Z0-9_]", "_", name)
+    return ("_" + s) if s and s[0].isdigit() else s or "_unnamed"

snapfix-0.1.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: snapfix
+Version: 0.1.0
+Summary: Capture real Python objects, scrub sensitive fields, emit pytest fixtures.
+Project-URL: Homepage, https://github.com/yourname/snapfix
+Project-URL: Documentation, https://github.com/yourname/snapfix#readme
+Project-URL: Issues, https://github.com/yourname/snapfix/issues
+Project-URL: Changelog, https://github.com/yourname/snapfix/blob/main/CHANGELOG.md
+License: MIT
+License-File: LICENSE
+Keywords: capture,fixtures,pii,pytest,scrubbing,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pydantic>=2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# snapfix
+
+**Capture real Python objects from staging, scrub sensitive fields, emit `@pytest.fixture` files automatically.**
+
+---
+
+## The problem
+
+You have a bug that only reproduces with real data. You need a test. You don't want to hand-build a factory that misses the edge case, and you don't want to copy-paste a production payload and accidentally commit a customer's email address.
+
+snapfix solves this with one decorator.
+
+---
+
+## Install
+
+```bash
+pip install snapfix
+```
+
+Python 3.10+ required. No other required dependencies.
+
+---
+
+## Quickstart
+
+```python
+# In your service code (staging or development only)
+from snapfix import capture
+
+@capture("invoice_response", scrub=["billing_name"])
+def fetch_invoice(invoice_id: str) -> dict:
+    return external_api.get(f"/invoices/{invoice_id}")
+```
+
+Call the function once against staging. snapfix writes this to `tests/fixtures/snapfix_invoice_response.py`:
+
+```python
+# Generated by snapfix -- do not edit manually
+# Captured : 2026-03-23T14:22:01
+# Scrubbed : customer.email, meta.token, billing_name
+import pytest
+from snapfix import reconstruct
+
+@pytest.fixture
+def invoice_response():
+    return reconstruct({
+        "id": "INV-8821",
+        "customer": {
+            "email": "***SCRUBBED***",
+            "billing_name": "***SCRUBBED***",
+            "plan": "pro",
+        },
+        "amount": {"__snapfix_type__": "decimal", "value": "149.99"},
+        "issued_at": {"__snapfix_type__": "datetime", "value": "2026-03-01T09:00:00"},
+        "meta": {
+            "token": "***SCRUBBED***",
+            "retry": 0,
+        },
+    })
+```
+
+Use it in any test:
+
+```python
+def test_invoice_total(invoice_response):
+    assert invoice_response["amount"].quantize(Decimal("0.01")) == Decimal("149.99")
+```
+
+That's it. No factory definition. No manual scrubbing. No pasted JSON.
+
+---
+
+## PII scrubbing
+
+> **⚠ Important limitation:** snapfix scrubs fields by **key name only**. It does NOT detect PII
+> in field values. An email address stored as `response["tags"][0]` or inside a list
+> will **not** be scrubbed. Always review generated fixtures before committing them.
+
+### Default scrubbed field names
+
+Any key whose name contains one of these strings (case-insensitive, substring match) is scrubbed:
+
+`email` · `password` · `passwd` · `token` · `secret` · `api_key` · `apikey` ·
+`access_token` · `refresh_token` · `ssn` · `credit_card` · `card_number` ·
+`cvv` · `phone` · `mobile` · `dob` · `date_of_birth` · `address` ·
+`ip_address` · `authorization` · `auth` · `bearer`
+
+`customer_email` → scrubbed (substring match on `email`)  
+`billing_phone_number` → scrubbed (substring match on `phone`)  
+`retry_count` → **not** scrubbed
+
+### Adding custom fields
+
+```python
+@capture("order", scrub=["customer_id", "tax_number"])
+def fetch_order(order_id: str) -> dict: ...
+```
+
+### Replacement values
+
+| Field value type | Replacement |
+|---|---|
+| `str` | `"***SCRUBBED***"` |
+| `int` / `float` | `-1` |
+| `None` | `"***SCRUBBED***"` |
+
+---
+
+## Supported types
+
+snapfix serializes the following Python types and restores them correctly via `reconstruct()`:
+
+| Type | Serialized as | Restored on `reconstruct()` |
+|---|---|---|
+| `dict`, `list`, `str`, `int`, `float`, `bool`, `None` | JSON native | Same |
+| `datetime.datetime` | ISO 8601 string + marker | `datetime` |
+| `datetime.date` | ISO 8601 string + marker | `date` |
+| `datetime.time` | ISO 8601 string + marker | `time` |
+| `datetime.timedelta` | total seconds + marker | `timedelta` |
+| `uuid.UUID` | string + marker | `UUID` |
+| `decimal.Decimal` | string + marker | `Decimal` |
+| `bytes` | base64 + marker | `bytes` |
+| `bytearray` | base64 + marker | `bytearray` |
+| `pathlib.Path` | string + marker | `Path` |
+| `enum.Enum` | `.value` + marker | value only (enum class not preserved) |
+| `tuple` | list + marker | `list` (documented: tuples become lists) |
+| `set` / `frozenset` | sorted list + marker | `set` / `frozenset` |
+| `dataclass` | `dataclasses.asdict()` then recurse | `dict` |
+| `pydantic.BaseModel` | `.model_dump()` then recurse | `dict` |
+| Circular reference | `{"__snapfix_circular__": true}` | sentinel dict |
+| Unserializable type | `{"__snapfix_unserializable__": true, ...}` | sentinel dict |
+
+> **Note:** `tuple` → `list` on roundtrip is intentional. JSON has no tuple type.
+> If your tests depend on the exact type, assert `isinstance(result, list)` rather than `tuple`.
+
+---
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SNAPFIX_OUTPUT_DIR` | `tests/fixtures` | Where fixture files are written |
+| `SNAPFIX_MAX_DEPTH` | `10` | Maximum serialization depth |
+| `SNAPFIX_MAX_SIZE` | `500000` | Maximum payload size in bytes |
+| `SNAPFIX_ENABLED` | `true` | Set to `false` to disable all capture |
+
+### `snapfix.yaml` (project root)
+
+```yaml
+snapfix:
+  output_dir: tests/fixtures
+  max_depth: 10
+  max_size_bytes: 500000
+  enabled: true
+```
+
+### Priority order (highest to lowest)
+
+1. Decorator parameters: `@capture(name, scrub=[...], max_depth=5)`
+2. Environment variables
+3. `snapfix.yaml`
+4. Built-in defaults
+
+### Disabling in production
+
+Set `SNAPFIX_ENABLED=false` in your production environment. The decorator becomes a no-op — zero overhead, no files written, no exceptions swallowed.
+
+---
+
+## CLI
+
+```
+snapfix list              # List all captured fixtures with metadata
+snapfix show  <name>      # Print a fixture to stdout
+snapfix clear <name>      # Delete one fixture (prompts for confirmation)
+snapfix clear-all         # Delete all fixtures (prompts for confirmation)
+```
+
+All commands accept `--dir <path>` to target a non-default fixture directory.
+
+---
+
+## Decorator reference
+
+```python
+@capture(
+    name,                # str — fixture name; becomes the function name in the output file
+    scrub=None,          # list[str] | None — extra field names to scrub (merged with defaults)
+    max_depth=None,      # int | None — override max serialization depth
+    max_size_bytes=None, # int | None — override max payload size
+    config=None,         # SnapfixConfig | None — full config override
+)
+```
+
+Works on both **sync** and **async** functions. The decorator is transparent:
+
+- The return value is always preserved unchanged.
+- If the wrapped function raises, the exception propagates normally and **no file is written**.
+- If serialization fails for any reason, a `warnings.warn()` is emitted and execution continues.
+
+---
+
+## FAQ
+
+**Is it safe to use against production traffic?**
+No. Use snapfix against staging or a development environment. Production traffic contains real customer data. Even with scrubbing enabled, value-level PII (email addresses in list fields, etc.) will not be caught.
+
+**Does it slow down my application?**
+Serialization adds latency proportional to payload size. For typical API responses (< 50 KB), the overhead is negligible in staging. Do not enable `SNAPFIX_ENABLED=true` in a production critical path.
+
+**What happens if the object is too large?**
+If the serialized payload exceeds `max_size_bytes`, the fixture is not written and a warning is emitted. Increase `SNAPFIX_MAX_SIZE` or add depth limiting with `max_depth`.
+
+**What happens if a field contains an unserializable type?**
+It is replaced with a sentinel dict: `{"__snapfix_unserializable__": true, "__snapfix_repr__": "...", "__snapfix_type_name__": "..."}`. The rest of the object is still captured. `reconstruct()` returns the sentinel as-is.
+
+**Can I regenerate a fixture?**
+Yes. Re-run the decorated function. The fixture file is overwritten in place.
+
+**Does it work with pytest parametrize?**
+The generated file is a standard `@pytest.fixture`. It works with everything pytest supports.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/yourname/snapfix
+cd snapfix
+pip install -e ".[dev]"
+pytest
+ruff check src/
+```
+
+---
+
+## License
+
+MIT

snapfix-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+snapfix/__init__.py,sha256=Bzr3NPmzBsIXucS5Z0TIkluupKQfwWVYoxazUwpZTMU,244
+snapfix/capture.py,sha256=JD2nk7yycb40WY2kWefnIqdH3grgm95dMQkqlebAcxE,2911
+snapfix/cli.py,sha256=f-yO_hM8e1lUpiuw8R_CM8n-2h36oH9GQo84mSAS3KI,3103
+snapfix/codegen.py,sha256=21mqrE61M20evmH2_YuO7NrXQ5kSq8qKWIusm5CcNeI,2222
+snapfix/config.py,sha256=2nsPZCNkC3YkgHQttbn-O5tEk9y10UpvcSo2B4cMXlU,1782
+snapfix/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+snapfix/reconstruct.py,sha256=yeW6v1TrGj_kp05cwOumfk3WVMbw3cWN2fmxtGuk-tc,246
+snapfix/scrubber.py,sha256=27UdoQEyE2dwrCmD18TfH4SY5y5sRowaqVhi7R0PczY,1696
+snapfix/serializer.py,sha256=eKKqV4A_wVVQ0Uf1491FqYRV3v5jO1fiDEtEZBMe9Vs,6885
+snapfix/store.py,sha256=asdWzSDjoA7qWbRFBhMkad0SuJlwEKE0uqAJfb_zysw,1808
+snapfix-0.1.0.dist-info/METADATA,sha256=BpXFJDvxsX2VtGNriW-AY-D0xKOzniMiMMMfm-_nD28,9314
+snapfix-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+snapfix-0.1.0.dist-info/entry_points.txt,sha256=BoQGQT91XVV6iFkvWWM4LLczC1XPf42t2xN-0xJUaAg,44
+snapfix-0.1.0.dist-info/licenses/LICENSE,sha256=9DgUw9Co75aF5aXEMg2R_xTrOh9cqo0bTsVPuMAC0Mg,1077
+snapfix-0.1.0.dist-info/RECORD,,

snapfix-0.1.0.dist-info/WHEEL

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

snapfix-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+snapfix = snapfix.cli:app

snapfix-0.1.0.dist-info/licenses/LICENSE

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