wrapture 1.0.0.dev1__tar.gz

wrapture-1.0.0.dev1/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2026, Graham Dumpleton
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

wrapture-1.0.0.dev1/PKG-INFO

@@ -0,0 +1,155 @@
+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.
+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
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: wrapt>=2.4.0rc4
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Dynamic: license-file
+
+# wrapture
+
+**Trace assertions without instrumenting your code.**
+
+[![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)
+
+wrapture (`wrapt` + `capture`) is a Python library for attaching bindings to
+arbitrary call sites, without modifying the code being observed, and doing
+something useful with what flows through them.
+
+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.
+
+## Documentation
+
+Full documentation is at [wrapture.readthedocs.io](https://wrapture.readthedocs.io).
+Start with the [getting started](https://wrapture.readthedocs.io/en/latest/getting-started.html)
+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.
+
+## Thirty seconds of it
+
+None of the classes below import wrapture or know they are observed:
+
+```python
+place = wrapture.binding(OrderService, "place")
+charge = wrapture.binding(Gateway, "charge")
+record = wrapture.binding(Ledger, "record")
+
+with wrapture.timeline(place, charge, record) as tape:
+    OrderService().place(500)
+
+print(tape.tree())
+```
+
+```
+OrderService.place(amount=500)  -> {'id': 'ch_500', 'amount': 500}
+  Gateway.charge(amount=500, currency='USD')  -> {'id': 'ch_500', 'amount': 500}
+  Ledger.record(entry={'id': 'ch_500', 'amount': 500})  -> 'led_ch_500'
+```
+
+The same bindings intervene as well as observe: stub a result, inject a
+failure, or transform one argument while the real code keeps running.
+
+## What it does
+
+One mechanism, four 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,
+   transform its arguments or result, or wrap it with a decorator, then
+   remove it again, with honest reporting if something else displaced the
+   patch in the meantime. Useful entirely on its own, with nothing else
+   switched on.
+
+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,
+   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
+   written, the receipt was not sent, and the compensating refund was issued.
+
+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.
+
+## Why
+
+No single existing tool covers "point at arbitrary methods, get a structured
+nested trace, assert on it or export it, in tests or in production":
+
+- `unittest.mock` records a flat call list, with no nesting and no return
+  values, and a patched call returns a fabricated `MagicMock` rather than
+  running the real code.
+- Span-assertion tools (`logfire.testing`, OpenTelemetry's
+  `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.
+
+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
+testing assertion library, a tracing tool, or both at once.
+
+## What it is not
+
+- **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
+  it.
+
+## Requirements
+
+- Python 3.12+
+- [wrapt](https://github.com/GrahamDumpleton/wrapt) 2.4.0+
+
+## License
+
+BSD 2-Clause. See [LICENSE](LICENSE).

wrapture-1.0.0.dev1/README.md

@@ -0,0 +1,124 @@
+# wrapture
+
+**Trace assertions without instrumenting your code.**
+
+[![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)
+
+wrapture (`wrapt` + `capture`) is a Python library for attaching bindings to
+arbitrary call sites, without modifying the code being observed, and doing
+something useful with what flows through them.
+
+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.
+
+## Documentation
+
+Full documentation is at [wrapture.readthedocs.io](https://wrapture.readthedocs.io).
+Start with the [getting started](https://wrapture.readthedocs.io/en/latest/getting-started.html)
+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.
+
+## Thirty seconds of it
+
+None of the classes below import wrapture or know they are observed:
+
+```python
+place = wrapture.binding(OrderService, "place")
+charge = wrapture.binding(Gateway, "charge")
+record = wrapture.binding(Ledger, "record")
+
+with wrapture.timeline(place, charge, record) as tape:
+    OrderService().place(500)
+
+print(tape.tree())
+```
+
+```
+OrderService.place(amount=500)  -> {'id': 'ch_500', 'amount': 500}
+  Gateway.charge(amount=500, currency='USD')  -> {'id': 'ch_500', 'amount': 500}
+  Ledger.record(entry={'id': 'ch_500', 'amount': 500})  -> 'led_ch_500'
+```
+
+The same bindings intervene as well as observe: stub a result, inject a
+failure, or transform one argument while the real code keeps running.
+
+## What it does
+
+One mechanism, four 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,
+   transform its arguments or result, or wrap it with a decorator, then
+   remove it again, with honest reporting if something else displaced the
+   patch in the meantime. Useful entirely on its own, with nothing else
+   switched on.
+
+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,
+   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
+   written, the receipt was not sent, and the compensating refund was issued.
+
+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.
+
+## Why
+
+No single existing tool covers "point at arbitrary methods, get a structured
+nested trace, assert on it or export it, in tests or in production":
+
+- `unittest.mock` records a flat call list, with no nesting and no return
+  values, and a patched call returns a fabricated `MagicMock` rather than
+  running the real code.
+- Span-assertion tools (`logfire.testing`, OpenTelemetry's
+  `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.
+
+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
+testing assertion library, a tracing tool, or both at once.
+
+## What it is not
+
+- **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
+  it.
+
+## Requirements
+
+- Python 3.12+
+- [wrapt](https://github.com/GrahamDumpleton/wrapt) 2.4.0+
+
+## License
+
+BSD 2-Clause. See [LICENSE](LICENSE).

wrapture-1.0.0.dev1/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+# wrapt is needed at build time because reading the dynamic version imports
+# the package, and the package imports wrapt at the top level.
+requires = ["setuptools>=62.0", "wheel", "wrapt>=2.4.0rc4"]
+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."
+readme = "README.md"
+license = "BSD-2-Clause"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Graham Dumpleton", email = "Graham.Dumpleton@gmail.com"}
+]
+requires-python = ">=3.12"
+keywords = ["wrapper", "monkey patching", "tracing", "testing", "profiling"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+]
+dependencies = [
+    "wrapt>=2.4.0rc4",
+]
+
+[project.urls]
+Homepage = "https://github.com/GrahamDumpleton/wrapture"
+Documentation = "https://wrapture.readthedocs.io"
+"Bug Tracker" = "https://github.com/GrahamDumpleton/wrapture/issues/"
+
+[project.optional-dependencies]
+dev = [
+    "mypy",
+    "pytest",
+    "ruff",
+    "setuptools",
+]
+docs = [
+    "myst-parser",
+    "sphinx",
+    "sphinx-rtd-theme",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+zip-safe = false
+packages = ["wrapture"]
+
+[tool.setuptools.package-data]
+wrapture = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = {attr = "wrapture.__version__"}
+
+[dependency-groups]
+test = [
+    "pytest",
+]
+dev = [
+    {include-group = "test"},
+    "mypy",
+    "ruff",
+    "setuptools",
+]
+
+[tool.pytest.ini_options]
+# The docs are on the test paths so the interpreter transcripts in the
+# getting started page run as doctests and cannot rot.
+testpaths = ["tests", "docs"]
+addopts = "--doctest-glob=*.md"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src/wrapture", "tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+# Version information is defined before the imports in __init__.py.
+per-file-ignores = {"src/wrapture/__init__.py" = ["E402"]}
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "UP",     # pyupgrade
+    "B",      # flake8-bugbear
+]

wrapture-1.0.0.dev1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wrapture-1.0.0.dev1/src/wrapture/__init__.py

@@ -0,0 +1,119 @@
+"""
+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.
+"""
+
+
+def _format_version(parts: tuple[str, ...]) -> str:
+    base = ".".join(parts[:3])
+
+    if len(parts) == 3:
+        return base
+
+    suffix = parts[3]
+    return (
+        f"{base}.{suffix}" if suffix.startswith(("dev", "post")) else f"{base}{suffix}"
+    )
+
+
+__version_info__ = ("1", "0", "0", "dev1")
+__version__ = _format_version(__version_info__)
+
+from .behaviours import (
+    CallBehaviour,
+    DeleteBehaviour,
+    GetBehaviour,
+    SetBehaviour,
+)
+from .bindings import (
+    Binding,
+    BindingGroup,
+    binding,
+    bindings,
+)
+from .capture import (
+    NONE,
+    REFERENCE,
+    SNAPSHOT,
+    SUMMARY,
+    TYPES,
+    redact,
+)
+from .eventlogs import (
+    EventLog,
+)
+from .events import (
+    Event,
+)
+from .exceptions import (
+    AlreadyAppliedError,
+    DeferredTargetError,
+    ExpectationNotMetError,
+    NeverAppliedError,
+    NotImplementedYetError,
+    RecordingGapWarning,
+    WrongModeError,
+)
+from .iterators import (
+    AbandonBehaviour,
+    ErrorBehaviour,
+    FinishBehaviour,
+    ItemBehaviour,
+    IteratorProxy,
+    iterator,
+)
+from .stacks import (
+    StackFrame,
+    caller,
+    full,
+    stack_frames,
+)
+from .timeline import (
+    Tape,
+    Timeline,
+    annotate,
+    current_event,
+    timeline,
+)
+
+__all__ = [
+    "NONE",
+    "REFERENCE",
+    "SNAPSHOT",
+    "SUMMARY",
+    "TYPES",
+    "AbandonBehaviour",
+    "AlreadyAppliedError",
+    "Binding",
+    "BindingGroup",
+    "CallBehaviour",
+    "DeferredTargetError",
+    "DeleteBehaviour",
+    "ErrorBehaviour",
+    "Event",
+    "EventLog",
+    "ExpectationNotMetError",
+    "FinishBehaviour",
+    "GetBehaviour",
+    "ItemBehaviour",
+    "IteratorProxy",
+    "NeverAppliedError",
+    "NotImplementedYetError",
+    "RecordingGapWarning",
+    "SetBehaviour",
+    "StackFrame",
+    "Tape",
+    "Timeline",
+    "WrongModeError",
+    "annotate",
+    "binding",
+    "bindings",
+    "caller",
+    "current_event",
+    "full",
+    "iterator",
+    "redact",
+    "stack_frames",
+    "timeline",
+]