wrapture-instrumentation 1.0.0.dev1__tar.gz

wrapture_instrumentation-1.0.0.dev1/CHANGES.md

@@ -0,0 +1,14 @@
+# Changes
+
+## Version 1.0.0
+
+In development.
+
+- Project skeleton: the `wrapture_instrumentation` package with its
+  version, the test-side WSGI driver, and the package-level tests
+  that keep every registered instrumentation import-light.
+
+- Flask (`flask`, Flask 3.x): every application's `wsgi_app` wrapped in
+  the recording WSGI middleware at construction, every view function
+  observed as it registers, and the exception `Flask.handle_exception`
+  receives noted against the request event. No settings yet.

wrapture_instrumentation-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_instrumentation-1.0.0.dev1/MANIFEST.in

@@ -0,0 +1,7 @@
+# setuptools includes test_*.py files by default but not the helpers
+# they import (conftest.py, wsgi.py, the package __init__.py), so the
+# tests directory is taken whole, with the repository's other notes.
+graft tests
+graft demo
+include CHANGES.md TESTING.md
+global-exclude __pycache__ *.py[cod]

wrapture_instrumentation-1.0.0.dev1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: wrapture-instrumentation
+Version: 1.0.0.dev1
+Summary: Instrumentation for common Python packages, applied through wrapture.
+Author-email: Graham Dumpleton <Graham.Dumpleton@gmail.com>
+License-Expression: BSD-2-Clause
+Project-URL: Homepage, https://github.com/GrahamDumpleton/wrapture-instrumentation
+Project-URL: Documentation, https://wrapture.readthedocs.io
+Project-URL: Bug Tracker, https://github.com/GrahamDumpleton/wrapture-instrumentation/issues/
+Keywords: wrapture,instrumentation,monkey patching,tracing
+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: wrapture>=1.0.0a4
+Dynamic: license-file
+
+# wrapture-instrumentation
+
+Instrumentation for common Python packages, applied through
+[wrapture](https://github.com/GrahamDumpleton/wrapture).
+
+wrapture attaches bindings to arbitrary Python call sites without
+modifying the code being observed, and its config layer can switch on
+packaged instrumentation for a third-party package by name. This
+project is the collection of that packaged instrumentation: one
+`wrapture.Instrumentation` class per target package (Flask first,
+more to follow), each registered under the bare target name, so that
+tracing a framework is one config entry and no code.
+
+> **Status: pre-alpha.** The package is being built target by target
+> against wrapture's alpha series; nothing is published to PyPI yet.
+> Flask is the first target and covers its basics; see the table below.
+
+## Installation
+
+```console
+$ pip install wrapture-instrumentation
+```
+
+Installing it brings wrapture and nothing else. No target package is
+a dependency: the instrumentation for a package you do not have is
+inert, and wrapture checks the installed version of each target
+against the range the instrumentation supports at apply time.
+
+## Using it
+
+An `[[instrument]]` entry in `wrapture.toml` names a target:
+
+```toml
+[[instrument]]
+name = "flask"
+
+[[sink]]
+type = "printer"
+```
+
+and the runner applies it before the application starts, so the
+patches are in place before the framework is imported:
+
+```console
+$ python -m wrapture -m myapp
+```
+
+The same config works through
+[autowrapt](https://github.com/GrahamDumpleton/autowrapt) injection
+(`AUTOWRAPT_BOOTSTRAP=wrapture python myapp.py`) and, in a test,
+through `wrapture.instrumentation("flask")` scoping the
+instrumentation to a block. The
+[ad-hoc tracing guide](https://wrapture.readthedocs.io/en/latest/ad-hoc-tracing.html)
+covers the config file itself.
+
+To see what is installed, what each instrumentation supports in the
+current environment, and what settings it takes:
+
+```console
+$ python -m wrapture.tools instrumentation --verbose
+```
+
+and to generate the `[[instrument]]` entries to paste into a config,
+every one disabled and every setting commented out at its default:
+
+```console
+$ python -m wrapture.tools instrumentation --toml
+```
+
+## Provided instrumentation
+
+| Target | Supported versions | Records | Settings |
+| ------ | ------------------ | ------- | -------- |
+| `flask` | Flask 3.x | Every request as one tree (the recording WSGI middleware installed on each application at construction), every view function beneath its request (observed as routes register, blueprints and `MethodView`s included), and the exception Flask catches on its way to a 500 noted on the request. | none yet |
+
+The entry point name is the config's `name`; the table says what each
+instrumentation does in the current cut. Settings, further choke
+points and wider version ranges are being added target by target.
+
+## Adding a target
+
+Each target lives in its own subpackage under
+`src/wrapture_instrumentation/`, named `<category>_<target>`:
+`framework_flask`, `external_requests`, `database_sqlite3`. The
+category says what kind of thing the target is and, with it, which
+part of wrapture the instrumentation mostly uses:
+
+- `framework_`: web frameworks, and their extensions as compound
+  names (`framework_flask_restful`).
+- `external_`: outbound HTTP and RPC clients and service SDKs.
+- `database_`: DB-API drivers and SQL toolkits.
+- `datastore_`: other stores and caches.
+- `task_`: task queues. `messaging_`: brokers and their clients.
+- `server_`: WSGI and ASGI servers. `template_`: template engines.
+
+A new category is added when a target fits none of these. The
+directory name is internal; the entry point name, and so the name a
+config uses, is always the bare target.
+
+The subpackage's `__init__.py` holds one `wrapture.Instrumentation`
+subclass and imports only wrapture; everything that touches the
+target lives in `hooks.py`, reached by an import inside `apply()`.
+The class is registered in `pyproject.toml` under
+`[project.entry-points."wrapture.instrumentation"]`, and gets its own
+test suite under `tests/<category>_<target>/`. The
+[instrumentation packages](https://wrapture.readthedocs.io/en/latest/instrumentation-packages.html)
+page of the wrapture documentation is the full contract; TESTING.md
+here covers the tests.
+
+## License
+
+BSD-2-Clause, as wrapture.

wrapture_instrumentation-1.0.0.dev1/README.md

@@ -0,0 +1,112 @@
+# wrapture-instrumentation
+
+Instrumentation for common Python packages, applied through
+[wrapture](https://github.com/GrahamDumpleton/wrapture).
+
+wrapture attaches bindings to arbitrary Python call sites without
+modifying the code being observed, and its config layer can switch on
+packaged instrumentation for a third-party package by name. This
+project is the collection of that packaged instrumentation: one
+`wrapture.Instrumentation` class per target package (Flask first,
+more to follow), each registered under the bare target name, so that
+tracing a framework is one config entry and no code.
+
+> **Status: pre-alpha.** The package is being built target by target
+> against wrapture's alpha series; nothing is published to PyPI yet.
+> Flask is the first target and covers its basics; see the table below.
+
+## Installation
+
+```console
+$ pip install wrapture-instrumentation
+```
+
+Installing it brings wrapture and nothing else. No target package is
+a dependency: the instrumentation for a package you do not have is
+inert, and wrapture checks the installed version of each target
+against the range the instrumentation supports at apply time.
+
+## Using it
+
+An `[[instrument]]` entry in `wrapture.toml` names a target:
+
+```toml
+[[instrument]]
+name = "flask"
+
+[[sink]]
+type = "printer"
+```
+
+and the runner applies it before the application starts, so the
+patches are in place before the framework is imported:
+
+```console
+$ python -m wrapture -m myapp
+```
+
+The same config works through
+[autowrapt](https://github.com/GrahamDumpleton/autowrapt) injection
+(`AUTOWRAPT_BOOTSTRAP=wrapture python myapp.py`) and, in a test,
+through `wrapture.instrumentation("flask")` scoping the
+instrumentation to a block. The
+[ad-hoc tracing guide](https://wrapture.readthedocs.io/en/latest/ad-hoc-tracing.html)
+covers the config file itself.
+
+To see what is installed, what each instrumentation supports in the
+current environment, and what settings it takes:
+
+```console
+$ python -m wrapture.tools instrumentation --verbose
+```
+
+and to generate the `[[instrument]]` entries to paste into a config,
+every one disabled and every setting commented out at its default:
+
+```console
+$ python -m wrapture.tools instrumentation --toml
+```
+
+## Provided instrumentation
+
+| Target | Supported versions | Records | Settings |
+| ------ | ------------------ | ------- | -------- |
+| `flask` | Flask 3.x | Every request as one tree (the recording WSGI middleware installed on each application at construction), every view function beneath its request (observed as routes register, blueprints and `MethodView`s included), and the exception Flask catches on its way to a 500 noted on the request. | none yet |
+
+The entry point name is the config's `name`; the table says what each
+instrumentation does in the current cut. Settings, further choke
+points and wider version ranges are being added target by target.
+
+## Adding a target
+
+Each target lives in its own subpackage under
+`src/wrapture_instrumentation/`, named `<category>_<target>`:
+`framework_flask`, `external_requests`, `database_sqlite3`. The
+category says what kind of thing the target is and, with it, which
+part of wrapture the instrumentation mostly uses:
+
+- `framework_`: web frameworks, and their extensions as compound
+  names (`framework_flask_restful`).
+- `external_`: outbound HTTP and RPC clients and service SDKs.
+- `database_`: DB-API drivers and SQL toolkits.
+- `datastore_`: other stores and caches.
+- `task_`: task queues. `messaging_`: brokers and their clients.
+- `server_`: WSGI and ASGI servers. `template_`: template engines.
+
+A new category is added when a target fits none of these. The
+directory name is internal; the entry point name, and so the name a
+config uses, is always the bare target.
+
+The subpackage's `__init__.py` holds one `wrapture.Instrumentation`
+subclass and imports only wrapture; everything that touches the
+target lives in `hooks.py`, reached by an import inside `apply()`.
+The class is registered in `pyproject.toml` under
+`[project.entry-points."wrapture.instrumentation"]`, and gets its own
+test suite under `tests/<category>_<target>/`. The
+[instrumentation packages](https://wrapture.readthedocs.io/en/latest/instrumentation-packages.html)
+page of the wrapture documentation is the full contract; TESTING.md
+here covers the tests.
+
+## License
+
+BSD-2-Clause, as wrapture.

wrapture_instrumentation-1.0.0.dev1/TESTING.md

@@ -0,0 +1,183 @@
+# Testing
+
+## Where the tests are
+
+Tests live in the [tests/](tests/) directory at the top of the
+repository, separate from the package code in
+src/wrapture_instrumentation/. Test files are named `test_*.py` and
+are discovered by pytest, which is configured via the
+`[tool.pytest.ini_options]` section of [pyproject.toml](pyproject.toml).
+
+The directory has two levels:
+
+- Package-level tests directly under tests/: the version, the rule
+  that importing the package or loading any registered class never
+  imports a target, the listing tool reporting every entry cleanly,
+  and the test-side WSGI driver's own tests.
+- One subdirectory per target, `tests/<category>_<target>/`
+  (`tests/framework_flask/`), holding that instrumentation's suite:
+  settings validation, applying and removing the class directly, the
+  whole path through `wrapture.instrumentation()` with a timeline
+  recording what the bindings observe, resolving the entry point by
+  name, and a check that the installed target satisfies the class's
+  `supports` range.
+
+Shared helpers live in [tests/conftest.py](tests/conftest.py) and
+[tests/wsgi.py](tests/wsgi.py).
+
+## The WSGI driver
+
+WSGI applications are driven in process by `tests/wsgi.py`, which
+plays the server's side of PEP 3333 exactly: it builds a complete
+environ, supplies a `start_response` that honours the `exc_info`
+re-invocation rule and returns a working `write` callable, iterates
+the application's result, and always calls its `close()`, including
+when iteration raises or is abandoned. It is used instead of a
+framework's test client because a request event's closing line is
+tied to the moment the response iterable is consumed and closed, and
+the driver makes that moment explicit: `request(app, "GET", "/path")`
+reads and closes for the common case, and `consume=False` hands back
+the response with its body unconsumed so a test can check the
+request is still open, then `read()` and `close()` it. The same
+driver serves every WSGI target.
+
+## Running the tests
+
+All tooling in this project goes through [uv](https://docs.astral.sh/uv/),
+which manages the project environment and installs the package, its
+development dependencies (including pytest) and the target packages
+the tests need.
+
+The simplest way to run the test suite is via the Justfile target:
+
+```console
+just test
+```
+
+Extra arguments are passed through to pytest, for example:
+
+```console
+just test -v
+just test tests/test_wsgi.py
+just test -k version
+```
+
+One target's suite alone:
+
+```console
+just test-target framework_flask
+```
+
+Equivalently, run pytest directly with uv:
+
+```console
+uv run pytest
+```
+
+## Watching what the tests record
+
+The suites assert on tapes rather than printing anything, but the
+recorded events can be watched live for visual verification. Setting
+WRAPTURE_PRINTER in the environment installs a process-wide
+wrapture.Printer sink for the session, streaming one line to stderr
+as each operation begins and a closing line with its outcome and
+timing; pytest captures stderr, so add -s to see it:
+
+```console
+WRAPTURE_PRINTER=1 just test tests/framework_flask -s
+```
+
+The sink is consulted alongside the tests' own scoped tapes, so the
+stream shows exactly what each tape hears without disturbing any
+assertion.
+
+For a purpose-built run rather than the tests' traffic, each target
+also has a demo module under demo/ that applies its instrumentation,
+drives the test application through the WSGI driver, and prints both
+the live stream and the reconstructed tree with timings:
+
+```console
+just demo-flask
+```
+
+With --otel the same events also export as OpenTelemetry spans over
+OTLP (to http://localhost:4318, or wherever
+OTEL_EXPORTER_OTLP_ENDPOINT points), for verifying the spans in a
+local backend such as Jaeger; the Justfile target overlays the
+wrapture[otel] dependencies for the run:
+
+```console
+just demo-flask --otel
+```
+
+## Testing across Python versions
+
+The project supports multiple Python versions, including the free
+threaded builds of 3.13, 3.14 and 3.15. The supported list is defined
+at the top of the [Justfile](Justfile). The default version used by
+plain `just test` is pinned in [.python-version](.python-version).
+
+Run the test suite on every supported version:
+
+```console
+just test-all
+```
+
+Run the test suite on one nominated version:
+
+```console
+just test-python 3.12
+just test-python 3.14t
+```
+
+Extra arguments are passed through to pytest for these targets too.
+uv downloads any Python version it does not already have, and each
+version gets its own environment (.venv-VERSION) so the default .venv
+is left untouched.
+
+## Testing across target versions
+
+The `test` dependency group installs each target at whatever version
+the lock resolves. An instrumentation's `supports` range is kept
+honest by running its suite against other versions of the target,
+overlaid on the project environment for that run. Each target has a
+recipe for it in the Justfile (`just test-flask 3.0.3`) and a list of
+versions that `just test-flask-all` loops over; the CI workflow runs
+the same matrix. A test in each target's suite asserts the installed
+target satisfies `supports`, so a matrix entry outside the range
+fails loudly rather than passing vacuously.
+
+## Testing against unreleased wrapture
+
+The package depends on a released wrapture. To run the tests against
+a checkout of wrapture in the sibling directory ../wrapture, without
+editing pyproject.toml:
+
+```console
+just test-dev
+```
+
+which overlays that checkout as an editable install for the run.
+
+## Writing tests
+
+- Put new test files in tests/ (package level) or
+  tests/<category>_<target>/ (for one instrumentation) and name them
+  `test_*.py`.
+- Import the package under test as `wrapture_instrumentation`, and
+  the instrumentation classes from their subpackages. The project is
+  installed into the uv-managed environment, so no path manipulation
+  is needed.
+- Validate behaviour with wrapture's own unit testing layer:
+  `wrapture.timeline()` to record what the instrumentation's bindings
+  observe and the tape's tree and queries to assert on it, bindings
+  with `when=` and behaviours where a test needs to see a target
+  internal being called or control what it does, and
+  `wrapture.instrumentation()` to scope an application of a class to
+  a block. Do not use `unittest.mock`. If something cannot be
+  expressed that way, write it plainly with a comment naming the gap,
+  and say so when summarising the work.
+- Drive WSGI applications through `tests/wsgi.py`, not a framework's
+  test client.
+- Tests should not depend on anything in the scratch/ directory,
+  which is not part of the repository.

wrapture_instrumentation-1.0.0.dev1/demo/__init__.py

@@ -0,0 +1,17 @@
+"""Demonstration scripts, one per instrumented target.
+
+Each module drives a small application with its target's
+instrumentation applied, streaming every recorded event live and
+printing the reconstructed tree at the end, so the instrumentation
+can be verified by eye rather than by assertion. Run from the
+repository root as a module, so the tests package (whose application
+and WSGI driver the demos reuse) imports cleanly:
+
+    uv run python -m demo.framework_flask
+
+or through the Justfile target, which also carries the OpenTelemetry
+dependencies for the --otel flag:
+
+    just demo-flask
+    just demo-flask --otel
+"""

wrapture_instrumentation-1.0.0.dev1/demo/framework_flask.py

@@ -0,0 +1,117 @@
+"""Drive the shop application with the Flask instrumentation applied.
+
+The instrumentation is resolved by its entry point name, the way a
+config file finds it, and the application is the tests' own shop,
+built only after the instrumentation applies, the order the runner
+guarantees in real use. A handful of requests then cover every shape
+the instrumentation handles: plain views, a streaming response, a
+class-based view, a blueprint, and a view that raises (Flask answers
+500 and the exception is noted against the request event).
+
+Two views of the run always print: the live stream, one line as each
+operation begins and a closing line with its outcome, and the tidy
+tree reconstructed afterwards with timings. With --otel the same
+events also export as OpenTelemetry spans to a local OTLP endpoint
+(http://localhost:4318 unless OTEL_EXPORTER_OTLP_ENDPOINT says
+otherwise), for verifying the spans in a backend such as Jaeger:
+
+    docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+import wrapture
+
+# Every route the shop registers, the failing request last so the
+# stream ends on the interesting case.
+
+REQUESTS: tuple[tuple[str, str], ...] = (
+    ("GET", "/"),
+    ("GET", "/quote/widget"),
+    ("GET", "/export"),
+    ("GET", "/catalog"),
+    ("GET", "/reports/summary"),
+    ("GET", "/quote/missing"),
+)
+
+
+def add_otel_sink() -> None:
+    """Register the OpenTelemetry sink, exporting the run's events as
+    spans; exits with guidance when the optional dependencies are
+    missing."""
+
+    try:
+        import wrapture.otel
+    except ImportError as error:
+        raise SystemExit(
+            "the OpenTelemetry dependencies are not installed; run the"
+            " demo through `just demo-flask --otel`, which overlays"
+            " wrapture[otel] for the run"
+        ) from error
+
+    wrapture.add_sink(wrapture.otel.sink(service_name="wrapture-flask-demo"))
+
+
+def main(arguments: list[str] | None = None) -> None:
+    """Run the demo: apply the instrumentation, drive the requests,
+    print the live stream and the tree, and flush any exporters."""
+
+    parser = argparse.ArgumentParser(
+        prog="demo.framework_flask",
+        description="Drive the shop application with the Flask"
+        " instrumentation applied, printing the live stream and the"
+        " tree.",
+    )
+    parser.add_argument(
+        "--otel",
+        action="store_true",
+        help="also export the events as OpenTelemetry spans over OTLP",
+    )
+    options = parser.parse_args(arguments)
+
+    # The exporting sink registers first, mirroring the config loader,
+    # which always puts the [otel] table's sink ahead of the [[sink]]
+    # list; the printer writes to stdout so the stream and the demo's
+    # own headings interleave in order.
+
+    if options.otel:
+        add_otel_sink()
+
+    wrapture.add_sink(wrapture.Printer(stream=sys.stdout))
+
+    print("== live stream ==")
+
+    with wrapture.instrumentation("flask"), wrapture.timeline() as tape:
+        from tests.framework_flask.shop import make_app
+        from tests.wsgi import request
+
+        app = make_app()
+
+        for method, path in REQUESTS:
+            request(app, method, path)
+
+    print()
+    print("== tree ==")
+    print(tape.tree(times=True))
+
+    # Deliver everything owed: batched spans push to the exporter here
+    # rather than at interpreter exit, so the closing hint below is
+    # true by the time it prints.
+
+    wrapture.shutdown()
+
+    if options.otel:
+        endpoint = os.environ.get(
+            "OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318"
+        )
+        print()
+        print("== otel ==")
+        print(f"spans flushed to {endpoint} as service wrapture-flask-demo")
+
+
+if __name__ == "__main__":
+    main()