wrapture 1.0.0a1__tar.gz

wrapture-1.0.0a1/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.0a1/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: wrapture
+Version: 1.0.0a1
+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
+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.0rc5
+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
+
+**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)
+
+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: stabilising ahead of 1.0.0.** The feature set is complete for
+> a first release and pre-releases are published to PyPI. Until 1.0.0 is
+> final, a plain `pip install wrapture` picks up the latest pre-release
+> automatically, so there is no need to pin a specific version. The API
+> is being exercised and tidied rather than extended, so small changes are
+> still possible 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
+
+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. 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.
+
+## At a glance
+
+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, 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,
+   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
+   `unittest.mock` `Mock`, which fabricates values and cannot see calls an object makes to itself,
+   wrapture watches the real code run, and when a test must supply a
+   stand-in it provides strict, recorded ones: `stub()` for a callable,
+   spec-required `mock()` for a collaborator. 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: 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
+
+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.
+- 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 fabrication tool.** There is no spec-less `Mock()` here by
+  design; stand-ins are strict and built from named specs, and
+  `unittest.mock` remains the tool for invented objects.
+- **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.
+
+## How it was built
+
+wrapture's code and documentation were written by an AI assistant under
+the direction of Graham Dumpleton, the author of wrapt, through a long
+process of specification, layered implementation, and validation against
+real-world test suites.
+[How wrapture was built](https://wrapture.readthedocs.io/en/latest/how-wrapture-was-built.html)
+explains the process and the thinking.
+
+## Requirements
+
+- 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
+[LICENSE](https://github.com/GrahamDumpleton/wrapture/blob/develop/LICENSE).

wrapture-1.0.0a1/README.md

@@ -0,0 +1,162 @@
+# wrapture
+
+**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)
+
+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: stabilising ahead of 1.0.0.** The feature set is complete for
+> a first release and pre-releases are published to PyPI. Until 1.0.0 is
+> final, a plain `pip install wrapture` picks up the latest pre-release
+> automatically, so there is no need to pin a specific version. The API
+> is being exercised and tidied rather than extended, so small changes are
+> still possible 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
+
+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. 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.
+
+## At a glance
+
+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, 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,
+   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
+   `unittest.mock` `Mock`, which fabricates values and cannot see calls an object makes to itself,
+   wrapture watches the real code run, and when a test must supply a
+   stand-in it provides strict, recorded ones: `stub()` for a callable,
+   spec-required `mock()` for a collaborator. 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: 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
+
+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.
+- 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 fabrication tool.** There is no spec-less `Mock()` here by
+  design; stand-ins are strict and built from named specs, and
+  `unittest.mock` remains the tool for invented objects.
+- **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.
+
+## How it was built
+
+wrapture's code and documentation were written by an AI assistant under
+the direction of Graham Dumpleton, the author of wrapt, through a long
+process of specification, layered implementation, and validation against
+real-world test suites.
+[How wrapture was built](https://wrapture.readthedocs.io/en/latest/how-wrapture-was-built.html)
+explains the process and the thinking.
+
+## Requirements
+
+- 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
+[LICENSE](https://github.com/GrahamDumpleton/wrapture/blob/develop/LICENSE).

wrapture-1.0.0a1/pyproject.toml

@@ -0,0 +1,111 @@
+[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.0rc5"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wrapture"
+dynamic = ["version"]
+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"]
+authors = [
+    {name = "Graham Dumpleton", email = "Graham.Dumpleton@gmail.com"}
+]
+requires-python = ">=3.12"
+keywords = ["wrapper", "monkey patching", "tracing", "testing"]
+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.0rc5",
+]
+
+[project.urls]
+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",
+    "pytest",
+    "ruff",
+    "setuptools",
+]
+docs = [
+    "myst-parser",
+    "sphinx",
+    "sphinx-rtd-theme",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+zip-safe = false
+packages = ["wrapture", "wrapture.tools"]
+
+[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"
+# ELLIPSIS lets a transcript elide values that vary between runs, such
+# as the elapsed time on a printer's closing line.
+doctest_optionflags = ["ELLIPSIS"]
+
+[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.0a1/setup.cfg

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