wrapture 1.0.0.dev4__tar.gz → 1.0.0.dev7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wrapture
-Version: 1.0.0.dev4
+Version: 1.0.0.dev7
 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
@@ -31,7 +31,7 @@ Dynamic: license-file
 
 # wrapture
 
-**Trace assertions without instrumenting your code.**
+**Wrap anything, capture everything, change nothing.**
 
 [![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)
@@ -70,7 +70,10 @@ Start with the [getting started](https://wrapture.readthedocs.io/en/latest/getti
 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.
+mapping each mock idiom to its wrapture counterpart. After that, the
+worked examples, starting with
+[testing code that calls external services](https://wrapture.readthedocs.io/en/latest/example-external-services.html),
+each take one question you might arrive with and answer it end to end.
 
 ## Thirty seconds of it
 
@@ -163,6 +166,13 @@ testing assertion library, a tracing tool, or both at once.
 - Python 3.12+
 - [wrapt](https://github.com/GrahamDumpleton/wrapt) 2.4.0+
 
+## Issues
+
+Bug reports and feature requests go to the
+[issue tracker](https://github.com/GrahamDumpleton/wrapture/issues).
+Include the wrapture and Python versions and, where you can, a small
+binding that reproduces the problem.
+
 ## License
 
 BSD 2-Clause. See

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

@@ -1,6 +1,6 @@
 # wrapture
 
-**Trace assertions without instrumenting your code.**
+**Wrap anything, capture everything, change nothing.**
 
 [![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)
@@ -39,7 +39,10 @@ Start with the [getting started](https://wrapture.readthedocs.io/en/latest/getti
 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.
+mapping each mock idiom to its wrapture counterpart. After that, the
+worked examples, starting with
+[testing code that calls external services](https://wrapture.readthedocs.io/en/latest/example-external-services.html),
+each take one question you might arrive with and answer it end to end.
 
 ## Thirty seconds of it
 
@@ -132,6 +135,13 @@ testing assertion library, a tracing tool, or both at once.
 - Python 3.12+
 - [wrapt](https://github.com/GrahamDumpleton/wrapt) 2.4.0+
 
+## Issues
+
+Bug reports and feature requests go to the
+[issue tracker](https://github.com/GrahamDumpleton/wrapture/issues).
+Include the wrapture and Python versions and, where you can, a small
+binding that reproduces the problem.
+
 ## License
 
 BSD 2-Clause. See

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

@@ -17,10 +17,10 @@ def _format_version(parts: tuple[str, ...]) -> str:
     )
 
 
-__version_info__ = ("1", "0", "0", "dev4")
+__version_info__ = ("1", "0", "0", "dev7")
 __version__ = _format_version(__version_info__)
 
-from wrapt import MISSING
+from wrapt import MISSING, register_post_import_hook, when_imported
 
 from .asgi import (
     ASGIMiddleware,
@@ -131,6 +131,8 @@ from .wsgi import (
 
 __all__ = [
     "MISSING",
+    "register_post_import_hook",
+    "when_imported",
     "ASGIMiddleware",
     "Aggregate",
     "AlreadyAppliedError",

{wrapture-1.0.0.dev4 → wrapture-1.0.0.dev7}/src/wrapture/bindings.py

@@ -135,7 +135,8 @@ def _reject_deferred(target: Any) -> None:
             f" wrapt's trailing `?` syntax. A deferred wrap registers a"
             f" post-import hook and returns no handle, so a binding would"
             f" have nothing to remove, suspend or query. Import the module"
-            f" first and bind against it."
+            f" first and bind against it, or create the binding inside a"
+            f" `wrapture.when_imported` hook for that module."
         )
 
 

{wrapture-1.0.0.dev4 → wrapture-1.0.0.dev7}/src/wrapture/events.py

@@ -181,9 +181,17 @@ def _format_time(seconds: float) -> str:
 def _own_time(event: Event) -> float | None:
     # The execution-time basis for self-time arithmetic. A generator's
     # wall duration includes the consumer's time between yields, so its
-    # accumulated body time is the honest measure of the code itself;
-    # everything else uses its duration. None when the event has not
-    # closed with a time.
+    # accumulated body time is the honest measure of the code itself. A
+    # request has two phases of application code, the synchronous call
+    # and the body it then streams, and its own time is their sum, again
+    # leaving out the server's time between chunks. Everything else uses
+    # its duration. None when the event has not closed with a time.
+
+    if event.kind == "request" and event.body_duration is not None:
+        app_duration = event.data.get("app_duration")
+        if app_duration is None:
+            return event.duration
+        return float(app_duration) + event.body_duration
 
     if event.body_duration is not None:
         return event.body_duration

{wrapture-1.0.0.dev4 → wrapture-1.0.0.dev7}/src/wrapture/exceptions.py

@@ -48,7 +48,8 @@ class NotImplementedYetError(NotImplementedError):
 
 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.
+    which is not supported. Import the module first and bind against it,
+    or create the binding inside a `wrapture.when_imported` hook.
     """
 
 

{wrapture-1.0.0.dev4 → wrapture-1.0.0.dev7}/src/wrapture/timeline.py

@@ -246,8 +246,13 @@ class Tape(Sink):
         def emit(event: Event) -> None:
             injected = " (injected)" if event.injected else ""
 
+            # A get event's str() already carries its value, so only the
+            # injected mark is added to it.
+
             if event.exception is not None:
                 marker = f"  !! {type(event.exception).__name__}{injected}"
+            elif event.kind == "get":
+                marker = injected
             elif event.result is not MISSING:
                 marker = f"  -> {event.result!r}{injected}"
             else:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wrapture
-Version: 1.0.0.dev4
+Version: 1.0.0.dev7
 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
@@ -31,7 +31,7 @@ Dynamic: license-file
 
 # wrapture
 
-**Trace assertions without instrumenting your code.**
+**Wrap anything, capture everything, change nothing.**
 
 [![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)
@@ -70,7 +70,10 @@ Start with the [getting started](https://wrapture.readthedocs.io/en/latest/getti
 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.
+mapping each mock idiom to its wrapture counterpart. After that, the
+worked examples, starting with
+[testing code that calls external services](https://wrapture.readthedocs.io/en/latest/example-external-services.html),
+each take one question you might arrive with and answer it end to end.
 
 ## Thirty seconds of it
 
@@ -163,6 +166,13 @@ testing assertion library, a tracing tool, or both at once.
 - Python 3.12+
 - [wrapt](https://github.com/GrahamDumpleton/wrapt) 2.4.0+
 
+## Issues
+
+Bug reports and feature requests go to the
+[issue tracker](https://github.com/GrahamDumpleton/wrapture/issues).
+Include the wrapture and Python versions and, where you can, a small
+binding that reproduces the problem.
+
 ## License
 
 BSD 2-Clause. See

{wrapture-1.0.0.dev4 → wrapture-1.0.0.dev7}/tests/test_bindings.py

@@ -250,6 +250,24 @@ def test_deferred_target_error_is_a_value_error() -> None:
     assert issubclass(DeferredTargetError, ValueError)
 
 
+def test_deferred_target_error_points_at_when_imported() -> None:
+    with pytest.raises(DeferredTargetError, match="wrapture.when_imported"):
+        binding("mymodule?", "handler")
+
+
+def test_post_import_hook_helpers_are_reexported_from_wrapt() -> None:
+    # The supported route to patching a module before it is imported is
+    # a post-import hook, so wrapt's helpers are available under the
+    # wrapture name to save application code importing wrapt for them.
+
+    import wrapture
+
+    assert wrapture.when_imported is wrapt.when_imported
+    assert wrapture.register_post_import_hook is wrapt.register_post_import_hook
+    assert "when_imported" in wrapture.__all__
+    assert "register_post_import_hook" in wrapture.__all__
+
+
 # ---------------------------------------------------------------------------
 # modes and behaviour namespaces
 # ---------------------------------------------------------------------------

{wrapture-1.0.0.dev4 → wrapture-1.0.0.dev7}/tests/test_events.py

@@ -9,10 +9,16 @@ import gc
 import weakref
 from typing import Any
 
+import pytest
 from wrapt import MISSING
 
 from wrapture import Event
-from wrapture.events import _signature, _signature_cache, normalized_arguments
+from wrapture.events import (
+    _own_time,
+    _signature,
+    _signature_cache,
+    normalized_arguments,
+)
 
 
 def charge(amount: int, currency: str = "USD", *, retries: int = 3) -> None:
@@ -189,3 +195,21 @@ def test_cache_does_not_keep_the_function_alive() -> None:
 
     gc.collect()
     assert alive() is None
+
+
+def test_own_time_of_a_request_sums_both_application_phases() -> None:
+    # A request's own time is the synchronous call plus the body it
+    # produced, not the wall time that includes the server between chunks.
+
+    request = Event(kind="request", path="app:wsgi_app", duration=1.0)
+    request.body_duration = 0.2
+    request.data["app_duration"] = 0.3
+
+    assert _own_time(request) == pytest.approx(0.5)
+
+
+def test_own_time_of_a_generator_is_its_body_time() -> None:
+    call = Event(kind="call", path="mod:gen", duration=1.0)
+    call.body_duration = 0.25
+
+    assert _own_time(call) == 0.25

{wrapture-1.0.0.dev4 → wrapture-1.0.0.dev7}/tests/test_timeline.py

@@ -354,6 +354,18 @@ def test_tree_renders_nesting_results_and_failures() -> None:
     assert lines[2] == "Gateway.refund(amount=100)  !! TimeoutError (injected)"
 
 
+def test_tree_shows_a_get_event_value_once() -> None:
+    class Settings:
+        retries = 3
+
+    retries = binding(Settings, "retries")
+
+    with timeline(retries) as tape:
+        _ = Settings().retries
+
+    assert tape.tree() == "get Settings.retries -> 3"
+
+
 def test_tree_of_an_empty_tape_is_empty() -> None:
     with timeline() as tape:
         pass