wrapture-instrumentation-postgresql 1.0.0.dev1__tar.gz

wrapture_instrumentation_postgresql-1.0.0.dev1/CHANGES.md

@@ -0,0 +1,9 @@
+# Changes
+
+## Version 1.0.0
+
+Initial release of wrapture-instrumentation-postgresql. Everything is
+new in this version, so rather than listing changes, see the
+[README](README.md) for what the package provides: the table of
+covered targets there links to each target's own notes describing
+what it records and its settings.

wrapture_instrumentation_postgresql-1.0.0.dev1/Dockerfile

@@ -0,0 +1,15 @@
+# The environment the test matrix runs in: Debian with uv, and the
+# one thing psycopg's pure Python implementation needs from the
+# machine, a libpq. Nothing else is baked in: uv fetches whichever
+# interpreter the run asks for and installs the test dependencies into
+# a per-version environment, both on named volumes so they persist
+# across runs (see compose.yml). The repository is bind-mounted at
+# run time, so the image never goes stale as the code changes.
+
+FROM ghcr.io/astral-sh/uv:debian-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libpq5 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /work

wrapture_instrumentation_postgresql-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_postgresql-1.0.0.dev1/MANIFEST.in

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

wrapture_instrumentation_postgresql-1.0.0.dev1/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: wrapture-instrumentation-postgresql
+Version: 1.0.0.dev1
+Summary: Instrumentation for the PostgreSQL client libraries (psycopg, psycopg2, asyncpg), 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-postgresql
+Project-URL: Documentation, https://wrapture.readthedocs.io
+Project-URL: Bug Tracker, https://github.com/GrahamDumpleton/wrapture-instrumentation-postgresql/issues/
+Keywords: wrapture,instrumentation,postgresql,psycopg,psycopg2,asyncpg,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 :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: wrapture>=1.0.0a20
+Dynamic: license-file
+
+# wrapture-instrumentation-postgresql
+
+Instrumentation for the PostgreSQL client libraries, 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 is
+the PostgreSQL package in that collection: one `wrapture.Instrumentation`
+class per client library, so tracing every query, connection and
+transaction your application sends to PostgreSQL is one config entry
+and no code.
+
+> **Status: alpha, ahead of 1.0.0.** Developed against wrapture's
+> alpha series, with pre-releases published to
+> [PyPI](https://pypi.org/project/wrapture-instrumentation-postgresql/),
+> and until 1.0.0 is final a plain `pip install
+> wrapture-instrumentation-postgresql` picks up the latest pre-release
+> automatically, so there is no need to pin a specific version.
+
+## Why a separate package
+
+The core
+[wrapture-instrumentation](https://github.com/GrahamDumpleton/wrapture-instrumentation)
+package deliberately covers only the standard library and third-party
+packages that can be exercised in-process, with no separate backend
+product or service needed to test against. A PostgreSQL driver is
+exactly the kind of target the separate-package rule was drawn for:
+its tests need a real server, so this package's suite runs one in a
+docker container, and it carries the drivers as test dependencies
+(some of them compiled wheels) and its own release cadence, so the
+core package's test matrix stays light. One package covers every
+client library for the one backend: psycopg, psycopg2 and asyncpg.
+
+## Installation
+
+```console
+$ pip install wrapture-instrumentation-postgresql
+```
+
+Installing it brings wrapture and nothing else. No driver is a
+dependency: each instrumentation is inert until its driver is present,
+and wrapture checks the installed version against the range the
+instrumentation supports at apply time.
+
+## Using it
+
+An `[[instrument]]` entry in `wrapture.toml` names the target:
+
+```toml
+[[instrument]]
+name = "psycopg"
+
+[[sink]]
+type = "printer"
+```
+
+and the runner applies it before the application starts, so the patch
+is in place before the driver 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`); through
+[manual setup](https://wrapture.readthedocs.io/en/latest/manual-setup.html),
+a few lines in the application's own startup where wrapping the launch
+from outside is awkward; and, in a test, through
+`wrapture.instrumentation("psycopg")` 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 it supports in the current
+environment, and what settings it takes:
+
+```console
+$ python -m wrapture.tools instrumentation --verbose
+```
+
+## Provided instrumentation
+
+| Target | Supported versions | Records | Settings |
+| ------ | ------------------ | ------- | -------- |
+| [`psycopg`](https://github.com/GrahamDumpleton/wrapture-instrumentation-postgresql/blob/develop/src/wrapture_instrumentation_postgresql/psycopg/README.md) | psycopg 3.1+ (3.x) | Every query as one `database` leaf, however it was issued (a cursor's `execute` or `executemany`, the connection's shortcut, a streamed query, a COPY, a server-side cursor's DECLARE), plus the connection being opened and each transaction boundary (`commit`, `rollback`, the connection's context manager, and a `transaction()` block's begin and end, savepoints included); sync and async classes alike, and connections from a pool. Each event carries the system, the operation, and the database, host and port it reached; a failing statement records the driver's exception. The SQL text is recorded only with the `statement` setting on, bound parameters never. | `statement` |
+| [`psycopg2`](https://github.com/GrahamDumpleton/wrapture-instrumentation-postgresql/blob/develop/src/wrapture_instrumentation_postgresql/psycopg2/README.md) | psycopg2 2.9+ (2.x), psycopg2-binary alike | Every query as one `database` leaf, however it was issued (`execute`, `executemany`, `callproc`, the extras' batch helpers, a named cursor's DECLARE), each COPY (`copy_from`, `copy_to`, `copy_expert`), the connection being opened and each transaction boundary (`commit`, `rollback`, the connection's context manager); through recording subclasses injected by psycopg2's own factory mechanism, so your `cursor_factory` and `connection_factory` classes keep working and are recorded too. Each event carries the system, the operation, and the database, host and port it reached; a failing statement records the driver's exception. The SQL text (the template with its placeholders) is recorded only with the `statement` setting on, bound parameters never. | `statement` |
+| [`asyncpg`](https://github.com/GrahamDumpleton/wrapture-instrumentation-postgresql/blob/develop/src/wrapture_instrumentation_postgresql/asyncpg/README.md) | asyncpg 0.29+ (0.x) | Every query as one `database` leaf recorded around its await, however it was issued (a connection's `execute`, `executemany`, `fetch`, `fetchrow`, `fetchval` or `fetchmany`, a prepared statement's own fetches, a server-side cursor's DECLARE and each FETCH), each COPY, the connection being opened, and each transaction boundary, which asyncpg issues through `execute`. Each event carries the system, the operation, and the database, host and port it reached; a failing statement records the driver's exception. The SQL text (with its `$n` placeholders) is recorded only with the `statement` setting on, query arguments never. A connection taken from a pool does not yet record its queries (a wrapture fix is pending). | `statement` |
+
+The entry point name is the config's `name`""; the linked per-target
+README is the full user documentation: what records, what the events
+carry, the setting, and what is deliberately not traced.
+
+## What is not traced
+
+By design, and where it goes:
+
+- Fetching rows: a query event closes when its execute returns, so
+  time spent iterating rows afterwards is the application's, and a
+  server-side cursor's FETCHes are not recorded (its DECLARE is).
+
+- Pool checkouts (`psycopg_pool`): a connection taken from a pool
+  records its queries like any other, but taking and returning it are
+  not database operations and are not recorded.
+
+- A connection taken from an asyncpg pool does not yet record its
+  queries: the pool proxy calls the connection's methods through the
+  class, a calling convention wrapture's signature check does not
+  yet handle. The fix is on wrapture's side.
+
+- LISTEN/NOTIFY, large objects and two-phase commit are out of scope.
+
+## Adding a target
+
+Each client library is its own subpackage and entry point here. The
+subpackage's `__init__.py` holds one `wrapture.Instrumentation`
+subclass and imports only wrapture (and the package's own `common.py`,
+which imports only wrapture too); everything that touches the driver
+lives in sibling modules imported inside the hook. The class is
+registered in `pyproject.toml` under
+`[project.entry-points."wrapture.instrumentation"]`, and gets its own
+test suite under `tests/<target>/` and a `README.md` linked from the
+table above. 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 and the server they run against.
+
+## License
+
+BSD 2-Clause. See
+[LICENSE](https://github.com/GrahamDumpleton/wrapture-instrumentation-postgresql/blob/develop/LICENSE).

wrapture_instrumentation_postgresql-1.0.0.dev1/README.md

@@ -0,0 +1,132 @@
+# wrapture-instrumentation-postgresql
+
+Instrumentation for the PostgreSQL client libraries, 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 is
+the PostgreSQL package in that collection: one `wrapture.Instrumentation`
+class per client library, so tracing every query, connection and
+transaction your application sends to PostgreSQL is one config entry
+and no code.
+
+> **Status: alpha, ahead of 1.0.0.** Developed against wrapture's
+> alpha series, with pre-releases published to
+> [PyPI](https://pypi.org/project/wrapture-instrumentation-postgresql/),
+> and until 1.0.0 is final a plain `pip install
+> wrapture-instrumentation-postgresql` picks up the latest pre-release
+> automatically, so there is no need to pin a specific version.
+
+## Why a separate package
+
+The core
+[wrapture-instrumentation](https://github.com/GrahamDumpleton/wrapture-instrumentation)
+package deliberately covers only the standard library and third-party
+packages that can be exercised in-process, with no separate backend
+product or service needed to test against. A PostgreSQL driver is
+exactly the kind of target the separate-package rule was drawn for:
+its tests need a real server, so this package's suite runs one in a
+docker container, and it carries the drivers as test dependencies
+(some of them compiled wheels) and its own release cadence, so the
+core package's test matrix stays light. One package covers every
+client library for the one backend: psycopg, psycopg2 and asyncpg.
+
+## Installation
+
+```console
+$ pip install wrapture-instrumentation-postgresql
+```
+
+Installing it brings wrapture and nothing else. No driver is a
+dependency: each instrumentation is inert until its driver is present,
+and wrapture checks the installed version against the range the
+instrumentation supports at apply time.
+
+## Using it
+
+An `[[instrument]]` entry in `wrapture.toml` names the target:
+
+```toml
+[[instrument]]
+name = "psycopg"
+
+[[sink]]
+type = "printer"
+```
+
+and the runner applies it before the application starts, so the patch
+is in place before the driver 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`); through
+[manual setup](https://wrapture.readthedocs.io/en/latest/manual-setup.html),
+a few lines in the application's own startup where wrapping the launch
+from outside is awkward; and, in a test, through
+`wrapture.instrumentation("psycopg")` 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 it supports in the current
+environment, and what settings it takes:
+
+```console
+$ python -m wrapture.tools instrumentation --verbose
+```
+
+## Provided instrumentation
+
+| Target | Supported versions | Records | Settings |
+| ------ | ------------------ | ------- | -------- |
+| [`psycopg`](https://github.com/GrahamDumpleton/wrapture-instrumentation-postgresql/blob/develop/src/wrapture_instrumentation_postgresql/psycopg/README.md) | psycopg 3.1+ (3.x) | Every query as one `database` leaf, however it was issued (a cursor's `execute` or `executemany`, the connection's shortcut, a streamed query, a COPY, a server-side cursor's DECLARE), plus the connection being opened and each transaction boundary (`commit`, `rollback`, the connection's context manager, and a `transaction()` block's begin and end, savepoints included); sync and async classes alike, and connections from a pool. Each event carries the system, the operation, and the database, host and port it reached; a failing statement records the driver's exception. The SQL text is recorded only with the `statement` setting on, bound parameters never. | `statement` |
+| [`psycopg2`](https://github.com/GrahamDumpleton/wrapture-instrumentation-postgresql/blob/develop/src/wrapture_instrumentation_postgresql/psycopg2/README.md) | psycopg2 2.9+ (2.x), psycopg2-binary alike | Every query as one `database` leaf, however it was issued (`execute`, `executemany`, `callproc`, the extras' batch helpers, a named cursor's DECLARE), each COPY (`copy_from`, `copy_to`, `copy_expert`), the connection being opened and each transaction boundary (`commit`, `rollback`, the connection's context manager); through recording subclasses injected by psycopg2's own factory mechanism, so your `cursor_factory` and `connection_factory` classes keep working and are recorded too. Each event carries the system, the operation, and the database, host and port it reached; a failing statement records the driver's exception. The SQL text (the template with its placeholders) is recorded only with the `statement` setting on, bound parameters never. | `statement` |
+| [`asyncpg`](https://github.com/GrahamDumpleton/wrapture-instrumentation-postgresql/blob/develop/src/wrapture_instrumentation_postgresql/asyncpg/README.md) | asyncpg 0.29+ (0.x) | Every query as one `database` leaf recorded around its await, however it was issued (a connection's `execute`, `executemany`, `fetch`, `fetchrow`, `fetchval` or `fetchmany`, a prepared statement's own fetches, a server-side cursor's DECLARE and each FETCH), each COPY, the connection being opened, and each transaction boundary, which asyncpg issues through `execute`. Each event carries the system, the operation, and the database, host and port it reached; a failing statement records the driver's exception. The SQL text (with its `$n` placeholders) is recorded only with the `statement` setting on, query arguments never. A connection taken from a pool does not yet record its queries (a wrapture fix is pending). | `statement` |
+
+The entry point name is the config's `name`""; the linked per-target
+README is the full user documentation: what records, what the events
+carry, the setting, and what is deliberately not traced.
+
+## What is not traced
+
+By design, and where it goes:
+
+- Fetching rows: a query event closes when its execute returns, so
+  time spent iterating rows afterwards is the application's, and a
+  server-side cursor's FETCHes are not recorded (its DECLARE is).
+
+- Pool checkouts (`psycopg_pool`): a connection taken from a pool
+  records its queries like any other, but taking and returning it are
+  not database operations and are not recorded.
+
+- A connection taken from an asyncpg pool does not yet record its
+  queries: the pool proxy calls the connection's methods through the
+  class, a calling convention wrapture's signature check does not
+  yet handle. The fix is on wrapture's side.
+
+- LISTEN/NOTIFY, large objects and two-phase commit are out of scope.
+
+## Adding a target
+
+Each client library is its own subpackage and entry point here. The
+subpackage's `__init__.py` holds one `wrapture.Instrumentation`
+subclass and imports only wrapture (and the package's own `common.py`,
+which imports only wrapture too); everything that touches the driver
+lives in sibling modules imported inside the hook. The class is
+registered in `pyproject.toml` under
+`[project.entry-points."wrapture.instrumentation"]`, and gets its own
+test suite under `tests/<target>/` and a `README.md` linked from the
+table above. 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 and the server they run against.
+
+## License
+
+BSD 2-Clause. See
+[LICENSE](https://github.com/GrahamDumpleton/wrapture-instrumentation-postgresql/blob/develop/LICENSE).

wrapture_instrumentation_postgresql-1.0.0.dev1/TESTING.md

@@ -0,0 +1,264 @@
+# 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_postgresql/. Test files are named
+`test_*.py` and are discovered by pytest, 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, and the listing tool reporting every entry
+  cleanly.
+
+- One subdirectory per target, `tests/<target>/` (`tests/psycopg/`,
+  `tests/psycopg2/`, `tests/asyncpg/`),
+  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 (sync and async), resolving the entry point by
+  name, a check that the installed driver satisfies the class's
+  `supports` range, and the composition tests with the core package's
+  sqlalchemy target.
+
+Shared helpers and the server fixture live in
+[tests/conftest.py](tests/conftest.py).
+
+## The PostgreSQL server
+
+The suites drive the real drivers against a real PostgreSQL server;
+nothing is mocked. The session-scoped `postgresql` fixture supplies
+it, in one of two ways:
+
+- `WRAPTURE_POSTGRESQL_URL` in the environment names a server already
+  running (`postgresql://user:password@host:port/dbname`), and the
+  fixture uses it and starts nothing. This is how CI's service
+  container, the compose file's `postgres` service and a server of
+  your own are used.
+
+- Otherwise the fixture runs a throwaway container from the official
+  `postgres:17` image on a random localhost port, waits until a real
+  connection from the host answers, and removes the container at the
+  end of the session. This needs the docker CLI and a running daemon
+  (Docker Desktop, or anything docker-compatible).
+
+With neither, the session fails with a message saying so rather than
+skipping, so a green run always means the suites ran. The fixture
+yields a `Server` with the parts in both spellings the drivers take
+(`server.url`, `server.kwargs`). Tests isolate themselves with
+temporary tables (`CREATE TEMP TABLE`), private to their connection
+and gone when it closes, so no cleanup fixtures are needed.
+
+An interrupted run can leave its throwaway container behind;
+`just postgresql-clean` removes any such container.
+
+## 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 drivers the tests need.
+
+The simplest way to run the test suite is via the Justfile target,
+which runs natively on the default Python version and starts a
+throwaway server unless `WRAPTURE_POSTGRESQL_URL` is set:
+
+```console
+just test
+```
+
+Extra arguments are passed through to pytest, for example:
+
+```console
+just test -v
+just test tests/psycopg/test_recording.py
+just test -k transaction
+```
+
+One target's suite alone:
+
+```console
+just test-target psycopg
+```
+
+Equivalently, run pytest directly with uv:
+
+```console
+uv run pytest
+```
+
+To run against a longer-lived server instead of a throwaway one per
+session, start the compose file's server and export the URL it
+prints:
+
+```console
+just postgresql-start
+export WRAPTURE_POSTGRESQL_URL=postgresql://postgres:postgres@localhost:54329/postgres
+just test
+just postgresql-stop
+```
+
+## 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/psycopg -s
+```
+
+The same events can go to an OpenTelemetry backend instead, for
+checking the spans, their kinds and their attributes in something
+like otel-desktop-viewer. Setting WRAPTURE_OTEL installs wrapture's
+OpenTelemetry sink for the session (exporting over OTLP to
+http://localhost:4318, or wherever OTEL_EXPORTER_OTLP_ENDPOINT
+points) and flushes it when the session ends; the `test-otel` recipe
+sets the variable and overlays the wrapture[otel] dependencies the
+sink needs:
+
+```console
+just test-otel tests/psycopg/test_recording.py -k transaction
+```
+
+Each event the tests record arrives as its own single-span trace:
+the tests drive the driver directly with nothing of their own around
+the calls, and a `timeline()` roots what it records (an enclosing
+block or observed function outside the timeline is not the parent of
+what happens inside it), so a root span per test would have to be
+opened inside each test's own timeline and would then appear on the
+tape the assertions read.
+
+For a purpose-built run rather than the tests' traffic, the demo
+module under demo/ applies the instrumentation, drives the driver
+against the server `WRAPTURE_POSTGRESQL_URL` names, and prints both
+the live stream and the reconstructed tree with timings:
+
+```console
+just postgresql-start
+export WRAPTURE_POSTGRESQL_URL=postgresql://postgres:postgres@localhost:54329/postgres
+just demo-psycopg
+just demo-psycopg2
+just demo-asyncpg
+```
+
+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-psycopg --otel
+```
+
+## Testing across Python versions
+
+The project supports Python 3.12 through 3.15. Free threaded builds
+are not in the matrix: the instrumentation is pure Python and behaves
+the same on them, and a free threaded row would only be testing
+whether the drivers' own C extensions build without the GIL, which is
+their concern. 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).
+
+The full matrix runs inside docker, so the machine never needs
+PostgreSQL client libraries: psycopg's binary wheels bundle a libpq up
+to Python 3.14, but on 3.15 psycopg runs as pure Python and needs a
+libpq from the machine, which the image in the [Dockerfile](Dockerfile)
+supplies. The [compose.yml](compose.yml) file defines the server and
+a `tests` container built from that image; uv fetches the requested
+interpreter inside the container and installs the test dependencies
+into a per-version environment, both kept on named volumes so reruns
+pay for neither.
+
+```console
+just test-all
+just test-docker 3.15
+```
+
+The first run per version downloads the interpreter and the wheels.
+For the versions where every driver has a wheel, the suite can also
+run natively in a per-version environment (.venv-VERSION) that leaves
+the default .venv untouched:
+
+```console
+just test-python 3.13
+```
+
+## Testing across driver versions
+
+The `test` dependency group installs each driver at whatever version
+the lock resolves. The instrumentation's `supports` range is kept
+honest by running its suite against other lines of the driver. Each
+line has a place in `psycopg_versions`, `psycopg2_versions` or
+`asyncpg_versions` in the Justfile, run one at a time by
+`just test-psycopg 3.1.20`, `just test-psycopg2 2.9.9` or
+`just test-asyncpg 0.29.0`, or all by the `-all` forms, and the CI
+workflow runs the same matrix. These runs use an environment of their
+own on Python 3.12 with the driver's binary distribution at the
+requested version (`psycopg[binary]`, `psycopg2-binary`, `asyncpg`): a driver's
+binary wheel must match its version, and the older lines ship binary
+wheels only up to the Pythons of their day, so 3.12 is the Python
+every line has a wheel for, and no libpq is needed from the machine. A test in the suite
+asserts the installed driver satisfies `supports`, so a matrix entry
+outside the range fails loudly rather than passing vacuously.
+
+## Continuous integration
+
+The workflow runs every test job on Linux with a PostgreSQL service
+container (service containers are Linux-only, and the drivers do not
+differ per OS at the instrumented layer), the URL in the environment,
+across Python 3.12 to 3.15 and the driver version matrix.
+
+## 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/<target>/
+  (for one instrumentation) and name them `test_*.py`.
+
+- Import the package under test as
+  `wrapture_instrumentation_postgresql`, and the instrumentation
+  classes from their subpackages. The project is installed into the
+  uv-managed environment, so no path manipulation is needed.
+
+- Guard the driver imports with `pytest.importorskip` at the top of
+  the module (`pytest.importorskip("psycopg")`), so a build without
+  that driver skips the suite rather than erroring.
+
+- Take the `postgresql` fixture for the server and create temporary
+  tables for whatever the test needs; never leave ordinary tables
+  behind.
+
+- 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, and
+  `wrapture.instrumentation()` to scope an application of a class to
+  a block, driving the real driver against the real server. Do not
+  mock a driver and 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.
+
+- Async cases run their coroutine with `asyncio.run` inside the test;
+  no pytest-asyncio.
+
+- Tests should not depend on anything in the scratch/ directory,
+  which is not part of the repository.

wrapture_instrumentation_postgresql-1.0.0.dev1/compose.yml

@@ -0,0 +1,56 @@
+# The PostgreSQL server the tests need, and a container to run the
+# tests in for the Python versions that need a libpq from the machine.
+#
+#   just test-docker 3.15         one version, extra args to pytest
+#   just test-docker-all          every supported version
+#   just postgresql-start         the server alone, published on
+#                                 localhost:54329 for the demos and
+#                                 for running the tests natively
+#
+# The tests container gets the server's URL in the environment, so the
+# suite's server fixture uses it and starts nothing itself, exactly as
+# on CI with its service container. uv's cache and the managed
+# interpreters live on one named volume and the per-version project
+# environments on another, so a rerun pays for neither the download
+# nor the install, and the container's environment never collides
+# with the .venv the host uses in the same directory.
+
+services:
+  postgres:
+    image: postgres:17
+    environment:
+      POSTGRES_PASSWORD: postgres
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+    ports:
+      - "127.0.0.1:${WRAPTURE_POSTGRESQL_PORT:-54329}:5432"
+
+  tests:
+    build: .
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      WRAPTURE_POSTGRESQL_URL: postgresql://postgres:postgres@postgres:5432/postgres
+      UV_PYTHON: ${UV_PYTHON:-3.14}
+      UV_CACHE_DIR: /cache/uv
+      UV_PYTHON_INSTALL_DIR: /cache/python
+      UV_LINK_MODE: copy
+    volumes:
+      - .:/work
+      - uv-cache:/cache
+      - venvs:/venv
+    entrypoint:
+      - sh
+      - -c
+      - |
+        export UV_PROJECT_ENVIRONMENT="/venv/$$UV_PYTHON"
+        exec uv run --python "$$UV_PYTHON" --no-default-groups --group test pytest "$$@"
+      - tests
+
+volumes:
+  uv-cache:
+  venvs: