wrapture 1.0.0.dev1__py3-none-any.whl

wrapture/timeline.py

@@ -0,0 +1,364 @@
+"""The recording scope: the tape events land on, and how they find it.
+
+Observed code calls its own methods normally; nothing threads a tape
+through those calls. So when a wrapper fires it answers two questions
+from ambient state: am I recording, and into what; and what call am I
+nested inside. Both live in context variables, set when a timeline is
+entered and restored on exit.
+
+Context variables specifically, because a module-level global would be
+shared by concurrent asyncio tasks, recording one task's calls as
+children of another's, and a thread-local would fail the same way for
+many tasks on one thread. Each task gets its own copy of the context,
+so each records its own correctly nested tree.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import threading
+from collections.abc import Iterable
+from typing import Any, Protocol, runtime_checkable
+
+from wrapt import MISSING
+
+from .capture import NONE, REFERENCE, CapturePolicy, _capture_value, _level_of
+from .eventlogs import EventLog
+from .events import Event
+
+
+@runtime_checkable
+class _Appliable(Protocol):
+    # Anything with the binding lifecycle: a Binding or a BindingGroup.
+    # Duck-typed rather than imported, because the bindings module is a
+    # consumer of this one and importing it here would be circular.
+
+    def apply(self) -> Any: ...
+
+    def remove(self) -> Any: ...
+
+
+class Tape:
+    """The ordered record of events for one timeline.
+
+    The tape assigns each event its sequence number as it is recorded,
+    so ordering assertions have a single authoritative order even when
+    events arrive from concurrently running tasks.
+    """
+
+    # The capture levels this sink requires of bindings that follow the
+    # sink (design: the sink says what it needs). REFERENCE on both
+    # axes, because a test asserts within the scope, where references
+    # are accurate and cost nothing. A streaming sink would declare
+    # SUMMARY arguments and NONE results instead.
+
+    capture_args: CapturePolicy = REFERENCE
+    capture_result: CapturePolicy = REFERENCE
+
+    def __init__(self) -> None:
+        self._entries: list[Event] = []
+        self._lock = threading.Lock()
+        self._seq = 0
+
+    def record(self, event: Event) -> Event:
+        """Assign the next sequence number to the event and append it.
+
+        Returns the event, which stays live: the recorder fills in the
+        outcome fields when the call completes.
+        """
+
+        with self._lock:
+            self._seq += 1
+            event.seq = self._seq
+            self._entries.append(event)
+
+        return event
+
+    @property
+    def all(self) -> list[Event]:
+        """Every recorded event, in sequence order."""
+
+        with self._lock:
+            return list(self._entries)
+
+    def for_binding(self, bnd: Any) -> EventLog:
+        """A filterable view over this tape's events for one binding."""
+
+        with self._lock:
+            events = [event for event in self._entries if event.binding is bnd]
+
+        return EventLog(getattr(bnd, "label", repr(bnd)), events)
+
+    def roots(self) -> list[Event]:
+        """The top-level events: those recorded with no observed caller."""
+
+        with self._lock:
+            return [event for event in self._entries if event.parent is None]
+
+    def tree(self) -> str:
+        """The call graph as it actually ran, one event per line,
+        indented by nesting depth.
+
+        A completed event shows its result after `->`; one that raised
+        shows `!!` and the exception type; one still in progress shows
+        neither.
+        """
+
+        lines: list[str] = []
+
+        def emit(event: Event) -> None:
+            injected = " (injected)" if event.injected else ""
+
+            if event.exception is not None:
+                marker = f"  !! {type(event.exception).__name__}{injected}"
+            elif event.result is not MISSING:
+                marker = f"  -> {event.result!r}{injected}"
+            else:
+                marker = ""
+
+            lines.append("  " * event.depth + str(event) + marker)
+
+            for child in event.children:
+                emit(child)
+
+        for root in self.roots():
+            emit(root)
+
+        return "\n".join(lines)
+
+    def assert_order(self, *bindings: Any) -> Tape:
+        """Assert the bindings recorded events in the given order.
+
+        A subsequence check, not an exact match: other events may appear
+        before, between and after, and only the relative order of the
+        given bindings' events matters. Repeating a binding requires it
+        to have recorded that many times in order. Raises AssertionError
+        naming where the expectation stalled, with the actual timeline.
+        """
+
+        with self._lock:
+            entries = list(self._entries)
+
+        position = 0
+        for event in entries:
+            if position < len(bindings) and event.binding is bindings[position]:
+                position += 1
+
+        if position != len(bindings):
+            stalled = getattr(bindings[position], "label", repr(bindings[position]))
+            actual = "\n".join(f"    {event}" for event in entries) or "    (no events)"
+            raise AssertionError(
+                f"expected order not satisfied; stalled waiting for"
+                f" {stalled} (position {position + 1} of {len(bindings)})\n"
+                f"  actual timeline:\n{actual}"
+            )
+
+        return self
+
+
+# The ambient state. The tape variable doubles as the recording switch:
+# None means no timeline is active and wrappers call straight through.
+# The stack variable holds the events currently in progress, innermost
+# last, and is the entire source of parent, depth and children.
+
+_tape: contextvars.ContextVar[Tape | None] = contextvars.ContextVar(
+    "wrapture_tape", default=None
+)
+_stack: contextvars.ContextVar[tuple[Event, ...]] = contextvars.ContextVar(
+    "wrapture_stack", default=()
+)
+
+# How many timelines are active process-wide, kept so a wrapper firing
+# with no ambient tape can tell "nothing is recording anywhere" from
+# "a timeline is running but this thread has no context". Threads start
+# with a fresh context, so their calls otherwise vanish from the tape
+# silently; see the known limitations page.
+
+_active_lock = threading.Lock()
+_active_count = 0
+
+
+def _timeline_started() -> None:
+    global _active_count
+
+    with _active_lock:
+        _active_count += 1
+
+
+def _timeline_finished() -> None:
+    global _active_count
+
+    with _active_lock:
+        _active_count -= 1
+
+
+def _timelines_active() -> bool:
+    return _active_count > 0
+
+
+# The reentrancy guard. Set while the recording machinery itself runs, so
+# an observed callable invoked from inside the recorder (rather than from
+# the code under observation) does not record recursively without bound.
+# Behaviour still applies on the guarded path: only recording is skipped,
+# so a call the user stubbed out stays stubbed even when the recorder
+# triggers it.
+
+_in_recorder: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    "wrapture_in_recorder", default=False
+)
+
+
+def _push(event: Event) -> contextvars.Token[tuple[Event, ...]]:
+    # Nest the event under whatever is currently in progress, then make
+    # it the innermost in-progress event. The returned token restores
+    # the previous stack in _pop, which must run in the same context.
+
+    stack = _stack.get()
+    parent = stack[-1] if stack else None
+
+    event.parent = parent
+    event.depth = len(stack)
+    if parent is not None:
+        parent.children.append(event)
+
+    return _stack.set(stack + (event,))
+
+
+def _pop(token: contextvars.Token[tuple[Event, ...]]) -> None:
+    _stack.reset(token)
+
+
+def _capture_result(event: Event, outcome: Any, policy: CapturePolicy) -> None:
+    # Result capture runs under the recorder guard: at SUMMARY and above
+    # it calls user code (repr, deepcopy), which must not record.
+
+    if _level_of(policy) <= NONE:
+        return
+
+    guard = _in_recorder.set(True)
+    try:
+        event.result = _capture_value(policy, None, outcome)
+    finally:
+        _in_recorder.reset(guard)
+
+
+def current_event() -> Event | None:
+    """The in-flight event, or None when nothing is being recorded.
+
+    The behaviour pipeline runs after its event is pushed, so this is
+    reachable from inside a decorates() handler, where it names the
+    event for the very call the handler is wrapping.
+    """
+
+    stack = _stack.get()
+    return stack[-1] if stack else None
+
+
+def annotate(**data: Any) -> None:
+    """Merge values into the in-flight event's data dict.
+
+    Annotation is targeted capture: the caller attaches what it knows a
+    generic policy cannot infer (a row count, a cache hit, an immutable
+    copy of a value that will be mutated). A silent no-op when nothing
+    is being recorded, so observed code can call it unconditionally.
+    """
+
+    event = current_event()
+    if event is not None:
+        event.data.update(data)
+
+
+class Timeline:
+    """A recording scope, created by timeline().
+
+    Entering sets the ambient tape and applies the bindings given at
+    creation, rolling back if any of them fails to apply. Exiting
+    removes them in reverse order and restores the previous ambient
+    state. The same timeline can be reused sequentially; its tape keeps
+    accumulating across uses.
+    """
+
+    def __init__(self, appliables: list[_Appliable]) -> None:
+        self.tape = Tape()
+
+        self._appliables = appliables
+        self._applied: list[_Appliable] = []
+        self._tape_token: contextvars.Token[Tape | None] | None = None
+        self._stack_token: contextvars.Token[tuple[Event, ...]] | None = None
+
+    def __enter__(self) -> Tape:
+        if self._tape_token is not None:
+            raise RuntimeError("timeline is already active")
+
+        self._tape_token = _tape.set(self.tape)
+        self._stack_token = _stack.set(())
+
+        # Apply every binding, rolling the whole entry back if one
+        # fails, so a partially patched scope never survives.
+
+        try:
+            for appliable in self._appliables:
+                appliable.apply()
+                self._applied.append(appliable)
+        except Exception:
+            for applied in reversed(self._applied):
+                applied.remove()
+            self._applied.clear()
+
+            self._restore()
+            raise
+
+        _timeline_started()
+        return self.tape
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        _timeline_finished()
+
+        for applied in reversed(self._applied):
+            applied.remove()
+        self._applied.clear()
+
+        self._restore()
+
+        # Verify declared expectations only when the block itself
+        # succeeded: raising here over an in-flight failure would bury
+        # the real cause.
+
+        if exc_type is None:
+            for appliable in self._appliables:
+                verify = getattr(appliable, "_verify", None)
+                if verify is not None:
+                    verify(self.tape)
+
+    def _restore(self) -> None:
+        assert self._tape_token is not None
+        assert self._stack_token is not None
+
+        _tape.reset(self._tape_token)
+        _stack.reset(self._stack_token)
+
+        self._tape_token = None
+        self._stack_token = None
+
+
+def timeline(*bindings: _Appliable | Iterable[_Appliable]) -> Timeline:
+    """Open a recording scope.
+
+    Bindings passed here are applied on entry and removed on exit: a
+    binding applied outside a timeline records nothing anyway, so the
+    recording scope and the useful patch lifetime are the same interval.
+    Accepts bindings, binding groups, or iterables of either; a group is
+    applied as a unit, keeping its own rollback behaviour. With no
+    arguments the scope only records, for bindings whose lifetime is
+    managed elsewhere.
+    """
+
+    flattened: list[_Appliable] = []
+
+    for entry in bindings:
+        if isinstance(entry, _Appliable):
+            flattened.append(entry)
+        else:
+            flattened.extend(entry)
+
+    return Timeline(flattened)

wrapture-1.0.0.dev1.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: wrapture
+Version: 1.0.0.dev1
+Summary: Library for attaching bindings to arbitrary Python call sites for monkey patching, testing, tracing and profiling.
+Author-email: Graham Dumpleton <Graham.Dumpleton@gmail.com>
+License-Expression: BSD-2-Clause
+Project-URL: Homepage, https://github.com/GrahamDumpleton/wrapture
+Project-URL: Documentation, https://wrapture.readthedocs.io
+Project-URL: Bug Tracker, https://github.com/GrahamDumpleton/wrapture/issues/
+Keywords: wrapper,monkey patching,tracing,testing,profiling
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: wrapt>=2.4.0rc4
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Dynamic: license-file
+
+# wrapture
+
+**Trace assertions without instrumenting your code.**
+
+[![Tests](https://github.com/GrahamDumpleton/wrapture/actions/workflows/build-test-release.yml/badge.svg?branch=develop)](https://github.com/GrahamDumpleton/wrapture/actions/workflows/build-test-release.yml)
+[![Documentation](https://readthedocs.org/projects/wrapture/badge/?version=latest)](https://wrapture.readthedocs.io)
+
+wrapture (`wrapt` + `capture`) is a Python library for attaching bindings to
+arbitrary call sites, without modifying the code being observed, and doing
+something useful with what flows through them.
+
+It is a sibling project to [wrapt](https://github.com/GrahamDumpleton/wrapt)
+and [autowrapt](https://github.com/GrahamDumpleton/autowrapt), building on the
+safe monkey-patching machinery wrapt provides.
+
+> **Status: early development.** The monkey patching and unit testing layers
+> are implemented; the tracing and profiling layers are designed but not
+> built. Nothing is published to PyPI yet.
+
+## Documentation
+
+Full documentation is at [wrapture.readthedocs.io](https://wrapture.readthedocs.io).
+Start with the [getting started](https://wrapture.readthedocs.io/en/latest/getting-started.html)
+page: everything on it can be pasted into a Python interpreter. Coming
+from `unittest.mock`? There is a
+[comparison page](https://wrapture.readthedocs.io/en/latest/coming-from-mock.html)
+mapping each mock idiom to its wrapture counterpart.
+
+## Thirty seconds of it
+
+None of the classes below import wrapture or know they are observed:
+
+```python
+place = wrapture.binding(OrderService, "place")
+charge = wrapture.binding(Gateway, "charge")
+record = wrapture.binding(Ledger, "record")
+
+with wrapture.timeline(place, charge, record) as tape:
+    OrderService().place(500)
+
+print(tape.tree())
+```
+
+```
+OrderService.place(amount=500)  -> {'id': 'ch_500', 'amount': 500}
+  Gateway.charge(amount=500, currency='USD')  -> {'id': 'ch_500', 'amount': 500}
+  Ledger.record(entry={'id': 'ch_500', 'amount': 500})  -> 'led_ch_500'
+```
+
+The same bindings intervene as well as observe: stub a result, inject a
+failure, or transform one argument while the real code keeps running.
+
+## What it does
+
+One mechanism, four uses, in increasing order of machinery:
+
+1. **Monkey patching.** A clean lifecycle and behaviour vocabulary over
+   wrapt's `wrap_object()`. Point at a method by name and stub it, fail it,
+   transform its arguments or result, or wrap it with a decorator, then
+   remove it again, with honest reporting if something else displaced the
+   patch in the meantime. Useful entirely on its own, with nothing else
+   switched on.
+
+2. **Unit testing.** Observe and assert on how calls actually flowed through a
+   *real* call graph (nesting, ordering, arguments and return values) and
+   optionally intervene (stub, transform, fail-inject). Unlike a `Mock`,
+   which fabricates values and cannot see calls an object makes to itself,
+   wrapture watches the real code run. This makes it possible to test code
+   with no injectable seams at all, and to assert on what *didn't* happen on
+   an error path: inject a gateway timeout, then verify the ledger was not
+   written, the receipt was not sent, and the compensating refund was issued.
+
+3. **Ad-hoc tracing.** Attach bindings to a running application, including
+   one you cannot modify or redeploy, and emit a structured, nested trace to
+   process or chart elsewhere. Name a handful of methods and a call tree
+   appears; no code changes required.
+
+4. **Targeted profiling.** Use a binding as a *scope* within which CPython's
+   own profiling machinery is active, so you can profile one subsystem of a
+   live process instead of everything.
+
+The distinction that matters: most tracing and profiling tools either need
+the code to have been written with them in mind, or can only be switched on
+for the whole program at once. wrapture needs neither: you point at a method
+by name and a trace appears.
+
+## Why
+
+No single existing tool covers "point at arbitrary methods, get a structured
+nested trace, assert on it or export it, in tests or in production":
+
+- `unittest.mock` records a flat call list, with no nesting and no return
+  values, and a patched call returns a fabricated `MagicMock` rather than
+  running the real code.
+- Span-assertion tools (`logfire.testing`, OpenTelemetry's
+  `InMemorySpanExporter`) require the code to already be instrumented.
+- `sys.settrace` tools (`hunter`, `snoop`) give a firehose with no assertion
+  API.
+- `cProfile` cannot scope to a subsystem in a live process, and APM agents
+  are all-or-nothing products rather than a toolkit.
+
+wrapture fills that gap: a targeted call tree with normalized arguments and
+return values, produced by naming the methods you care about, usable as a
+testing assertion library, a tracing tool, or both at once.
+
+## What it is not
+
+- **Not a replacement for `unittest.mock`.** It complements mocking where
+  code has seams; it exists for the code that doesn't.
+- **Not a sampling profiler.** `py-spy` and `austin` do that better and
+  without distortion.
+- **Not a production APM.** It is a toolkit that APM-like things could be
+  built on.
+- **Not an OpenTelemetry competitor.** It should emit to OTel, not replace
+  it.
+
+## Requirements
+
+- Python 3.12+
+- [wrapt](https://github.com/GrahamDumpleton/wrapt) 2.4.0+
+
+## License
+
+BSD 2-Clause. See [LICENSE](LICENSE).

wrapture-1.0.0.dev1.dist-info/RECORD

@@ -0,0 +1,18 @@
+wrapture/__init__.py,sha256=wFXWftQjghULEMHW6UP5-ucFxl19fTdc1VQSxhUJ2y8,2168
+wrapture/attributes.py,sha256=kcdKvsyXxPTlr8aiJRSuXlEyTxAoHBLS55iw2X731To,11622
+wrapture/behaviours.py,sha256=I3iNUquVfcWVXKWvis9o7PUq1Zh-XCQdQoRG8AgsOjE,12894
+wrapture/bindings.py,sha256=dk-W_Nl_b8m6O55L3LgS-jFyJ_LBNzb6edl3fMrcrpw,36595
+wrapture/capture.py,sha256=JIgefS3ASrGos8s798Yr6FTss7rh6n01jPAMGm6iUWY,5689
+wrapture/eventlogs.py,sha256=eTMtc5NizGPTwcsHfw4FrdzHXW2rHHMutJ4M7WXsFSU,7917
+wrapture/events.py,sha256=borkvI-SdGGvhgOT9acRg2XkbnNga0Ikf5imfjkxFyY,6902
+wrapture/exceptions.py,sha256=1WB2qLj3E-aXVOutipr9pMDWBm4_Qw0S8tkCABRaD5c,1415
+wrapture/iterators.py,sha256=X5_WAJY9LsuTC1Bo5y2QYael8ZFZvLI8bgo5jJkTkaA,14021
+wrapture/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wrapture/pytest_plugin.py,sha256=yMDZHgFofNeGQP4USIPtjK4mKWxwVk5E0SSZ9pKIeTI,3859
+wrapture/stacks.py,sha256=CcnCD4bTQbl-JDLms1Nx5FTJmjlkEJbmfGTVgO_Dxi0,2644
+wrapture/timeline.py,sha256=DlCFhKx0qER1upqC5yvI0Y-7oBwHh3jQQ-qFp_bTZxs,12044
+wrapture-1.0.0.dev1.dist-info/licenses/LICENSE,sha256=RPMyRnXwgrw9co5o6wY9G3DKlb-oBZ44tpiRnuYeec8,1299
+wrapture-1.0.0.dev1.dist-info/METADATA,sha256=H_gsOD_sGyvAkr1QbrHke80vn1jBB8gv0m4TFdJ-U0Q,6699
+wrapture-1.0.0.dev1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+wrapture-1.0.0.dev1.dist-info/top_level.txt,sha256=eUnd7dTkQgJ1f9rnewuv3zt-yCP-Qc36DMmRskb8AIU,9
+wrapture-1.0.0.dev1.dist-info/RECORD,,

wrapture-1.0.0.dev1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wrapture-1.0.0.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2026, Graham Dumpleton
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

wrapture-1.0.0.dev1.dist-info/top_level.txt

@@ -0,0 +1 @@
+wrapture