wrapture-instrumentation 1.0.0.dev1__py3-none-any.whl

wrapture_instrumentation/__init__.py

@@ -0,0 +1,26 @@
+"""
+Instrumentation for common Python packages, applied through wrapture.
+
+Each target package has its own subpackage here, named for its
+category and the target (framework_flask, external_requests), holding
+one wrapture.Instrumentation subclass registered in the
+wrapture.instrumentation entry point group under the bare target name.
+This module carries only the version: importing it loads no
+instrumentation and no target.
+"""
+
+
+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__)

wrapture_instrumentation/framework_flask/__init__.py

@@ -0,0 +1,36 @@
+"""Instrumentation for Flask: request and view tracing for every
+application the process creates.
+
+This module imports only wrapture. Everything that touches Flask lives
+in the sibling hooks module, which itself imports only wrapture at top
+level, so loading this class when a config loads never imports Flask
+ahead of the hook meant to fire on its import.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import wrapture
+
+from . import hooks
+
+
+class FlaskInstrumentation(wrapture.Instrumentation):
+    """Request and view tracing for Flask applications."""
+
+    # The description defaults to the distribution's summary, which
+    # describes the whole collection; each class in a multi-target
+    # package says what it alone does.
+
+    description = "Request and view tracing for Flask applications."
+
+    target = "flask"
+    supports = ">=3.0,<4"
+    removable = True
+
+    @wrapture.instrumentation_hook("flask.app")
+    def flask_app(self, name: str, module: Any) -> None:
+        """Patch the Flask class's choke points once flask.app exists."""
+
+        hooks.instrument(module, self)

wrapture_instrumentation/framework_flask/hooks.py

@@ -0,0 +1,115 @@
+"""The Flask patches, at Flask's own choke points.
+
+Three bindings, all created with when=False so they are behaviour-only:
+the plumbing is not the trace, so they act without ever recording
+their own calls.
+
+- Flask.__init__ installs the recording WSGI middleware on each new
+  instance's wsgi_app attribute, the documented place Flask middleware
+  goes, so every request records as one "request" event however the
+  instance was made: module level, an application factory, several
+  applications in one process.
+- Flask.add_url_rule substitutes wrapture.observed(view_func) as
+  routes register, so every view handler records as a "call" event
+  beneath its request, wherever the view came from: module functions,
+  closures, blueprints from other modules, MethodView classes (which
+  register a generated view function). Flask captures view functions
+  into its dispatch table the moment a route registers, before any
+  observation could exist, which is why registration itself is the
+  point to intercept. observed() is idempotent, so a view registered
+  twice is not wrapped twice.
+- Flask.handle_exception is the one place a view's exception can be
+  seen after Flask catches it: wsgi_app catches around the dispatch
+  and hands the exception here, which returns the 500 response, so
+  the request itself completes normally. The binding notes the
+  exception against the enclosing request event with note_exception(),
+  so the request shows the failure beside its status.
+
+The three are applied as one group whose remove() is registered as a
+cleanup callback with on_cleanup(), which is what lets remove(), and
+with it AppliedConfig.revert() and the instrumentation() context
+manager, take the whole thing down again.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import wrapture
+
+
+def wrap_app(
+    wrapped: Any, instance: Any, args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> Any:
+    """Run Flask.__init__, then install the recording middleware on the
+    new instance's wsgi_app."""
+
+    outcome = wrapped(*args, **kwargs)
+
+    # Label with the app's own import name, so requests read as
+    # "myapp.wsgi_app" and two apps in one process stay distinct.
+
+    instance.wsgi_app = wrapture.WSGIMiddleware(
+        instance.wsgi_app, label=f"{instance.name}.wsgi_app"
+    )
+
+    return outcome
+
+
+def wrap_view(
+    args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> tuple[tuple[Any, ...], dict[str, Any]]:
+    """Substitute an observed view function into an add_url_rule call.
+
+    The signature is add_url_rule(rule, endpoint=None, view_func=None,
+    ...), so the view is either the view_func keyword or the third
+    positional argument; a registration without a view (an endpoint
+    name alone) passes through untouched.
+    """
+
+    if kwargs.get("view_func") is not None:
+        kwargs = dict(kwargs, view_func=wrapture.observed(kwargs["view_func"]))
+    elif len(args) >= 3 and args[2] is not None:
+        args = (*args[:2], wrapture.observed(args[2]), *args[3:])
+
+    return args, kwargs
+
+
+def note_failure(
+    wrapped: Any, instance: Any, args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> Any:
+    """Note the exception handle_exception received against the
+    enclosing request event, then let the handler run."""
+
+    # The exception is the handler's one positional argument. Aim the
+    # note at the request the middleware recorded, not at this call,
+    # which is not recorded anyway; outside a request (a handler
+    # invoked with nothing recording) this is a no-op.
+
+    exception = args[0] if args else kwargs.get("e")
+    if exception is not None:
+        wrapture.note_exception(exception, event=wrapture.current_event(kind="request"))
+
+    return wrapped(*args, **kwargs)
+
+
+def instrument(module: Any, instrumentation: wrapture.Instrumentation) -> None:
+    """Bind the three choke points on the Flask class found in the
+    flask.app module, apply them as one group, and register the
+    group's removal as the instrumentation's cleanup."""
+
+    constructor = wrapture.binding(module.Flask, "__init__", when=False)
+    constructor.on_call.decorates(wrap_app)
+
+    registrar = wrapture.binding(module.Flask, "add_url_rule", when=False)
+    registrar.on_call.transforms_args(wrap_view)
+
+    handler = wrapture.binding(module.Flask, "handle_exception", when=False)
+    handler.on_call.decorates(note_failure)
+
+    group = wrapture.bindings(
+        constructor=constructor, registrar=registrar, handler=handler
+    )
+    group.apply()
+
+    instrumentation.on_cleanup(group.remove)

wrapture_instrumentation-1.0.0.dev1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+wrapture_instrumentation/__init__.py,sha256=nwGba4lOYVvBYcR7FYxR5cqYiVUmCGW2_ao66slVMYg,783
+wrapture_instrumentation/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wrapture_instrumentation/framework_flask/__init__.py,sha256=DtfT6EALymqOhKboyn5XToJQKch_C781kMSDz0IbZqs,1108
+wrapture_instrumentation/framework_flask/hooks.py,sha256=EtS_Rw_IIiQp_sHICupAC08NgGTqzEo0k8uZn7Sa2pw,4534
+wrapture_instrumentation-1.0.0.dev1.dist-info/licenses/LICENSE,sha256=RPMyRnXwgrw9co5o6wY9G3DKlb-oBZ44tpiRnuYeec8,1299
+wrapture_instrumentation-1.0.0.dev1.dist-info/METADATA,sha256=xqT_KxyHckRsVLxPS2SRaoozBoPCnXVMunRV1L3L5ns,5353
+wrapture_instrumentation-1.0.0.dev1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+wrapture_instrumentation-1.0.0.dev1.dist-info/entry_points.txt,sha256=UZXOmg--ham7LOqtX-KHrGPo2TZxz7ttUI6UTbcFCMo,97
+wrapture_instrumentation-1.0.0.dev1.dist-info/top_level.txt,sha256=IIkfVp5ZVFBXZhNnU-lt7OnulEuRBy6EGW9Ci2q3B-o,25
+wrapture_instrumentation-1.0.0.dev1.dist-info/RECORD,,

wrapture_instrumentation-1.0.0.dev1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wrapture_instrumentation-1.0.0.dev1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[wrapture.instrumentation]
+flask = wrapture_instrumentation.framework_flask:FlaskInstrumentation

wrapture_instrumentation-1.0.0.dev1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+wrapture_instrumentation