wrapture 1.0.0.dev1__py3-none-any.whl

wrapture/capture.py

@@ -0,0 +1,165 @@
+"""Capture policies: how much of a call's values recording stores.
+
+Recording by reference is free but can lie retroactively: mutate a list
+after the call and the tape shows the mutated list. Copying everything
+is safe but costly, and calling repr() on arbitrary values can itself
+have side effects. So capture is a policy, chosen per binding or
+declared by the sink consuming the events.
+
+A policy is either one of the levels below, ordered by cost, or a
+callable fn(name, value) -> stored applied to each captured value:
+
+    NONE        no arguments, no result; skips signature binding
+    TYPES       type names only; never calls user code
+    REFERENCE   store references (what unittest.mock does); the default
+    SUMMARY     bounded repr; survives locks and sockets, retains nothing
+    SNAPSHOT    deepcopy; highest fidelity, falls back where it raises
+
+The safe levels are the ones that call no user code: NONE, TYPES and
+REFERENCE cannot trigger anything, while SUMMARY and SNAPSHOT execute
+methods on the values being captured, which may be slow, may raise, and
+may have effects. That is why REFERENCE is the default.
+"""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Callable
+from typing import Any
+
+NONE = 0
+TYPES = 1
+REFERENCE = 2
+SUMMARY = 3
+SNAPSHOT = 4
+
+CapturePolicy = int | Callable[[str | None, Any], Any]
+
+_ATOMIC = (bool, int, float, complex, type(None))
+
+
+def type_name(value: Any) -> str:
+    """The safest possible capture: a type name, calling no user code.
+
+    repr() can have side effects (a lazy ORM object may issue a query),
+    so tracing with SUMMARY can cause the very behaviour being traced.
+    TYPES is immune because it touches nothing but the class.
+    """
+
+    return f"<{type(value).__name__}>"
+
+
+def summarize(value: Any, *, limit: int = 200, items: int = 10) -> Any:
+    """Bounded repr. Never raises, never retains the original.
+
+    Type-aware for the common containers, because a naive
+    repr(value)[:limit] materialises the whole repr before truncating:
+    a 5MB repr costs 5MB and milliseconds even though the output is 200
+    bytes. Handling str, bytes and the container types structurally
+    bounds the work as well as the result.
+
+    Unavoidably, the fallback for unknown types calls repr(), which is
+    user code: it may be slow and may have side effects. Use TYPES where
+    that matters.
+    """
+
+    if isinstance(value, _ATOMIC):
+        return value
+
+    if isinstance(value, (str, bytes)):
+        if len(value) > limit:
+            if isinstance(value, bytes):
+                return value[:limit] + b"..."
+            return value[:limit] + f"...+{len(value) - limit}"
+        return value
+
+    if isinstance(value, (list, tuple, set, frozenset)):
+        kind = type(value).__name__
+        shown = [
+            summarize(v, limit=limit // 4, items=items) for v in list(value)[:items]
+        ]
+        more = f", +{len(value) - items}" if len(value) > items else ""
+        return f"<{kind} {shown!r}{more}>"
+
+    if isinstance(value, dict):
+        shown_items = {
+            k: summarize(v, limit=limit // 4, items=items)
+            for k, v in list(value.items())[:items]
+        }
+        more = f", +{len(value) - items}" if len(value) > items else ""
+        return f"<dict {shown_items!r}{more}>"
+
+    try:
+        text = repr(value)
+    except Exception as exc:
+        return f"<unreprable {type(value).__name__}: {type(exc).__name__}>"
+
+    if len(text) > limit:
+        return text[:limit] + f"...+{len(text) - limit}"
+    return text
+
+
+def redact(
+    *names: str, level: CapturePolicy = REFERENCE, marker: str = "<redacted>"
+) -> CapturePolicy:
+    """A capture policy that replaces named parameters with a marker.
+
+        binding(Gateway, "charge", capture_args=redact("card_number"))
+
+    Matching is by parameter name against the signature-normalized
+    arguments, so it works whether the caller passed the value
+    positionally or by keyword. Everything not named is captured at
+    `level`.
+
+    Two limits: results have no parameter name, so a bare redact() does
+    not touch them (pair it with capture_result=NONE when the secret
+    comes back out); and names are top-level parameters only, so a
+    secret nested inside a dict argument is not found. Any custom
+    fn(name, value) callable handles those cases.
+    """
+
+    wanted = set(names)
+
+    def policy(name: str | None, value: Any) -> Any:
+        if name in wanted:
+            return marker
+        return _capture_value(level, name, value)
+
+    policy.level = _level_of(level)  # type: ignore[attr-defined]
+    return policy
+
+
+def _level_of(policy: CapturePolicy) -> int:
+    # A policy is an int level or a callable carrying one; a callable
+    # without a declared level is assumed to want normalized arguments.
+
+    if callable(policy):
+        return int(getattr(policy, "level", REFERENCE))
+    return policy
+
+
+def _capture_value(policy: CapturePolicy, name: str | None, value: Any) -> Any:
+    if callable(policy):
+        return policy(name, value)
+    return _apply_capture(policy, value)
+
+
+def _apply_capture(level: int, value: Any) -> Any:
+    if level == TYPES:
+        return type_name(value)
+
+    if level >= SNAPSHOT:
+        # deepcopy fails on locks, sockets, file handles and connections,
+        # which are common arguments. Failing the call under test because
+        # the recorder could not copy an argument would be indefensible,
+        # so fall back to the bounded repr instead.
+
+        try:
+            return copy.deepcopy(value)
+        except Exception:
+            return summarize(value)
+
+    if level == SUMMARY:
+        return summarize(value)
+
+    return value

wrapture/eventlogs.py

@@ -0,0 +1,232 @@
+"""The filterable view over recorded events.
+
+One naming rule, without exception, on every object in this package: a
+method whose name starts with assert_ raises on failure; everything else
+returns data. The filters here narrow and return a new log, never raise,
+so a mismatched filter yields an empty log rather than an error. Each
+narrowed log remembers what it was filtered from, so failure output can
+show the events a filter discarded instead of a bare empty result.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from typing import Any
+
+from wrapt import MISSING
+
+from .events import Event
+
+
+class EventLog:
+    """An immutable, filterable view over recorded events.
+
+    Filters return a narrowed EventLog and never raise. The data
+    accessors make a log usable directly in a bare assert: an empty log
+    is falsey, and repr() prints the events it holds.
+    """
+
+    def __init__(
+        self,
+        label: str,
+        events: list[Event],
+        *,
+        filtered_from: EventLog | None = None,
+    ) -> None:
+        self._label = label
+        self._events = list(events)
+        self._filtered_from = filtered_from
+
+    @property
+    def label(self) -> str:
+        """The log's provenance: the binding label plus one bracketed
+        segment per filter applied."""
+
+        return self._label
+
+    def _narrow(self, suffix: str, keep: Callable[[Event], bool]) -> EventLog:
+        kept = [event for event in self._events if keep(event)]
+        return EventLog(f"{self._label}{suffix}", kept, filtered_from=self)
+
+    # -- filters: return a narrowed log, never raise -------------------------
+
+    def of_kind(self, *kinds: str) -> EventLog:
+        """Events of the given kind or kinds: "call", "get", "set" or
+        "delete"."""
+
+        wanted = set(kinds)
+        return self._narrow(f"[{','.join(kinds)}]", lambda event: event.kind in wanted)
+
+    def matching(self, predicate: Callable[[Event], bool]) -> EventLog:
+        """Events for which the predicate returns true."""
+
+        name = getattr(predicate, "__name__", "predicate")
+        return self._narrow(f"[matching={name}]", lambda event: bool(predicate(event)))
+
+    def raising(self, *exceptions: type[BaseException]) -> EventLog:
+        """Events that raised one of the given exception types, or, with
+        no arguments, events that raised anything at all."""
+
+        if not exceptions:
+            return self._narrow("[raising]", lambda event: event.exception is not None)
+
+        names = ",".join(exception.__name__ for exception in exceptions)
+        return self._narrow(
+            f"[raising={names}]",
+            lambda event: isinstance(event.exception, exceptions),
+        )
+
+    def with_args(self, **arguments: Any) -> EventLog:
+        """Call events whose normalized arguments include every given
+        name and value.
+
+        Matching is by parameter name against the signature-normalized
+        arguments with defaults applied, so with_args(currency="USD")
+        matches a call that never spelled the default out. Events with
+        no normalized arguments, attribute events included, never match.
+        """
+
+        suffix = "[" + ", ".join(f"{k}={v!r}" for k, v in arguments.items()) + "]"
+
+        def keep(event: Event) -> bool:
+            if event.arguments is None:
+                return False
+
+            return all(
+                name in event.arguments and event.arguments[name] == value
+                for name, value in arguments.items()
+            )
+
+        return self._narrow(suffix, keep)
+
+    def returning(self, value: Any) -> EventLog:
+        """Events whose recorded outcome equals the value: the return
+        value of a call, or the value a read produced. Events that
+        raised have no outcome and never match."""
+
+        return self._narrow(
+            f"[returning={value!r}]",
+            lambda event: event.result is not MISSING and event.result == value,
+        )
+
+    def with_value(self, value: Any) -> EventLog:
+        """Set events that wrote the value: the write-side counterpart
+        to with_args()."""
+
+        return self._narrow(
+            f"[value={value!r}]",
+            lambda event: event.value is not MISSING and event.value == value,
+        )
+
+    def injected(self, want: bool = True) -> EventLog:
+        """Events whose outcome was supplied by returns(), raises() or
+        rejects(); with want=False, events whose outcome was real."""
+
+        suffix = "[injected]" if want else "[injected=False]"
+        return self._narrow(suffix, lambda event: event.injected is want)
+
+    # -- assertions: raise on failure, return self so they chain -------------
+
+    def assert_never(self) -> EventLog:
+        """Assert the log holds no events."""
+
+        if self._events:
+            raise AssertionError(self._failure("expected no events"))
+        return self
+
+    def assert_any(self) -> EventLog:
+        """Assert the log holds at least one event."""
+
+        if not self._events:
+            raise AssertionError(self._failure("expected at least 1 event(s)"))
+        return self
+
+    def assert_once(self) -> EventLog:
+        """Assert the log holds exactly one event."""
+
+        return self.assert_times(1)
+
+    def assert_times(self, count: int) -> EventLog:
+        """Assert the log holds exactly `count` events."""
+
+        if len(self._events) != count:
+            raise AssertionError(self._failure(f"expected exactly {count} event(s)"))
+        return self
+
+    def assert_at_least(self, count: int) -> EventLog:
+        """Assert the log holds at least `count` events."""
+
+        if len(self._events) < count:
+            raise AssertionError(self._failure(f"expected at least {count} event(s)"))
+        return self
+
+    def assert_at_most(self, count: int) -> EventLog:
+        """Assert the log holds at most `count` events."""
+
+        if len(self._events) > count:
+            raise AssertionError(self._failure(f"expected at most {count} event(s)"))
+        return self
+
+    def _describe(self) -> list[str]:
+        # The log's events, line by line. When the log is empty because
+        # a filter discarded everything, fall back to the nearest
+        # non-empty log in the filter chain, so filtering the wrong
+        # thing is visible rather than mysterious.
+
+        lines = repr(self).splitlines()
+
+        if not self._events:
+            ancestor = self._filtered_from
+            while ancestor is not None and not ancestor._events:
+                ancestor = ancestor._filtered_from
+
+            if ancestor is not None:
+                lines.append("  filtered from:")
+                lines.extend(f"    {line}" for line in repr(ancestor).splitlines())
+
+        return lines
+
+    def _failure(self, expectation: str) -> str:
+        return "\n".join([f"{expectation}, got {len(self._events)}", *self._describe()])
+
+    # -- data ----------------------------------------------------------------
+
+    @property
+    def count(self) -> int:
+        """How many events the log holds."""
+
+        return len(self._events)
+
+    @property
+    def first(self) -> Event:
+        """The earliest event in the log."""
+
+        return self._events[0]
+
+    @property
+    def last(self) -> Event:
+        """The latest event in the log."""
+
+        return self._events[-1]
+
+    def __len__(self) -> int:
+        return len(self._events)
+
+    def __bool__(self) -> bool:
+        return bool(self._events)
+
+    def __iter__(self) -> Iterator[Event]:
+        return iter(self._events)
+
+    def __getitem__(self, index: int) -> Event:
+        return self._events[index]
+
+    def __repr__(self) -> str:
+        lines = [f"<EventLog {self._label}: {len(self._events)} event(s)>"]
+
+        if self._events:
+            lines.extend(f"    {event}" for event in self._events)
+        else:
+            lines.append("    (no events)")
+
+        return "\n".join(lines)

wrapture/events.py

@@ -0,0 +1,201 @@
+"""The event record produced when a binding observes something happen.
+
+One record type covers all four kinds of observation: a call to a wrapped
+callable, and a read, write or delete of a wrapped attribute. The kinds
+share the fields that describe where and when the event happened and how
+events nest; each kind then populates the fields that make sense for it.
+
+Nothing in this module records anything by itself. Events are created by
+the recording machinery when a binding fires inside a timeline, and are
+consumed through the event log and tape interfaces built on top of them.
+"""
+
+from __future__ import annotations
+
+import inspect
+import weakref
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from wrapt import MISSING
+
+from .capture import REFERENCE
+
+EventKind = Literal["call", "get", "set", "delete"]
+
+
+@dataclass(eq=False)
+class Event:
+    """One recorded occurrence at a binding.
+
+    The `kind` field says what happened: "call" for an invocation of a
+    wrapped callable, and "get", "set" or "delete" for attribute access.
+    Fields that were not observed hold the MISSING sentinel (for values,
+    so that a recorded None stays distinguishable) or None (for the
+    optional descriptive fields). Events compare by identity: two events
+    with identical fields are still two distinct occurrences.
+    """
+
+    kind: EventKind
+
+    # Where it happened: path is the fully qualified location of what
+    # was bound, in module:path form with both halves dotted, so it
+    # stays meaningful after events leave the process. label is the
+    # friendly display name, from the binding's label.
+
+    path: str
+    label: str | None = None
+    instance: Any = None
+
+    # The Binding that recorded this event. Typed loosely because the
+    # bindings module builds on this one; excluded from repr() because
+    # the path already identifies the event.
+
+    binding: Any = field(default=None, repr=False)
+
+    # Position on the tape: allocation order, nesting depth, and the
+    # enclosing and enclosed events. Excluded from repr() because parent
+    # and children reference each other cyclically.
+
+    seq: int = 0
+    depth: int = 0
+    parent: Event | None = field(default=None, repr=False)
+    children: list[Event] = field(default_factory=list, repr=False)
+
+    started: float | None = None
+    duration: float | None = None
+
+    # Iteration, for a call that produced a generator: how many items it
+    # has yielded so far, and the accumulated time its body ran across
+    # resumptions. duration is then wall time from creation to close,
+    # which includes all the consumer's time between yields, so the two
+    # answer different questions.
+
+    items: int | None = None
+    body_duration: float | None = None
+
+    # Outcome. For a call this is the return value or the exception it
+    # raised; for a get it is the value read, so the same accessors and
+    # filters work across calls and reads.
+
+    result: Any = MISSING
+    exception: BaseException | None = None
+
+    # kind == "call": the arguments as sent, the signature-normalized
+    # form with defaults applied, and the (args, kwargs) actually passed
+    # on when behaviour transformed them.
+
+    args: tuple[Any, ...] | None = None
+    kwargs: dict[str, Any] | None = None
+    arguments: dict[str, Any] | None = None
+    forwarded: tuple[tuple[Any, ...], dict[str, Any]] | None = None
+
+    # kind == "set": the value written, and the prior value where it was
+    # cheaply available.
+
+    value: Any = MISSING
+    previous: Any = MISSING
+
+    # Recording provenance: the capture level values were recorded at,
+    # whether the outcome was supplied by returns()/raises() rather than
+    # produced by the real operation, the interned id of the captured
+    # call stack when the binding asked for one, and caller-supplied
+    # annotations merged in with annotate().
+
+    capture: int = REFERENCE
+    injected: bool = False
+    stack: int | None = None
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        # Display favours the friendly label; the path is there when no
+        # label was recorded, and for anything that needs the location
+        # rather than the name.
+
+        where = self.label or self.path
+
+        if self.kind == "call":
+            return f"{where}({self._format_arguments()})"
+
+        if self.kind == "get":
+            if self.result is not MISSING:
+                return f"get {where} -> {self.result!r}"
+            return f"get {where}"
+
+        if self.kind == "set":
+            return f"set {where} = {self.value!r}"
+
+        return f"delete {where}"
+
+    def _format_arguments(self) -> str:
+        # Prefer the normalized form so the display matches what filters
+        # and assertions compare against; fall back to the raw call shape
+        # when no signature was available.
+
+        if self.arguments is not None:
+            return ", ".join(f"{k}={v!r}" for k, v in self.arguments.items())
+
+        positional = [repr(a) for a in (self.args or ())]
+        keyword = [f"{k}={v!r}" for k, v in (self.kwargs or {}).items()]
+        return ", ".join(positional + keyword)
+
+
+# Signature lookup is cached because inspect.signature costs microseconds
+# per call and would dominate the recording path. The cache is keyed on
+# the function itself via weak references, never on id(): ids are reused
+# after garbage collection, and a collision would silently bind one
+# function's arguments against another's signature.
+
+_signature_cache: weakref.WeakKeyDictionary[Any, inspect.Signature | None] = (
+    weakref.WeakKeyDictionary()
+)
+
+
+def _signature(func: Any) -> inspect.Signature | None:
+    try:
+        return _signature_cache[func]
+    except KeyError:
+        pass
+    except TypeError:
+        # Unhashable or not weak-referenceable: compute every time.
+
+        try:
+            return inspect.signature(func)
+        except (TypeError, ValueError):
+            return None
+
+    try:
+        signature = inspect.signature(func)
+    except (TypeError, ValueError):
+        signature = None
+
+    try:
+        _signature_cache[func] = signature
+    except TypeError:
+        pass
+
+    return signature
+
+
+def normalized_arguments(
+    func: Any, args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> dict[str, Any] | None:
+    """Bind args and kwargs against func's signature, defaults applied.
+
+    Returns a dict mapping parameter names to values, so that f(1, 2)
+    and f(1, b=2) produce the same recorded arguments. Returns None when
+    no signature is available or the arguments do not fit it, in which
+    case the caller falls back to the raw call shape.
+    """
+
+    signature = _signature(func)
+    if signature is None:
+        return None
+
+    try:
+        bound = signature.bind(*args, **kwargs)
+    except TypeError:
+        return None
+
+    bound.apply_defaults()
+    return dict(bound.arguments)

wrapture/exceptions.py

@@ -0,0 +1,45 @@
+"""Exception types raised by wrapture."""
+
+
+class AlreadyAppliedError(RuntimeError):
+    """apply() was called on a binding whose wrapper is already applied."""
+
+
+class WrongModeError(AttributeError):
+    """A behaviour namespace was accessed that does not apply to this
+    binding's mode.
+
+    Derives from AttributeError so that hasattr() can be used to probe
+    which namespaces a binding supports.
+    """
+
+
+class ExpectationNotMetError(AssertionError):
+    """A declared expect_* expectation was not met when the timeline
+    verified it at exit.
+
+    Derives from AssertionError so test frameworks report it as a test
+    failure rather than an error.
+    """
+
+
+class RecordingGapWarning(RuntimeWarning):
+    """An observed operation ran on a thread with no recording context
+    while a timeline was active elsewhere, so it is missing from that
+    timeline's tape. Behaviour still applied; only recording was lost.
+    """
+
+
+class NeverAppliedError(RuntimeError):
+    """events was read on a binding that was never applied, so nothing
+    could possibly have been recorded for it."""
+
+
+class NotImplementedYetError(NotImplementedError):
+    """A feature whose API shape is settled is not implemented yet."""
+
+
+class DeferredTargetError(ValueError):
+    """A string target used wrapt's trailing `?` deferred-patching syntax,
+    which is not supported. Import the module first and bind against it.
+    """