wrapture

Trace assertions without instrumenting your code.

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 and autowrapt, building on the safe monkey-patching machinery wrapt provides.

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:

$ pip install wrapture

or with uv:

$ uv add wrapture

Documentation

Full documentation is at wrapture.readthedocs.io. Start with the getting started page: everything on it can be pasted into a Python interpreter. Coming from unittest.mock? There is a comparison page mapping each mock idiom to its wrapture counterpart.

Thirty seconds of it

None of the classes below import wrapture or know they are observed:

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 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: with a wrapture.toml naming the methods and a sink, python -m wrapture manage.py runserver traces the application untouched. With 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 replacement for unittest.mock. It complements mocking where code has seams; it exists for the code that doesn't.
• 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 2.4.0+

License

BSD 2-Clause. See LICENSE.