wrapture 1.0.0.dev1__tar.gz → 1.0.0.dev2__tar.gz

{wrapture-1.0.0.dev1/src/wrapture.egg-info → wrapture-1.0.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wrapture
-Version: 1.0.0.dev1
+Version: 1.0.0.dev2
 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
@@ -46,7 +46,22 @@ 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.
+> built. Development previews are published to PyPI; the API may still
+> shift before 1.0.0.
+
+## Installation
+
+wrapture is on [PyPI](https://pypi.org/project/wrapture/):
+
+```console
+$ pip install wrapture
+```
+
+or with uv:
+
+```console
+$ uv add wrapture
+```
 
 ## Documentation
 
@@ -152,4 +167,5 @@ testing assertion library, a tracing tool, or both at once.
 
 ## License
 
-BSD 2-Clause. See [LICENSE](LICENSE).
+BSD 2-Clause. See
+[LICENSE](https://github.com/GrahamDumpleton/wrapture/blob/develop/LICENSE).

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/README.md

@@ -15,7 +15,22 @@ 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.
+> built. Development previews are published to PyPI; the API may still
+> shift before 1.0.0.
+
+## Installation
+
+wrapture is on [PyPI](https://pypi.org/project/wrapture/):
+
+```console
+$ pip install wrapture
+```
+
+or with uv:
+
+```console
+$ uv add wrapture
+```
 
 ## Documentation
 
@@ -121,4 +136,5 @@ testing assertion library, a tracing tool, or both at once.
 
 ## License
 
-BSD 2-Clause. See [LICENSE](LICENSE).
+BSD 2-Clause. See
+[LICENSE](https://github.com/GrahamDumpleton/wrapture/blob/develop/LICENSE).

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/src/wrapture/__init__.py

@@ -17,9 +17,11 @@ def _format_version(parts: tuple[str, ...]) -> str:
     )
 
 
-__version_info__ = ("1", "0", "0", "dev1")
+__version_info__ = ("1", "0", "0", "dev2")
 __version__ = _format_version(__version_info__)
 
+from wrapt import MISSING
+
 from .behaviours import (
     CallBehaviour,
     DeleteBehaviour,
@@ -33,11 +35,6 @@ from .bindings import (
     bindings,
 )
 from .capture import (
-    NONE,
-    REFERENCE,
-    SNAPSHOT,
-    SUMMARY,
-    TYPES,
     redact,
 )
 from .eventlogs import (
@@ -56,17 +53,15 @@ from .exceptions import (
     WrongModeError,
 )
 from .iterators import (
-    AbandonBehaviour,
-    ErrorBehaviour,
-    FinishBehaviour,
-    ItemBehaviour,
+    IteratorAbandonBehaviour,
+    IteratorErrorBehaviour,
+    IteratorFinishBehaviour,
+    IteratorItemBehaviour,
     IteratorProxy,
     iterator,
 )
 from .stacks import (
     StackFrame,
-    caller,
-    full,
     stack_frames,
 )
 from .timeline import (
@@ -78,25 +73,21 @@ from .timeline import (
 )
 
 __all__ = [
-    "NONE",
-    "REFERENCE",
-    "SNAPSHOT",
-    "SUMMARY",
-    "TYPES",
-    "AbandonBehaviour",
+    "MISSING",
     "AlreadyAppliedError",
     "Binding",
     "BindingGroup",
     "CallBehaviour",
     "DeferredTargetError",
     "DeleteBehaviour",
-    "ErrorBehaviour",
     "Event",
     "EventLog",
     "ExpectationNotMetError",
-    "FinishBehaviour",
     "GetBehaviour",
-    "ItemBehaviour",
+    "IteratorAbandonBehaviour",
+    "IteratorErrorBehaviour",
+    "IteratorFinishBehaviour",
+    "IteratorItemBehaviour",
     "IteratorProxy",
     "NeverAppliedError",
     "NotImplementedYetError",
@@ -109,9 +100,7 @@ __all__ = [
     "annotate",
     "binding",
     "bindings",
-    "caller",
     "current_event",
-    "full",
     "iterator",
     "redact",
     "stack_frames",

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/src/wrapture/bindings.py

@@ -37,6 +37,7 @@ from .capture import (
     CapturePolicy,
     _capture_value,
     _level_of,
+    _resolve_policy,
 )
 from .eventlogs import EventLog
 from .events import Event, normalized_arguments
@@ -49,6 +50,7 @@ from .exceptions import (
     WrongModeError,
 )
 from .stacks import _capture as _capture_stack
+from .stacks import _resolve_depth
 from .timeline import (
     Tape,
     _capture_result,
@@ -356,20 +358,21 @@ class Binding:
         label: str | None = None,
         mode: str | None = None,
         missing_ok: bool = False,
-        capture: CapturePolicy | None = None,
-        capture_args: CapturePolicy | None = None,
-        capture_result: CapturePolicy | None = None,
-        stack: int | None = None,
+        capture: CapturePolicy | str | None = None,
+        capture_args: CapturePolicy | str | None = None,
+        capture_result: CapturePolicy | str | None = None,
+        stack: int | str | None = None,
     ) -> None:
         # Validate the target and settle the mode before anything is
         # stored, so a bad binding fails on the line that created it.
 
         _reject_deferred(target)
 
+        stack = _resolve_depth(stack)
         if stack is not None and stack < 1:
             raise ValueError(
-                f"stack must be None, wrapture.caller, wrapture.full or a"
-                f" positive frame count, got {stack!r}"
+                f"stack must be None, 'caller', 'full' or a positive"
+                f" frame count, got {stack!r}"
             )
 
         if mode is None:
@@ -390,8 +393,12 @@ class Binding:
         # consuming the events declares; capture= is shorthand for both
         # axes, with the specific parameters winning.
 
-        self._capture_args = capture_args if capture_args is not None else capture
-        self._capture_result = capture_result if capture_result is not None else capture
+        self._capture_args = _resolve_policy(
+            capture_args if capture_args is not None else capture
+        )
+        self._capture_result = _resolve_policy(
+            capture_result if capture_result is not None else capture
+        )
         self._stack_depth = stack
 
         # The behaviour pipelines, keyed by operation ("call", "get",
@@ -1052,10 +1059,10 @@ def binding(
     label: str | None = None,
     mode: str | None = None,
     missing_ok: bool = False,
-    capture: CapturePolicy | None = None,
-    capture_args: CapturePolicy | None = None,
-    capture_result: CapturePolicy | None = None,
-    stack: int | None = None,
+    capture: CapturePolicy | str | None = None,
+    capture_args: CapturePolicy | str | None = None,
+    capture_result: CapturePolicy | str | None = None,
+    stack: int | str | None = None,
 ) -> Binding:
     """Create a binding for one target attribute.
 
@@ -1071,15 +1078,16 @@ def binding(
     AttributeError, because it is indistinguishable from a typo.
 
     `capture=` overrides how much of the recorded values this binding
-    stores (a level such as SUMMARY, or a fn(name, value) callable),
-    with `capture_args=` and `capture_result=` controlling the two axes
-    separately and winning over the shorthand. Left unset, the binding
+    stores: a level named by string ("none", "types", "reference",
+    "summary" or "snapshot"), or a fn(name, value) callable.
+    `capture_args=` and `capture_result=` control the two axes
+    separately and win over the shorthand. Left unset, the binding
     follows what the sink consuming the events declares.
 
     `stack=` captures how control reached each recorded event:
-    wrapture.caller for just the calling frame, a frame count, or
-    wrapture.full for the whole stack. The default None captures
-    nothing and costs nothing.
+    "caller" for just the calling frame, a frame count, or "full" for
+    the whole stack. The default None captures nothing and costs
+    nothing.
 
     Does NOT apply the wrapper; call apply() or use the binding as a
     context manager.

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/src/wrapture/capture.py

@@ -35,6 +35,32 @@ SNAPSHOT = 4
 
 CapturePolicy = int | Callable[[str | None, Any], Any]
 
+# The user-facing spellings of the levels: binding() and redact() accept
+# these strings and resolve them to the numeric levels above.
+
+_LEVEL_NAMES = {
+    "none": NONE,
+    "types": TYPES,
+    "reference": REFERENCE,
+    "summary": SUMMARY,
+    "snapshot": SNAPSHOT,
+}
+
+
+def _resolve_policy(policy: CapturePolicy | str | None) -> CapturePolicy | None:
+    if isinstance(policy, str):
+        try:
+            return _LEVEL_NAMES[policy]
+        except KeyError:
+            raise ValueError(
+                f"capture level must be one of {sorted(_LEVEL_NAMES)}, a"
+                f" numeric level, or a fn(name, value) callable, got"
+                f" {policy!r}"
+            ) from None
+
+    return policy
+
+
 _ATOMIC = (bool, int, float, complex, type(None))
 
 
@@ -100,7 +126,9 @@ def summarize(value: Any, *, limit: int = 200, items: int = 10) -> Any:
 
 
 def redact(
-    *names: str, level: CapturePolicy = REFERENCE, marker: str = "<redacted>"
+    *names: str,
+    level: CapturePolicy | str = REFERENCE,
+    marker: str = "<redacted>",
 ) -> CapturePolicy:
     """A capture policy that replaces named parameters with a marker.
 
@@ -119,6 +147,8 @@ def redact(
     """
 
     wanted = set(names)
+    resolved = _resolve_policy(level)
+    level = REFERENCE if resolved is None else resolved
 
     def policy(name: str | None, value: Any) -> Any:
         if name in wanted:

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/src/wrapture/iterators.py

@@ -227,7 +227,7 @@ class _IteratorBehaviour:
         self._factory = factory
 
 
-class ItemBehaviour(_IteratorBehaviour):
+class IteratorItemBehaviour(_IteratorBehaviour):
     """`iterator().on_item`: behaviour applied to each item.
 
     Mirrors the composing half of a binding's on_call: stages accumulate
@@ -260,7 +260,7 @@ class ItemBehaviour(_IteratorBehaviour):
         return self._factory._clear(self._factory._item_stages)
 
 
-class FinishBehaviour(_IteratorBehaviour):
+class IteratorFinishBehaviour(_IteratorBehaviour):
     """`iterator().on_finish`: behaviour for normal exhaustion.
 
     Checks receive the wrapped generator's return value, or None for
@@ -280,7 +280,7 @@ class FinishBehaviour(_IteratorBehaviour):
         return self._factory._clear(self._factory._finish_checks)
 
 
-class ErrorBehaviour(_IteratorBehaviour):
+class IteratorErrorBehaviour(_IteratorBehaviour):
     """`iterator().on_error`: behaviour for a failed iteration.
 
     Hooks receive the exception about to reach the consumer, whether it
@@ -302,7 +302,7 @@ class ErrorBehaviour(_IteratorBehaviour):
         return self._factory._clear(self._factory._error_hooks)
 
 
-class AbandonBehaviour(_IteratorBehaviour):
+class IteratorAbandonBehaviour(_IteratorBehaviour):
     """`iterator().on_abandon`: behaviour for an abandoned iteration.
 
     Hooks fire when a started, unexhausted wrapped generator is closed,
@@ -343,28 +343,28 @@ class IteratorProxy:
         self._abandon_hooks: list[AbandonFunction] = []
 
     @property
-    def on_item(self) -> ItemBehaviour:
+    def on_item(self) -> IteratorItemBehaviour:
         """The behaviour namespace for items."""
 
-        return ItemBehaviour(self)
+        return IteratorItemBehaviour(self)
 
     @property
-    def on_finish(self) -> FinishBehaviour:
+    def on_finish(self) -> IteratorFinishBehaviour:
         """The behaviour namespace for normal exhaustion."""
 
-        return FinishBehaviour(self)
+        return IteratorFinishBehaviour(self)
 
     @property
-    def on_error(self) -> ErrorBehaviour:
+    def on_error(self) -> IteratorErrorBehaviour:
         """The behaviour namespace for a failed iteration."""
 
-        return ErrorBehaviour(self)
+        return IteratorErrorBehaviour(self)
 
     @property
-    def on_abandon(self) -> AbandonBehaviour:
+    def on_abandon(self) -> IteratorAbandonBehaviour:
         """The behaviour namespace for an abandoned iteration."""
 
-        return AbandonBehaviour(self)
+        return IteratorAbandonBehaviour(self)
 
     def _add(self, hooks: list[Any], fn: Any) -> Self:
         hooks.append(fn)

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/src/wrapture/stacks.py

@@ -34,12 +34,29 @@ class StackFrame(NamedTuple):
     function: str
 
 
-# The stack= argument to binding(): capture just the calling frame, or
-# every frame. Any other positive integer captures that many frames.
+# The depths behind the stack= argument to binding(): "caller" captures
+# just the calling frame, "full" every frame, and any positive integer
+# captures that many frames.
 
 caller: Final[int] = 1
 full: Final[int] = sys.maxsize
 
+_DEPTH_NAMES = {"caller": caller, "full": full}
+
+
+def _resolve_depth(stack: int | str | None) -> int | None:
+    if isinstance(stack, str):
+        try:
+            return _DEPTH_NAMES[stack]
+        except KeyError:
+            raise ValueError(
+                f"stack must be None, 'caller', 'full' or a positive"
+                f" frame count, got {stack!r}"
+            ) from None
+
+    return stack
+
+
 # Frames of the observation machinery itself are elided, so a captured
 # stack starts at the code under observation.
 

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2/src/wrapture.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wrapture
-Version: 1.0.0.dev1
+Version: 1.0.0.dev2
 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
@@ -46,7 +46,22 @@ 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.
+> built. Development previews are published to PyPI; the API may still
+> shift before 1.0.0.
+
+## Installation
+
+wrapture is on [PyPI](https://pypi.org/project/wrapture/):
+
+```console
+$ pip install wrapture
+```
+
+or with uv:
+
+```console
+$ uv add wrapture
+```
 
 ## Documentation
 
@@ -152,4 +167,5 @@ testing assertion library, a tracing tool, or both at once.
 
 ## License
 
-BSD 2-Clause. See [LICENSE](LICENSE).
+BSD 2-Clause. See
+[LICENSE](https://github.com/GrahamDumpleton/wrapture/blob/develop/LICENSE).

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/tests/test_attribute_events.py

@@ -10,7 +10,7 @@ from typing import Any
 import pytest
 from wrapt import MISSING
 
-from wrapture import SUMMARY, annotate, binding, redact, timeline
+from wrapture import annotate, binding, redact, timeline
 
 
 class Model:
@@ -216,7 +216,7 @@ def test_calls_triggered_by_a_property_read_nest_under_the_get_event() -> None:
 
 
 def test_set_values_capture_at_the_argument_level() -> None:
-    status = binding(Model, "status", missing_ok=True, capture=SUMMARY)
+    status = binding(Model, "status", missing_ok=True, capture="summary")
     model = Model()
     tags = ["a", "b"]
 

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/tests/test_capture.py

@@ -12,17 +12,13 @@ from typing import Any
 from wrapt import MISSING
 
 from wrapture import (
-    NONE,
-    SNAPSHOT,
-    SUMMARY,
-    TYPES,
     annotate,
     binding,
     current_event,
     redact,
     timeline,
 )
-from wrapture.capture import summarize, type_name
+from wrapture.capture import NONE, summarize, type_name
 
 
 class Ledger:
@@ -59,7 +55,7 @@ def test_reference_default_stores_references() -> None:
 
 
 def test_summary_snapshots_a_bounded_repr() -> None:
-    record = binding(Ledger, "record", capture=SUMMARY)
+    record = binding(Ledger, "record", capture="summary")
     entries = ["a", "b"]
 
     with timeline(record):
@@ -75,7 +71,7 @@ def test_summary_snapshots_a_bounded_repr() -> None:
 
 
 def test_types_records_type_names_only() -> None:
-    record = binding(Ledger, "record", capture=TYPES)
+    record = binding(Ledger, "record", capture="types")
 
     with timeline(record):
         Ledger().record(["a"])
@@ -87,7 +83,7 @@ def test_types_records_type_names_only() -> None:
 
 
 def test_none_keeps_the_event_but_no_values() -> None:
-    record = binding(Ledger, "record", capture=NONE)
+    record = binding(Ledger, "record", capture="none")
 
     with timeline(record):
         Ledger().record(["a"])
@@ -100,7 +96,7 @@ def test_none_keeps_the_event_but_no_values() -> None:
 
 
 def test_snapshot_deepcopies_and_falls_back_where_it_cannot() -> None:
-    record = binding(Ledger, "record", capture=SNAPSHOT)
+    record = binding(Ledger, "record", capture="snapshot")
     entries = ["a", "b"]
 
     with timeline(record):
@@ -121,7 +117,7 @@ def test_snapshot_deepcopies_and_falls_back_where_it_cannot() -> None:
 
 
 def test_specific_axis_wins_over_the_shorthand() -> None:
-    record = binding(Ledger, "record", capture=NONE, capture_result=SUMMARY)
+    record = binding(Ledger, "record", capture="none", capture_result="summary")
 
     with timeline(record):
         Ledger().record(["a"])
@@ -154,6 +150,25 @@ def test_redact_matches_by_name_however_the_caller_passed_it() -> None:
         assert vault.events.first.result == "opened:hunter2"
 
 
+def test_a_misspelled_capture_level_raises_at_creation() -> None:
+    import pytest
+
+    with pytest.raises(ValueError, match="capture level must be"):
+        binding(Ledger, "record", capture="sumary")
+
+
+def test_redact_accepts_a_level_name_for_everything_unnamed() -> None:
+    vault = binding(Vault, "open", capture_args=redact("secret", level="types"))
+
+    with timeline(vault):
+        Vault().open("hunter2", attempts=3)
+
+        event = vault.events.first
+        assert event.arguments is not None
+        assert event.arguments["secret"] == "<redacted>"
+        assert event.arguments["attempts"] == "<int>"
+
+
 def test_a_custom_callable_is_a_policy() -> None:
     def masked(name: str | None, value: Any) -> Any:
         return f"{name}!{value}"

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/tests/test_events.py

@@ -24,6 +24,15 @@ def charge(amount: int, currency: str = "USD", *, retries: int = 3) -> None:
 # ---------------------------------------------------------------------------
 
 
+def test_missing_is_reexported_from_wrapture() -> None:
+    # Docs teach `event.result is MISSING`; the sentinel is reachable
+    # without knowing it comes from wrapt.
+
+    import wrapture
+
+    assert wrapture.MISSING is MISSING
+
+
 def test_call_event_defaults() -> None:
     event = Event("call", "Gateway.charge")
 

{wrapture-1.0.0.dev1 → wrapture-1.0.0.dev2}/tests/test_stacks.py

@@ -10,7 +10,7 @@ from typing import Any
 
 import pytest
 
-from wrapture import binding, caller, full, stack_frames, timeline
+from wrapture import binding, stack_frames, timeline
 from wrapture.stacks import _stacks
 
 
@@ -44,7 +44,7 @@ def test_no_capture_by_default() -> None:
 
 
 def test_caller_captures_exactly_the_calling_frame() -> None:
-    charge = binding(Gateway, "charge", stack=caller)
+    charge = binding(Gateway, "charge", stack="caller")
 
     with timeline(charge):
         place_order(Gateway())
@@ -75,7 +75,7 @@ def test_a_frame_count_walks_outward_from_the_caller() -> None:
 
 
 def test_full_captures_more_than_caller() -> None:
-    charge = binding(Gateway, "charge", stack=full)
+    charge = binding(Gateway, "charge", stack="full")
 
     with timeline(charge):
         place_order(Gateway())
@@ -92,6 +92,9 @@ def test_an_invalid_depth_is_rejected_at_creation() -> None:
     with pytest.raises(ValueError, match="stack must be"):
         binding(Gateway, "charge", stack=0)
 
+    with pytest.raises(ValueError, match="stack must be"):
+        binding(Gateway, "charge", stack="fll")
+
 
 # ---------------------------------------------------------------------------
 # interning
@@ -99,7 +102,7 @@ def test_an_invalid_depth_is_rejected_at_creation() -> None:
 
 
 def test_repeated_captures_from_one_site_intern_to_one_stack() -> None:
-    charge = binding(Gateway, "charge", stack=caller)
+    charge = binding(Gateway, "charge", stack="caller")
 
     with timeline(charge):
         gateway = Gateway()
@@ -114,7 +117,7 @@ def test_repeated_captures_from_one_site_intern_to_one_stack() -> None:
 
 
 def test_different_call_sites_intern_to_different_stacks() -> None:
-    charge = binding(Gateway, "charge", stack=caller)
+    charge = binding(Gateway, "charge", stack="caller")
 
     with timeline(charge):
         gateway = Gateway()
@@ -134,7 +137,7 @@ def test_different_call_sites_intern_to_different_stacks() -> None:
 
 
 def test_an_attribute_read_names_the_line_that_triggered_it() -> None:
-    total = binding(Model, "total", stack=caller)
+    total = binding(Model, "total", stack="caller")
 
     def render(model: Model) -> str:
         return f"total: {model.total}"
@@ -164,7 +167,7 @@ def test_no_wrapture_or_wrapt_frames_appear() -> None:
         os.path.dirname(os.path.abspath(wrapt.__file__)),
     )
 
-    charge = binding(Gateway, "charge", stack=full)
+    charge = binding(Gateway, "charge", stack="full")
 
     with timeline(charge):
         place_order(Gateway())
@@ -180,7 +183,7 @@ def test_capture_works_through_behaviour() -> None:
     def note(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
         return args, kwargs
 
-    charge = binding(Gateway, "charge", stack=caller).on_call.transforms_args(note)
+    charge = binding(Gateway, "charge", stack="caller").on_call.transforms_args(note)
 
     with timeline(charge):
         place_order(Gateway())