wrapture 1.0.0.dev1__tar.gz → 1.0.0.dev3__tar.gz

{wrapture-1.0.0.dev1/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.dev1
-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,9 +44,24 @@ 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.
+> **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
+
+wrapture is on [PyPI](https://pypi.org/project/wrapture/):
+
+```console
+$ pip install wrapture
+```
+
+or with uv:
+
+```console
+$ uv add wrapture
+```
 
 ## Documentation
 
@@ -83,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,
@@ -104,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
 
@@ -127,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
@@ -138,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
@@ -152,4 +165,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.dev3}/README.md

@@ -13,9 +13,24 @@ 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.
+> **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
+
+wrapture is on [PyPI](https://pypi.org/project/wrapture/):
+
+```console
+$ pip install wrapture
+```
+
+or with uv:
+
+```console
+$ uv add wrapture
+```
 
 ## Documentation
 
@@ -52,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,
@@ -73,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
 
@@ -96,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
@@ -107,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
@@ -121,4 +134,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.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.dev1 → 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,9 +17,11 @@ def _format_version(parts: tuple[str, ...]) -> str:
     )
 
 
-__version_info__ = ("1", "0", "0", "dev1")
+__version_info__ = ("1", "0", "0", "dev3")
 __version__ = _format_version(__version_info__)
 
+from wrapt import MISSING
+
 from .behaviours import (
     CallBehaviour,
     DeleteBehaviour,
@@ -31,15 +33,19 @@ from .bindings import (
     BindingGroup,
     binding,
     bindings,
+    discover,
 )
 from .capture import (
-    NONE,
-    REFERENCE,
-    SNAPSHOT,
-    SUMMARY,
-    TYPES,
     redact,
 )
+from .config import (
+    AppliedConfig,
+    Config,
+    ObserveEntry,
+    SetupEntry,
+    find_config,
+    load_config,
+)
 from .eventlogs import (
     EventLog,
 )
@@ -48,25 +54,52 @@ 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 (
-    AbandonBehaviour,
-    ErrorBehaviour,
-    FinishBehaviour,
-    ItemBehaviour,
+    IteratorAbandonBehaviour,
+    IteratorErrorBehaviour,
+    IteratorFinishBehaviour,
+    IteratorItemBehaviour,
     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,
-    caller,
-    full,
+    clear_stacks,
     stack_frames,
 )
 from .timeline import (
@@ -74,46 +107,76 @@ from .timeline import (
     Timeline,
     annotate,
     current_event,
+    propagate,
     timeline,
 )
+from .wsgi import (
+    WSGIMiddleware,
+)
 
 __all__ = [
-    "NONE",
-    "REFERENCE",
-    "SNAPSHOT",
-    "SUMMARY",
-    "TYPES",
-    "AbandonBehaviour",
+    "MISSING",
+    "Aggregate",
     "AlreadyAppliedError",
+    "AppliedConfig",
     "Binding",
     "BindingGroup",
     "CallBehaviour",
+    "Config",
+    "ConfigError",
+    "ConfigWarning",
+    "Counter",
     "DeferredTargetError",
     "DeleteBehaviour",
-    "ErrorBehaviour",
+    "Depth",
     "Event",
     "EventLog",
     "ExpectationNotMetError",
-    "FinishBehaviour",
+    "Fanout",
+    "Filter",
     "GetBehaviour",
-    "ItemBehaviour",
+    "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",
-    "caller",
+    "canonical",
+    "chrome_trace",
+    "clear_stacks",
     "current_event",
-    "full",
+    "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()