wrapture 1.0.0.dev7__tar.gz → 1.0.0.dev8__tar.gz

{wrapture-1.0.0.dev7/src/wrapture.egg-info → wrapture-1.0.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wrapture
-Version: 1.0.0.dev7
+Version: 1.0.0.dev8
 Summary: Monkey patch, test, and trace Python by attaching bindings to call sites, without modifying the code being observed. Built on wrapt.
 Author-email: Graham Dumpleton <Graham.Dumpleton@gmail.com>
 License-Expression: BSD-2-Clause
@@ -44,10 +44,10 @@ 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, unit testing and
-> ad-hoc tracing layers are implemented, including WSGI and ASGI request
-> tracing. Development previews are published to PyPI; the API may still
-> shift before 1.0.0.
+> **Status: stabilising ahead of 1.0.0.** The feature set is complete for
+> a first release and development previews are published to PyPI. The API
+> is being exercised and tidied rather than extended, so small changes are
+> still possible before 1.0.0.
 
 ## Installation
 
@@ -112,8 +112,8 @@ One mechanism, three uses, in increasing order of machinery:
 
 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,
+   optionally intervene (stub, transform, fail-inject). Unlike a
+   `unittest.mock` `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

{wrapture-1.0.0.dev7 → wrapture-1.0.0.dev8}/README.md

@@ -13,10 +13,10 @@ 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, unit testing and
-> ad-hoc tracing layers are implemented, including WSGI and ASGI request
-> tracing. Development previews are published to PyPI; the API may still
-> shift before 1.0.0.
+> **Status: stabilising ahead of 1.0.0.** The feature set is complete for
+> a first release and development previews are published to PyPI. The API
+> is being exercised and tidied rather than extended, so small changes are
+> still possible before 1.0.0.
 
 ## Installation
 
@@ -81,8 +81,8 @@ One mechanism, three uses, in increasing order of machinery:
 
 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,
+   optionally intervene (stub, transform, fail-inject). Unlike a
+   `unittest.mock` `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

{wrapture-1.0.0.dev7 → wrapture-1.0.0.dev8}/src/wrapture/__init__.py

@@ -17,7 +17,7 @@ def _format_version(parts: tuple[str, ...]) -> str:
     )
 
 
-__version_info__ = ("1", "0", "0", "dev7")
+__version_info__ = ("1", "0", "0", "dev8")
 __version__ = _format_version(__version_info__)
 
 from wrapt import MISSING, register_post_import_hook, when_imported
@@ -27,9 +27,13 @@ from .asgi import (
 )
 from .behaviours import (
     CallBehaviour,
+    CallPhase,
     DeleteBehaviour,
+    DeletePhase,
     GetBehaviour,
+    GetPhase,
     SetBehaviour,
+    SetPhase,
 )
 from .bindings import (
     Binding,
@@ -69,6 +73,7 @@ from .exceptions import (
     NeverAppliedError,
     NotImplementedYetError,
     RecordingGapWarning,
+    SequenceExhaustedError,
     SinkErrorWarning,
     WrongModeError,
 )
@@ -144,12 +149,14 @@ __all__ = [
     "Window",
     "BindingGroup",
     "CallBehaviour",
+    "CallPhase",
     "Config",
     "ConfigError",
     "ConfigWarning",
     "Counter",
     "DeferredTargetError",
     "DeleteBehaviour",
+    "DeletePhase",
     "Depth",
     "Event",
     "EventLog",
@@ -157,6 +164,7 @@ __all__ = [
     "Fanout",
     "Filter",
     "GetBehaviour",
+    "GetPhase",
     "IteratorAbandonBehaviour",
     "IteratorErrorBehaviour",
     "IteratorFinishBehaviour",
@@ -171,7 +179,9 @@ __all__ = [
     "Printer",
     "RecordingGapWarning",
     "Sample",
+    "SequenceExhaustedError",
     "SetBehaviour",
+    "SetPhase",
     "SetupEntry",
     "Sink",
     "SinkErrorWarning",

{wrapture-1.0.0.dev7 → wrapture-1.0.0.dev8}/src/wrapture/attributes.py

@@ -7,6 +7,13 @@ nothing was defined. Reads, writes and deletes hook the binding's
 behaviour first and then perform the real operation, honouring a prior
 descriptor's own logic beneath the interception.
 
+A module owner works the same way one level up: the descriptor goes on
+a per-module subclass of the module's type, assigned to the module's
+`__class__` while any binding on the module is applied, and the value
+itself stays in the module's `__dict__`. One such class serves every
+binding on the module, and it is removed again when the last binding
+is.
+
 The descriptor derives from wrapt's BaseObjectProxy and wraps the prior
 definition, so wrapt's unwrap_object() can traverse and splice the
 wrapper chain, and two attribute bindings on one name compose rather
@@ -22,6 +29,7 @@ from __future__ import annotations
 
 import inspect
 import sys
+import threading
 import time
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
@@ -29,9 +37,8 @@ from typing import TYPE_CHECKING, Any
 import wrapt
 from wrapt import MISSING, BaseObjectProxy, apply_patch
 
-from .capture import _capture_value, _level_of
+from .capture import REFERENCE, CapturePolicy, _capture_value, _level_of
 from .events import Event, EventKind
-from .exceptions import NotImplementedYetError
 from .sinks import (
     _active_sinks,
     _in_recorder,
@@ -49,6 +56,7 @@ from .timeline import (
 )
 
 if TYPE_CHECKING:
+    from .behaviours import Phase
     from .bindings import Binding
 
 
@@ -78,6 +86,19 @@ def _read(prior: Any, attribute: str, instance: Any, owner: Any) -> Any:
     if prior is not MISSING:
         return prior
 
+    # A module may supply names it does not define through a module-level
+    # __getattr__ (PEP 562); a missing_ok binding on such a name defers
+    # to it rather than hiding it.
+
+    if inspect.ismodule(instance):
+        fallback = instance.__dict__.get("__getattr__")
+        if fallback is not None:
+            return fallback(attribute)
+
+        raise AttributeError(
+            f"module {instance.__name__!r} has no attribute {attribute!r}"
+        )
+
     raise AttributeError(
         f"{type(instance).__name__!r} object has no attribute {attribute!r}"
     )
@@ -112,13 +133,100 @@ def _delete(prior: Any, attribute: str, instance: Any) -> None:
         ) from None
 
 
+def _build_event(
+    binding: Binding,
+    kind: EventKind,
+    instance: Any,
+    attribute: str,
+    policy: CapturePolicy,
+    value: Any,
+    phase: Phase | None,
+) -> Event:
+    """Construct the event for one attribute operation, under the
+    recorder guard so capture that runs user code does not record."""
+
+    guard = _in_recorder.set(True)
+    try:
+        event = Event(
+            kind,
+            binding._path,
+            label=binding._label,
+            instance=instance,
+            binding=binding,
+            capture=_level_of(policy),
+            injected=phase is not None and phase.injected,
+            phase=binding._phase_of(phase),
+        )
+
+        if binding._stack_depth is not None:
+            event.stack = _capture_stack(binding._stack_depth)
+
+        if value is not MISSING:
+            event.value = _capture_value(policy, attribute, value)
+
+        # The prior value, when cheaply available: only what already
+        # sits in the instance dictionary. A prior held by a descriptor
+        # would take running user code to read, so it is not recorded.
+
+        if kind in ("set", "delete"):
+            previous = getattr(instance, "__dict__", {}).get(attribute, MISSING)
+            if previous is not MISSING:
+                event.previous = _capture_value(policy, attribute, previous)
+
+    finally:
+        _in_recorder.reset(guard)
+
+    return event
+
+
+def _quiet(
+    binding: Binding,
+    kind: EventKind,
+    instance: Any,
+    attribute: str,
+    operate: Callable[[Event | None], Any],
+    value: Any,
+    slot: list[Phase | None],
+) -> Any:
+    """Run an unrecorded attribute operation, still showing it to a
+    phase with an until= exit through a private event, as the callable
+    path does."""
+
+    try:
+        outcome = operate(None)
+    except BaseException as exc:
+        phase = slot[0]
+
+        if phase is not None and phase.watches:
+            event = _build_event(
+                binding, kind, instance, attribute, REFERENCE, value, phase
+            )
+            event.exception = exc
+            binding._completed(kind, phase, event)
+
+        raise
+
+    phase = slot[0]
+
+    if phase is not None and phase.watches:
+        event = _build_event(
+            binding, kind, instance, attribute, REFERENCE, value, phase
+        )
+        if kind == "get":
+            event.result = outcome
+        binding._completed(kind, phase, event)
+
+    return outcome
+
+
 def _record(
     binding: Binding,
     kind: EventKind,
     instance: Any,
     attribute: str,
-    operate: Callable[[], Any],
+    operate: Callable[[Event | None], Any],
     value: Any = MISSING,
+    slot: list[Phase | None] | None = None,
 ) -> Any:
     """Run one attribute operation, recording it onto the ambient tape.
 
@@ -126,20 +234,25 @@ def _record(
     recorder's own reentrancy guard) means the operation just runs, and
     otherwise an event is recorded around it, with the operation pushed
     on the in-progress stack so anything it triggers nests under it.
+    `slot` holds the phase handling the operation, updated by dispatch
+    if a sequence hands over mid-operation.
     """
 
+    if slot is None:
+        slot = [None]
+
     # when=False is a behaviour-only binding: it never records, counts
     # nothing, and takes no part in gap detection.
 
     if binding._when is False:
-        return operate()
+        return _quiet(binding, kind, instance, attribute, operate, value, slot)
 
     active = _active_sinks()
     if not active or _in_recorder.get():
         if not active and not _in_recorder.get() and _timelines_active():
             binding._note_missed_call()
 
-        return operate()
+        return _quiet(binding, kind, instance, attribute, operate, value, slot)
 
     # The per-access predicate, mapped onto call shape the same way
     # behaviour stages are: a set passes the written value as the one
@@ -156,45 +269,23 @@ def _record(
 
         if not wanted:
             binding._filtered_calls += 1
-            return operate()
+            return _quiet(binding, kind, instance, attribute, operate, value, slot)
 
     # The written value and the prior value are inbound data, so they
     # capture on the arguments axis, under the attribute's name so a
-    # by-name policy such as redact() applies to writes too.
+    # by-name policy such as redact() applies to writes too. An until=
+    # predicate needs the value whatever the sinks asked for.
+
+    phase = slot[0]
+    watching = phase is not None and phase.watches
 
     policy = binding._capture_args
     if policy is None:
         policy = _required_policy(active, "capture_args")
+    if watching and _level_of(policy) < REFERENCE:
+        policy = REFERENCE
 
-    guard = _in_recorder.set(True)
-    try:
-        event = Event(
-            kind,
-            binding._path,
-            label=binding._label,
-            instance=instance,
-            binding=binding,
-            capture=_level_of(policy),
-            injected=binding._injects.get(kind, False),
-        )
-
-        if binding._stack_depth is not None:
-            event.stack = _capture_stack(binding._stack_depth)
-
-        if value is not MISSING:
-            event.value = _capture_value(policy, attribute, value)
-
-        # The prior value, when cheaply available: only what already
-        # sits in the instance dictionary. A prior held by a descriptor
-        # would take running user code to read, so it is not recorded.
-
-        if kind in ("set", "delete"):
-            previous = getattr(instance, "__dict__", {}).get(attribute, MISSING)
-            if previous is not MISSING:
-                event.previous = _capture_value(policy, attribute, previous)
-
-    finally:
-        _in_recorder.reset(guard)
+    event = _build_event(binding, kind, instance, attribute, policy, value, phase)
 
     # Position before delivery: pushed first, so sinks hearing
     # on_enter see the event's final depth and parent link. Timing
@@ -208,11 +299,12 @@ def _record(
     event.started = started
 
     try:
-        outcome = operate()
+        outcome = operate(event)
     except BaseException as exc:
         event.duration = time.perf_counter() - started
         event.exception = exc
         _notify_error(event, active)
+        binding._completed(kind, slot[0], event)
         raise
     finally:
         _pop(token)
@@ -226,9 +318,12 @@ def _record(
         result_policy = binding._capture_result
         if result_policy is None:
             result_policy = _required_policy(active, "capture_result")
+        if watching and _level_of(result_policy) < REFERENCE:
+            result_policy = REFERENCE
         _capture_result(event, outcome, result_policy)
 
     _notify_exit(event, active)
+    binding._completed(kind, slot[0], event)
     return outcome
 
 
@@ -262,17 +357,18 @@ class AttributeDescriptor(BaseObjectProxy[Any]):
             binding._suspended_calls += 1
             return _read(prior, attribute, instance, owner)
 
-        behaviour = binding._behaviour("get")
+        phase = binding._select("get")
+        slot: list[Phase | None] = [phase]
 
         def read() -> Any:
             return _read(prior, attribute, instance, owner)
 
-        def operate() -> Any:
-            if behaviour is None:
-                return read()
-            return behaviour(read, instance, (), {})
+        def operate(event: Event | None) -> Any:
+            return binding._invoke(
+                "get", phase, read, instance, (), {}, event, slot=slot
+            )
 
-        return _record(binding, "get", instance, attribute, operate)
+        return _record(binding, "get", instance, attribute, operate, slot=slot)
 
     def __set__(self, instance: Any, value: Any) -> None:
         binding = self._self_wrapture_binding
@@ -284,18 +380,18 @@ class AttributeDescriptor(BaseObjectProxy[Any]):
             _write(prior, attribute, instance, value)
             return
 
-        behaviour = binding._behaviour("set")
+        phase = binding._select("set")
+        slot: list[Phase | None] = [phase]
 
         def write(new_value: Any) -> None:
             _write(prior, attribute, instance, new_value)
 
-        def operate() -> Any:
-            if behaviour is None:
-                write(value)
-                return None
-            return behaviour(write, instance, (value,), {})
+        def operate(event: Event | None) -> Any:
+            return binding._invoke(
+                "set", phase, write, instance, (value,), {}, event, slot=slot
+            )
 
-        _record(binding, "set", instance, attribute, operate, value=value)
+        _record(binding, "set", instance, attribute, operate, value=value, slot=slot)
 
     def __delete__(self, instance: Any) -> None:
         binding = self._self_wrapture_binding
@@ -307,18 +403,103 @@ class AttributeDescriptor(BaseObjectProxy[Any]):
             _delete(prior, attribute, instance)
             return
 
-        behaviour = binding._behaviour("delete")
+        phase = binding._select("delete")
+        slot: list[Phase | None] = [phase]
 
         def erase() -> None:
             _delete(prior, attribute, instance)
 
-        def operate() -> Any:
-            if behaviour is None:
-                erase()
-                return None
-            return behaviour(erase, instance, (), {})
+        def operate(event: Event | None) -> Any:
+            return binding._invoke(
+                "delete", phase, erase, instance, (), {}, event, slot=slot
+            )
+
+        _record(binding, "delete", instance, attribute, operate, slot=slot)
+
+
+_MODULE_BASE = "_wrapture_module_base"
+
+_module_lock = threading.Lock()
+
+
+def _module_class(module: Any) -> type | None:
+    """The per-module class wrapture assigned to a module, or None when
+    the module's type is not one of ours."""
+
+    cls = type(module)
+    if _MODULE_BASE in vars(cls):
+        return cls
+
+    return None
+
+
+def _intercept_module(module: Any, binding: Binding) -> type:
+    """Find or create the per-module class that carries descriptors for
+    a module, assigning it to the module's __class__ on creation.
+
+    The class derives from the module's current type rather than
+    ModuleType, so anything that already replaced the module's class is
+    kept working beneath the interception. It is named "module" so the
+    type's name, and messages built from it, read the same as before.
+    """
+
+    existing = _module_class(module)
+    if existing is not None:
+        return existing
+
+    # From CPython 3.14 (python/cpython#103951, PR #126264, still the
+    # case on main) the LOAD_ATTR specialisation for modules is chosen on
+    # the type's getattro slot alone, anything sharing ModuleType's, and
+    # then reads the module dictionary directly, skipping data
+    # descriptors on the type. Before 3.14 the guard was an exact type
+    # check, so subclasses always took the general path and descriptors
+    # worked. The change was made for speed and neither the issue nor
+    # the PR mentions descriptors, so the loss looks unintended, an
+    # unreported regression rather than a decision. Defining
+    # __getattribute__ gives the class its own slot, so every access
+    # takes the general path and the descriptors are seen, on every
+    # version, whether or not upstream changes again. It delegates
+    # straight to the base, so messages and any module __getattr__
+    # behave as before.
+
+    base: Any = type(module)
+
+    def __getattribute__(self: Any, name: str) -> Any:
+        return base.__getattribute__(self, name)
+
+    namespace = {
+        _MODULE_BASE: base,
+        "__module__": base.__module__,
+        "__getattribute__": __getattribute__,
+    }
+    cls = type("module", (base,), namespace)
+
+    try:
+        module.__class__ = cls
+    except TypeError as exc:
+        raise TypeError(
+            f"{binding._label}: attribute bindings on module"
+            f" {module.__name__!r} are not possible because its type"
+            f" {base.__name__!r} does not allow __class__ assignment"
+            f" ({exc}). To hold a value in the attribute while applied,"
+            f" use attr={binding._name.rsplit('.', 1)[-1]!r} instead"
+        ) from None
+
+    return cls
+
+
+def _release_module(module: Any) -> None:
+    """Put the module's original class back once no descriptor remains
+    on the per-module class and it is still what the module uses."""
+
+    cls = _module_class(module)
+    if cls is None:
+        return
+
+    if any(isinstance(value, AttributeDescriptor) for value in vars(cls).values()):
+        return
 
-        _record(binding, "delete", instance, attribute, operate)
+    module.__class__ = vars(cls)[_MODULE_BASE]
 
 
 def _resolve_parent(target: Any, name: str) -> tuple[Any, str]:
@@ -336,6 +517,36 @@ def _resolve_parent(target: Any, name: str) -> tuple[Any, str]:
     return target, name
 
 
+def _install_on_module(
+    binding: Binding, module: Any, attribute: str
+) -> AttributeDescriptor:
+    """Install the descriptor for a module attribute on the per-module
+    class, creating the class on first use."""
+
+    # An absent attribute is only bindable with missing_ok=True, as for
+    # a class owner. A name a module-level __getattr__ would supply
+    # counts as absent: it is not in the module's dictionary.
+
+    if attribute not in vars(module) and not binding._missing_ok:
+        raise AttributeError(
+            f"{binding._label}: attribute {attribute!r} is not defined on"
+            f" module {module.__name__!r}; pass missing_ok=True to bind a"
+            f" name that is assigned later"
+        )
+
+    with _module_lock:
+        cls = _intercept_module(module, binding)
+
+        prior: Any = vars(cls).get(attribute, MISSING)
+        created = prior is MISSING
+
+        descriptor = AttributeDescriptor(prior, attribute, binding)
+        descriptor.__self_setattr__("__wrapt_wrap_object_created_slot__", created)
+        apply_patch(cls, attribute, descriptor)
+
+    return descriptor
+
+
 def install(binding: Binding, target: Any, name: str) -> AttributeDescriptor:
     """Install an AttributeDescriptor for a binding, returning the handle.
 
@@ -344,22 +555,21 @@ def install(binding: Binding, target: Any, name: str) -> AttributeDescriptor:
     keeps working beneath the interception. Whether installation created
     the attribute slot is recorded on the descriptor the same way
     wrapt.wrap_object() records it, so wrapt.unwrap_object() removes the
-    slot rather than leaving a shadowing copy where appropriate.
+    slot rather than leaving a shadowing copy where appropriate. A
+    module owner installs on the per-module class instead.
     """
 
     parent, attribute = _resolve_parent(target, name)
 
     if inspect.ismodule(parent):
-        raise NotImplementedYetError(
-            f"{binding._label}: attribute bindings on a module are not"
-            f" supported; module attribute access does not go through"
-            f" class descriptors"
-        )
+        return _install_on_module(binding, parent, attribute)
 
     if not inspect.isclass(parent):
         raise TypeError(
             f"{binding._label}: an attribute binding installs a descriptor"
-            f" on the class, so the target must be a class, not an instance"
+            f" on the class, so the target must be a class, not an instance."
+            f" To observe reads on every instance, bind the class; to set"
+            f" the value on this one object, use attr={attribute!r}"
         )
 
     prior: Any = MISSING
@@ -386,3 +596,72 @@ def install(binding: Binding, target: Any, name: str) -> AttributeDescriptor:
     apply_patch(parent, attribute, descriptor)
 
     return descriptor
+
+
+def _holder(target: Any, name: str, descriptor: AttributeDescriptor) -> tuple[Any, str]:
+    """The object whose namespace holds a binding's descriptor, and the
+    attribute name there: for a module owner the per-module class in
+    its MRO that has the descriptor, otherwise the owner itself. Raises
+    when the owner no longer resolves or no class holds it."""
+
+    parent, attribute = _resolve_parent(target, name)
+
+    if not inspect.ismodule(parent):
+        return parent, attribute
+
+    # Something may have layered its own subclass above ours after the
+    # install, so search the MRO rather than insisting on type(module).
+
+    for cls in type(parent).__mro__:
+        if _MODULE_BASE not in vars(cls):
+            continue
+        current = vars(cls).get(attribute, MISSING)
+        if current is not MISSING and wrapt.is_wrapped_by(current, descriptor):
+            return cls, attribute
+
+    raise LookupError(f"module {parent.__name__!r} does not hold {attribute!r}")
+
+
+def is_installed(target: Any, name: str, descriptor: AttributeDescriptor) -> bool:
+    """Whether a binding's descriptor is still in place at its location,
+    alone or within a chain of composed descriptors."""
+
+    try:
+        holder, attribute = _holder(target, name, descriptor)
+        current = wrapt.resolve_path(holder, attribute)[2]
+    except Exception:
+        return False
+
+    return bool(wrapt.is_wrapped_by(current, descriptor))
+
+
+def uninstall(
+    target: Any,
+    name: str,
+    descriptor: AttributeDescriptor,
+    *,
+    missing_ok: bool,
+) -> None:
+    """Remove a binding's descriptor, splicing it out of a composed
+    chain where needed, and for a module owner release the per-module
+    class once nothing else is installed on it."""
+
+    parent, attribute = _resolve_parent(target, name)
+
+    if not inspect.ismodule(parent):
+        wrapt.unwrap_object(parent, attribute, descriptor, missing_ok=missing_ok)
+        return
+
+    with _module_lock:
+        try:
+            cls, attribute = _holder(target, name, descriptor)
+        except LookupError:
+            if missing_ok:
+                return
+            raise ValueError(
+                f"module {parent.__name__!r} no longer holds the descriptor"
+                f" for {attribute!r}, so it cannot be removed"
+            ) from None
+
+        wrapt.unwrap_object(cls, attribute, descriptor, missing_ok=missing_ok)
+        _release_module(parent)