wrapture 1.0.0.dev2__tar.gz → 1.0.0.dev3__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: wrapture
-Version: 1.0.0.dev2
-Summary: Library for attaching bindings to arbitrary Python call sites for monkey patching, testing, tracing and profiling.
+Version: 1.0.0.dev3
+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
 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
+Keywords: wrapper,monkey patching,tracing,testing
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -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 and unit testing layers
-> are implemented; the tracing and profiling layers are designed but not
-> built. Development previews are published to PyPI; the API may still
-> shift before 1.0.0.
+> **Status: early development.** The monkey patching, unit testing and
+> ad-hoc tracing layers are implemented, including WSGI request tracing.
+> Development previews are published to PyPI; the API may still shift
+> before 1.0.0.
 
 ## Installation
 
@@ -98,7 +98,7 @@ failure, or transform one argument while the real code keeps running.
 
 ## What it does
 
-One mechanism, four uses, in increasing order of machinery:
+One mechanism, three 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,
@@ -119,16 +119,17 @@ One mechanism, four uses, in increasing order of machinery:
 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.
+   appears; no code changes required: with a `wrapture.toml` naming the
+   methods and a sink, `python -m wrapture manage.py runserver` traces the
+   application untouched. With [autowrapt](https://github.com/GrahamDumpleton/autowrapt)
+   installed, not even the launcher is needed: `AUTOWRAPT_BOOTSTRAP=wrapture`
+   in the environment applies the same config at interpreter startup, so the
+   program starts with plain `python`.
+
+The distinction that matters: most tracing 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
 
@@ -142,8 +143,7 @@ nested trace, assert on it or export it, in tests or in production":
   `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.
+- 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
@@ -153,8 +153,6 @@ testing assertion library, a tracing tool, or both at once.
 
 - **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

{wrapture-1.0.0.dev2 → wrapture-1.0.0.dev3}/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 and unit testing layers
-> are implemented; the tracing and profiling layers are designed but not
-> built. Development previews are published to PyPI; the API may still
-> shift before 1.0.0.
+> **Status: early development.** The monkey patching, unit testing and
+> ad-hoc tracing layers are implemented, including WSGI request tracing.
+> Development previews are published to PyPI; the API may still shift
+> before 1.0.0.
 
 ## Installation
 
@@ -67,7 +67,7 @@ failure, or transform one argument while the real code keeps running.
 
 ## What it does
 
-One mechanism, four uses, in increasing order of machinery:
+One mechanism, three 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,
@@ -88,16 +88,17 @@ One mechanism, four uses, in increasing order of machinery:
 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.
+   appears; no code changes required: with a `wrapture.toml` naming the
+   methods and a sink, `python -m wrapture manage.py runserver` traces the
+   application untouched. With [autowrapt](https://github.com/GrahamDumpleton/autowrapt)
+   installed, not even the launcher is needed: `AUTOWRAPT_BOOTSTRAP=wrapture`
+   in the environment applies the same config at interpreter startup, so the
+   program starts with plain `python`.
+
+The distinction that matters: most tracing 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
 
@@ -111,8 +112,7 @@ nested trace, assert on it or export it, in tests or in production":
   `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.
+- 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
@@ -122,8 +122,6 @@ testing assertion library, a tracing tool, or both at once.
 
 - **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

{wrapture-1.0.0.dev2 → wrapture-1.0.0.dev3}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "wrapture"
 dynamic = ["version"]
-description = "Library for attaching bindings to arbitrary Python call sites for monkey patching, testing, tracing and profiling."
+description = "Monkey patch, test, and trace Python by attaching bindings to call sites, without modifying the code being observed. Built on wrapt."
 readme = "README.md"
 license = "BSD-2-Clause"
 license-files = ["LICENSE"]
@@ -15,7 +15,7 @@ authors = [
     {name = "Graham Dumpleton", email = "Graham.Dumpleton@gmail.com"}
 ]
 requires-python = ">=3.12"
-keywords = ["wrapper", "monkey patching", "tracing", "testing", "profiling"]
+keywords = ["wrapper", "monkey patching", "tracing", "testing"]
 classifiers = [
     "Development Status :: 2 - Pre-Alpha",
     "Programming Language :: Python :: 3",
@@ -33,6 +33,18 @@ Homepage = "https://github.com/GrahamDumpleton/wrapture"
 Documentation = "https://wrapture.readthedocs.io"
 "Bug Tracker" = "https://github.com/GrahamDumpleton/wrapture/issues/"
 
+# The zero-code injection trigger, in the shape autowrapt consumes:
+# AUTOWRAPT_BOOTSTRAP=wrapture names this entry point group, which
+# autowrapt hands to wrapt.discover_post_import_hooks() at interpreter
+# startup. Each entry maps a trigger module to a callback; hooking os,
+# which is always already imported by then, makes the callback fire
+# immediately at startup. Inert metadata unless autowrapt is installed
+# and the environment variable is set; wrapture itself has no
+# dependency on autowrapt and never imports it.
+
+[project.entry-points.wrapture]
+os = "wrapture.bootstrap:bootstrap"
+
 [project.optional-dependencies]
 dev = [
     "mypy",
@@ -49,7 +61,7 @@ docs = [
 [tool.setuptools]
 package-dir = {"" = "src"}
 zip-safe = false
-packages = ["wrapture"]
+packages = ["wrapture", "wrapture.tools"]
 
 [tool.setuptools.package-data]
 wrapture = ["py.typed"]

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

@@ -1,7 +1,7 @@
 """
 Wrapture is a library for attaching bindings to arbitrary Python call sites,
 without modifying the code being observed, for use in monkey patching,
-testing, tracing and profiling.
+testing and tracing.
 """
 
 
@@ -17,7 +17,7 @@ def _format_version(parts: tuple[str, ...]) -> str:
     )
 
 
-__version_info__ = ("1", "0", "0", "dev2")
+__version_info__ = ("1", "0", "0", "dev3")
 __version__ = _format_version(__version_info__)
 
 from wrapt import MISSING
@@ -33,10 +33,19 @@ from .bindings import (
     BindingGroup,
     binding,
     bindings,
+    discover,
 )
 from .capture import (
     redact,
 )
+from .config import (
+    AppliedConfig,
+    Config,
+    ObserveEntry,
+    SetupEntry,
+    find_config,
+    load_config,
+)
 from .eventlogs import (
     EventLog,
 )
@@ -45,13 +54,22 @@ from .events import (
 )
 from .exceptions import (
     AlreadyAppliedError,
+    ConfigError,
+    ConfigWarning,
     DeferredTargetError,
     ExpectationNotMetError,
     NeverAppliedError,
     NotImplementedYetError,
     RecordingGapWarning,
+    SinkErrorWarning,
     WrongModeError,
 )
+from .export import (
+    canonical,
+    chrome_trace,
+    load_events,
+    mermaid,
+)
 from .iterators import (
     IteratorAbandonBehaviour,
     IteratorErrorBehaviour,
@@ -60,8 +78,28 @@ from .iterators import (
     IteratorProxy,
     iterator,
 )
+from .observed import (
+    ObservedCallable,
+    observed,
+)
+from .sinks import (
+    Aggregate,
+    Counter,
+    Depth,
+    Fanout,
+    Filter,
+    JSONLines,
+    PathStats,
+    Printer,
+    Sample,
+    Sink,
+    add_sink,
+    flush_sinks,
+    remove_sink,
+)
 from .stacks import (
     StackFrame,
+    clear_stacks,
     stack_frames,
 )
 from .timeline import (
@@ -69,40 +107,76 @@ from .timeline import (
     Timeline,
     annotate,
     current_event,
+    propagate,
     timeline,
 )
+from .wsgi import (
+    WSGIMiddleware,
+)
 
 __all__ = [
     "MISSING",
+    "Aggregate",
     "AlreadyAppliedError",
+    "AppliedConfig",
     "Binding",
     "BindingGroup",
     "CallBehaviour",
+    "Config",
+    "ConfigError",
+    "ConfigWarning",
+    "Counter",
     "DeferredTargetError",
     "DeleteBehaviour",
+    "Depth",
     "Event",
     "EventLog",
     "ExpectationNotMetError",
+    "Fanout",
+    "Filter",
     "GetBehaviour",
     "IteratorAbandonBehaviour",
     "IteratorErrorBehaviour",
     "IteratorFinishBehaviour",
     "IteratorItemBehaviour",
     "IteratorProxy",
+    "JSONLines",
     "NeverAppliedError",
     "NotImplementedYetError",
+    "ObserveEntry",
+    "ObservedCallable",
+    "PathStats",
+    "Printer",
     "RecordingGapWarning",
+    "Sample",
     "SetBehaviour",
+    "SetupEntry",
+    "Sink",
+    "SinkErrorWarning",
     "StackFrame",
     "Tape",
     "Timeline",
+    "WSGIMiddleware",
     "WrongModeError",
+    "add_sink",
     "annotate",
     "binding",
     "bindings",
+    "canonical",
+    "chrome_trace",
+    "clear_stacks",
     "current_event",
+    "discover",
+    "find_config",
+    "flush_sinks",
     "iterator",
+    "load_config",
+    "load_events",
+    "mermaid",
+    "observed",
+    "propagate",
     "redact",
+    "remove_sink",
     "stack_frames",
     "timeline",
 ]

wrapture-1.0.0.dev3/src/wrapture/__main__.py

@@ -0,0 +1,148 @@
+"""Run a Python program with a wrapture config applied first.
+
+    python -m wrapture [--config PATH] (-m MODULE | SCRIPT) [ARGS...]
+
+The config is resolved, loaded and applied before the target runs, so
+patches land before the target module imports anything: the same
+ordering guarantee the injection path gives. The target then runs as
+__main__ with sys.argv rebuilt to the target and its arguments,
+exactly as python itself would have run it.
+
+This module is the runner's entry point only, the same private -m
+convention as pdb, cProfile and coverage: run it, do not import it.
+"""
+
+from __future__ import annotations
+
+import os
+import runpy
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import NoReturn
+
+from .config import find_config, load_config
+from .exceptions import ConfigError
+
+_USAGE = """\
+usage: python -m wrapture [--config PATH] (-m MODULE | SCRIPT) [ARGS...]
+
+Apply a wrapture config, then run the target as __main__ with ARGS as
+its arguments. With --config the named TOML file is used; without it
+the standard precedence chain locates one: a path in WRAPTURE_CONFIG,
+wrapture.toml in the current directory, then a [tool.wrapture] table
+in pyproject.toml. Everything after the target belongs to the target,
+so wrapture's own options must come before it.
+
+Trace files a run produces can be rendered in other formats with
+python -m wrapture.tools convert.
+"""
+
+
+@dataclass(frozen=True)
+class _Invocation:
+    config: str | None
+    module: str | None
+    script: str | None
+    arguments: tuple[str, ...]
+
+
+def _usage_error(message: str) -> NoReturn:
+    print(f"wrapture: {message}", file=sys.stderr)
+    print(_USAGE, file=sys.stderr, end="")
+    raise SystemExit(2)
+
+
+def _parse(argv: Sequence[str]) -> _Invocation:
+    """Split the command line into wrapture's own options and the
+    target with its arguments.
+
+    Parsing stops at the first target: everything after -m MODULE or
+    the script path is the target's own, however option-like it
+    looks, matching how python itself treats a command line.
+    """
+
+    config: str | None = None
+    pending = list(argv)
+
+    while pending:
+        argument = pending[0]
+
+        if argument in ("-h", "--help"):
+            print(_USAGE, end="")
+            raise SystemExit(0)
+
+        if argument == "--config":
+            if len(pending) < 2:
+                _usage_error("--config requires a path")
+            config = pending[1]
+            del pending[:2]
+            continue
+
+        if argument.startswith("--config="):
+            config = argument.partition("=")[2]
+            if not config:
+                _usage_error("--config requires a path")
+            del pending[0]
+            continue
+
+        if argument == "-m":
+            if len(pending) < 2:
+                _usage_error("-m requires a module name")
+            return _Invocation(config, pending[1], None, tuple(pending[2:]))
+
+        if argument.startswith("-"):
+            _usage_error(f"unknown option {argument!r}")
+
+        return _Invocation(config, None, argument, tuple(pending[1:]))
+
+    _usage_error("a target is required: -m MODULE or a script path")
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Parse the command line, apply the config, and run the target."""
+
+    invocation = _parse(sys.argv[1:] if argv is None else argv)
+
+    # Resolve and apply the config before anything else happens, so
+    # patches and setup hooks are in place before the target module
+    # imports anything. Finding no config is an error rather than a
+    # silent untraced run.
+
+    source = invocation.config if invocation.config is not None else find_config()
+
+    if source is None:
+        print(
+            "wrapture: no config found: pass --config PATH, set"
+            " WRAPTURE_CONFIG, or provide wrapture.toml or a"
+            " [tool.wrapture] table in pyproject.toml in the current"
+            " directory",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+    try:
+        load_config(source).apply()
+    except ConfigError as exc:
+        print(f"wrapture: {exc}", file=sys.stderr)
+        raise SystemExit(1) from None
+
+    # Hand over to the target as python itself would have run it. For
+    # a module target, alter_sys replaces sys.argv[0] with the
+    # module's own file, matching python -m; for a script, its
+    # directory joins the front of sys.path, matching python script.py.
+
+    if invocation.module is not None:
+        sys.argv[:] = [invocation.module, *invocation.arguments]
+        runpy.run_module(invocation.module, run_name="__main__", alter_sys=True)
+    else:
+        script = invocation.script
+        assert script is not None
+
+        sys.argv[:] = [script, *invocation.arguments]
+        sys.path.insert(0, os.path.dirname(os.path.abspath(script)))
+        runpy.run_path(script, run_name="__main__")
+
+
+if __name__ == "__main__":
+    main()

{wrapture-1.0.0.dev2 → wrapture-1.0.0.dev3}/src/wrapture/attributes.py

@@ -22,22 +22,29 @@ from __future__ import annotations
 
 import inspect
 import sys
+import time
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
 import wrapt
 from wrapt import MISSING, BaseObjectProxy, apply_patch
 
-from .capture import REFERENCE, _capture_value, _level_of
+from .capture import _capture_value, _level_of
 from .events import Event, EventKind
 from .exceptions import NotImplementedYetError
+from .sinks import (
+    _active_sinks,
+    _in_recorder,
+    _notify_error,
+    _notify_exit,
+    _record_event,
+    _required_policy,
+)
 from .stacks import _capture as _capture_stack
 from .timeline import (
     _capture_result,
-    _in_recorder,
     _pop,
     _push,
-    _tape,
     _timelines_active,
 )
 
@@ -121,20 +128,43 @@ def _record(
     on the in-progress stack so anything it triggers nests under it.
     """
 
-    tape = _tape.get()
-    if tape is None or _in_recorder.get():
-        if tape is None and not _in_recorder.get() and _timelines_active():
+    # 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()
+
+    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()
 
+    # The per-access predicate, mapped onto call shape the same way
+    # behaviour stages are: a set passes the written value as the one
+    # positional argument, a get or delete passes empty args.
+
+    if binding._when is not None:
+        call_args = (value,) if value is not MISSING else ()
+
+        guard = _in_recorder.set(True)
+        try:
+            wanted = binding._when(instance, call_args, {})
+        finally:
+            _in_recorder.reset(guard)
+
+        if not wanted:
+            binding._filtered_calls += 1
+            return operate()
+
     # 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.
 
     policy = binding._capture_args
     if policy is None:
-        policy = getattr(tape, "capture_args", REFERENCE)
+        policy = _required_policy(active, "capture_args")
 
     guard = _in_recorder.set(True)
     try:
@@ -163,28 +193,42 @@ def _record(
             if previous is not MISSING:
                 event.previous = _capture_value(policy, attribute, previous)
 
-        tape.record(event)
     finally:
         _in_recorder.reset(guard)
 
+    # Position before delivery: pushed first, so sinks hearing
+    # on_enter see the event's final depth and parent link. Timing
+    # starts after the bookkeeping, so its overhead is not charged to
+    # the observed operation.
+
     token = _push(event)
+    _record_event(event, active)
+
+    started = time.perf_counter()
+    event.started = started
+
     try:
         outcome = operate()
     except BaseException as exc:
+        event.duration = time.perf_counter() - started
         event.exception = exc
+        _notify_error(event, active)
         raise
     finally:
         _pop(token)
 
+    event.duration = time.perf_counter() - started
+
     # The value a read produced is its outcome, so it captures on the
     # result axis, exactly as a call's return value does.
 
     if kind == "get":
         result_policy = binding._capture_result
         if result_policy is None:
-            result_policy = getattr(tape, "capture_result", REFERENCE)
+            result_policy = _required_policy(active, "capture_result")
         _capture_result(event, outcome, result_policy)
 
+    _notify_exit(event, active)
     return outcome