snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/debug/assets/pages/config.html

@@ -0,0 +1,34 @@
+<!-- Vista "Config": cómo se configura el panel. Estático (informativo, no interactivo: el panel es SSR
+     por request). Textos traducibles con `data-t`; env-vars y código NO se traducen. -->
+<div class="snk-help">
+  <div class="snk-help-card">
+    <h4 data-t="cfg_channels">Canales de debug</h4>
+    <p data-t="cfg_channels_d">Qué entrega el panel. Se combinan por coma:</p>
+    <p><code>SNAKE_ORM_DEBUG=ssr,envelope,timing</code></p>
+    <p><code>ssr</code> · <span data-t="cfg_ch_ssr">panel HTML inyectado en la respuesta</span></p>
+    <p><code>envelope</code> · <span data-t="cfg_ch_envelope">el debug en el JSON, bajo la clave</span> <code>snakeorm</code></p>
+    <p><code>timing</code> · <span data-t="cfg_ch_timing">cabecera Server-Timing</span></p>
+    <p><code>sidecar</code> · <span data-t="cfg_ch_sidecar">un token y su propia página en</span> <code>/__snake__/{token}</code></p>
+    <p><code>otel</code> · <span data-t="cfg_ch_otel">DECLARADO y sin implementar: encenderlo no entrega nada y avisa</span></p>
+  </div>
+  <div class="snk-help-card">
+    <h4 data-t="cfg_advise">Umbral del asesor</h4>
+    <p data-t="cfg_advise_d">Solo sugiere índices para queries más lentas que X ms (por debajo, un índice no cambia nada):</p>
+    <p><code>SNAKE_ORM_ADVISE_MS=10</code></p>
+    <p><span data-t="cfg_advise_code">O tipado en código:</span> <code>SnakeDebugConfig(advise_min_ms=25)</code></p>
+  </div>
+  <div class="snk-help-card">
+    <h4 data-t="cfg_where">Qué va en config y qué en el comando</h4>
+    <p data-t="cfg_where_d">La regla: si la aplicación lo necesita para funcionar, va en config; si solo lo necesita esa invocación, va en flag.</p>
+    <p><code>SnakeOrmConfig</code> · <span data-t="cfg_where_cfg">databases, debug, advise_ms, migrations_dir, language</span></p>
+    <p><span data-t="cfg_where_cli">Flags del comando:</span> <code>--out</code>, <code>--schema</code>, <code>--keep-underscores</code></p>
+    <p data-t="cfg_where_db">--database no sobrescribe nada: ELIGE una de las conexiones que declara la config. Un nombre que no esté no se puede crear desde el comando.</p>
+    <p data-t="cfg_where_django">En Django no se declara aparte: el CLI sube hasta manage.py, lee su DJANGO_SETTINGS_MODULE y traduce settings.DATABASES + settings.SNAKEORM al mismo objeto.</p>
+  </div>
+  <div class="snk-help-card">
+    <h4 data-t="cfg_prod">Producción</h4>
+    <p data-t="cfg_prod_d">Los que entregan el SQL a quien pide —ssr, envelope y sidecar— se caen con production=True, aunque los configures. timing se queda: mide, no cuenta.</p>
+    <p><code>SNAKE_ORM_PRODUCTION=true</code></p>
+    <p data-t="cfg_prod_env">Del entorno no se adivina nada: si hay un canal de riesgo encendido y nadie lo ha declarado —ni esta variable, ni production= en el middleware, ni SnakeDebugConfig— el arranque se niega en vez de elegir un defecto.</p>
+  </div>
+</div>

snakeorm/debug/assets/pages/database_first.html

@@ -0,0 +1,29 @@
+<!-- Vista "DB-first": adoptar una BD existente (scaffolding + modelo espejo + deriva). Estático. Textos
+     traducibles con `data-t`; comandos y decoradores NO se traducen. Se inlinea como una vista más. -->
+<div class="snk-help">
+  <div class="snk-help-card">
+    <h4 data-t="dbf_scaffold">Generar modelos</h4>
+    <p data-t="dbf_scaffold_d">Espeja una BD existente a modelos Python:</p>
+    <p><code>snakeorm scaffold create --out models.py</code></p>
+    <p><span data-t="dbf_scaffold_u">Re-sincronizar (sobrescribe entero):</span> <code>scaffold update</code></p>
+    <p><span data-t="dbf_scaffold_out">Sin</span> <code>--out</code> <span data-t="dbf_scaffold_out2">no genera: no hay ruta por defecto y falla diciéndolo.</span></p>
+  </div>
+  <div class="snk-help-card">
+    <h4 data-t="dbf_mirror">Modelo espejo</h4>
+    <p><code>@snake_db_first</code> · <span data-t="dbf_mirror_d">marca un modelo como espejo: las migraciones lo IGNORAN. El esquema es del sysadmin, no nuestro.</span></p>
+    <p data-t="dbf_mirror_adopt">NO hay adopción in situ: cambiarlo a @snake_model no le entrega los mandos a las migraciones, porque el histórico no conoce la tabla y el autogen solo emitiría un CreateTable, que contra la tabla existente muere. Sirve para LLEVARSE el esquema a otra base gobernada desde cero.</p>
+  </div>
+  <div class="snk-help-card">
+    <h4 data-t="dbf_names">Nombres de las clases</h4>
+    <p data-t="dbf_names_d">La clase se llama como la tabla, en CapWords y con el esquema delante:</p>
+    <p><code>public.project_requests</code> → <code>PublicProjectRequests</code></p>
+    <p><code>--keep-underscores</code> · <span data-t="dbf_names_u">deja los guiones bajos</span> <code>Public_project_requests</code></p>
+    <p><code>--no-schema-prefix</code> · <span data-t="dbf_names_s">quita el esquema; dos esquemas con la misma tabla COLISIONAN y se avisa</span></p>
+    <p data-t="dbf_names_why">No se quita el plural: eso es adivinar en inglés y rompe status, analysis o direcciones. Lo que no se puede nombrar se avisa y se deja fuera, nunca se inventa.</p>
+  </div>
+  <div class="snk-help-card">
+    <h4 data-t="dbf_check">Deriva</h4>
+    <p data-t="dbf_check_d">Compara el código con la BD real y avisa si no cuadran:</p>
+    <p><code>snakeorm check --models miapp.models</code></p>
+  </div>
+</div>

snakeorm/debug/assets/pages/help.html

@@ -0,0 +1,21 @@
+<!-- Contenido ESTÁTICO de la vista "Ayuda" del panel: cómo usar la herramienta. Se inlinea dentro del
+     shadow root como una vista más. Los textos traducibles llevan `data-t` (el JS los swapea); el
+     server pinta el español por defecto. Los fragmentos de código/env-var no se traducen. -->
+<div class="snk-help">
+  <div class="snk-help-card">
+    <h4 data-t="help_enable">Activar el panel</h4>
+    <p><code>SNAKE_ORM_DEBUG=ssr,envelope,timing</code></p>
+  </div>
+  <div class="snk-help-card">
+    <h4 data-t="help_json">JSON de la API</h4>
+    <p><span data-t="help_json_d">Con el canal envelope, en cada respuesta JSON bajo la clave</span> <code>snakeorm</code></p>
+  </div>
+  <div class="snk-help-card">
+    <h4 data-t="help_shortcuts">Atajos</h4>
+    <p data-t="help_shortcuts_d">Esc cierra · arrastra el botón para moverlo · ◐ tema · 🌐 idioma</p>
+  </div>
+  <div class="snk-help-card">
+    <h4 data-t="help_read">Leer las consultas</h4>
+    <p data-t="help_read_d">×N = misma consulta repetida · ↳ fichero:línea = de dónde salió · los ? ya llevan su valor real · pliega los avisos y elige cuántas queries ves por página para ganar sitio</p>
+  </div>
+</div>

snakeorm/debug/assets/pages/history.html

@@ -0,0 +1,27 @@
+<!-- Vista "Historial": las llamadas que la página hace DESPUÉS del render (fetch, XHR, HTMX, Alpine).
+     Es la única vista DINÁMICA: el servidor pinta el esqueleto y el cliente añade sus `<li>` a
+     `.snk-history-list`. Las tarjetas de arriba son aritmética del cliente sobre esa misma lista:
+     el servidor las pinta vacías (con sus textos traducibles) y el JS solo escribe los números.
+     Textos traducibles con `data-t`; el código y las env-vars no se traducen.
+     `.snk-history-off` solo se ve cuando la vista lleva `data-envelope="off"`. -->
+<div class="snk-help">
+  <div class="snk-help-card snk-history-live">
+    <div class="snk-metrics snk-hmetrics">
+      <div class="snk-m" title="Llamadas que la página ha hecho desde que cargó." data-tt="hcalls_tip"><b data-hm="calls">0</b><span data-t="hcalls">llamadas</span></div>
+      <div class="snk-m" title="Suma de las consultas de esas llamadas." data-tt="hqueries_tip"><b data-hm="queries">0</b><span data-t="queries">queries</span><em class="snk-m-part" data-hm-part="queries" title="Calculado solo sobre las llamadas que trajeron el dato; las demás no cuentan como cero." data-tt="hpart_tip"></em></div>
+      <div class="snk-m" title="Suma de lo que esas llamadas esperaron a la BD." data-tt="hdb_tip"><b data-hm="db">0.00<small>ms</small></b><span data-t="db">en BD</span><em class="snk-m-part" data-hm-part="db" title="Calculado solo sobre las llamadas que trajeron el dato; las demás no cuentan como cero." data-tt="hpart_tip"></em></div>
+      <div class="snk-m" title="Suma del mapeo de esas llamadas: filas convertidas en objetos." data-tt="hmap_tip"><b data-hm="map">0.00<small>ms</small></b><span data-t="map">mapeo</span><em class="snk-m-part" data-hm-part="map" title="Calculado solo sobre las llamadas que trajeron el dato; las demás no cuentan como cero." data-tt="hpart_tip"></em></div>
+      <div class="snk-m" title="La llamada que más esperó a la BD de toda la lista." data-tt="hslowest_tip"><b data-hm="slowest">0.00<small>ms</small></b><span data-t="slowest">más lenta</span><em class="snk-m-part" data-hm-part="slowest" title="Calculado solo sobre las llamadas que trajeron el dato; las demás no cuentan como cero." data-tt="hpart_tip"></em></div>
+    </div>
+    <h4 data-t="hist_title">Llamadas posteriores</h4>
+    <p data-t="hist_intro">El informe de arriba es el de la petición que pintó esta página. Aquí se apilan las que vienen después, sin recargar.</p>
+    <ul class="snk-history-list"></ul>
+    <p class="snk-history-empty" data-t="hist_empty">Aún no hay llamadas.</p>
+  </div>
+  <div class="snk-help-card snk-history-off">
+    <h4 data-t="hist_off">Falta el canal envelope</h4>
+    <p data-t="hist_off_d">El histórico lee el informe que el ORM cuelga de las respuestas JSON. Sin ese canal no llega ninguno, así que aquí no habría nada que apilar:</p>
+    <p><code>SNAKE_ORM_DEBUG=ssr,envelope</code></p>
+    <p data-t="hist_off_why">El panel lo dice y no lo enciende: ssr y envelope son canales independientes y quien los elige eres tú.</p>
+  </div>
+</div>

snakeorm/debug/capture.py

@@ -0,0 +1,234 @@
+"""`CaptureDriver` / `AsyncCaptureDriver`: driver decorators that record each statement into the scope's collector.
+
+With no active scope they delegate without timing or recording: with the debug off, the cost is one `ContextVar` read.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Sequence
+from time import perf_counter
+
+from snakeorm.debug.collector import current_collector
+from snakeorm.debug.record import QueryKind
+from snakeorm.drivers.asyncbase import AsyncDriver
+from snakeorm.drivers.base import SnakeDriver
+
+
+class CaptureDriver:
+    """Wrap a `SnakeDriver` and record each statement into the active collector (if there is one)."""
+
+    __slots__ = ("_inner", "_system")
+
+    def __init__(self, inner: SnakeDriver, *, system: str = "") -> None:
+        """`system` is the engine's OpenTelemetry name (`db.system.name`), DECLARED by the caller.
+
+        It is read once here and copied onto every record, so the per-query cost is an attribute
+        read. It is not derived from the driver's class: a decorator chain (pool, timeout, logging)
+        would hide it, and guessing from the SQL cannot tell MySQL from MariaDB.
+        """
+        self._inner = inner
+        self._system = system
+
+    def fetch_all(self, sql: str, params: Sequence[object]) -> list[tuple[object, ...]]:
+        """Run the read; if there is a scope, record SQL, time and rows returned."""
+        collector = current_collector()
+        if collector is None:
+            return self._inner.fetch_all(sql, params)
+        start = perf_counter()
+        rows = self._inner.fetch_all(sql, params)
+        collector.add(
+            sql=sql,
+            params=params,
+            duration_ms=(perf_counter() - start) * 1000,
+            rows=len(rows),
+            kind=QueryKind.SELECT,
+            started_at=start,
+            system=self._system,
+        )
+        return rows
+
+    def fetch_iter(
+        self, sql: str, params: Sequence[object], *, chunk: int = 1000
+    ) -> Iterator[tuple[object, ...]]:
+        """Yield the rows in streaming; if there is a scope, record SQL, time and rows CONSUMED.
+
+        It gets noted at the end, not at the start, and for two reasons. The first is that counting
+        beforehand would demand materialising the result, which is exactly what this path avoids.
+        The second is that in streaming the interesting figure IS what was consumed: a `break` at
+        the tenth row out of a million counts ten, and that is what the panel must show.
+
+        The measured time includes whatever the consumer takes between rows. It is unavoidable —the
+        cursor stays open that whole time— and it is also honest: that is how long the query lasts
+        from the point of view of the connection, which is the one being held.
+        """
+        collector = current_collector()
+        if collector is None:
+            yield from self._inner.fetch_iter(sql, params, chunk=chunk)
+            return
+        start = perf_counter()
+        consumed = 0
+        try:
+            for row in self._inner.fetch_iter(sql, params, chunk=chunk):
+                consumed += 1
+                yield row
+        finally:
+            collector.add(
+                sql=sql,
+                params=params,
+                duration_ms=(perf_counter() - start) * 1000,
+                rows=consumed,
+                kind=QueryKind.SELECT,
+                started_at=start,
+                system=self._system,
+            )
+
+    def execute(self, sql: str, params: Sequence[object]) -> int:
+        """Run the write; if there is a scope, record SQL, time and rows affected."""
+        collector = current_collector()
+        if collector is None:
+            return self._inner.execute(sql, params)
+        start = perf_counter()
+        affected = self._inner.execute(sql, params)
+        collector.add(
+            sql=sql,
+            params=params,
+            duration_ms=(perf_counter() - start) * 1000,
+            rows=affected,
+            kind=QueryKind.WRITE,
+            started_at=start,
+            system=self._system,
+        )
+        return affected
+
+    @property
+    def last_insert_id(self) -> int:
+        """Forward to the wrapped driver (see the `SnakeDriver` Protocol)."""
+        return self._inner.last_insert_id
+
+    def commit(self) -> None:
+        """Delegate the commit."""
+        self._inner.commit()
+
+    def rollback(self) -> None:
+        """Delegate the rollback."""
+        self._inner.rollback()
+
+    def savepoint(self, name: str) -> None:
+        """Delegate the savepoint."""
+        self._inner.savepoint(name)
+
+    def release_savepoint(self, name: str) -> None:
+        """Delegate the savepoint release."""
+        self._inner.release_savepoint(name)
+
+    def rollback_to_savepoint(self, name: str) -> None:
+        """Delegate the rollback to the savepoint."""
+        self._inner.rollback_to_savepoint(name)
+
+    def close(self) -> None:
+        """Close the inner driver."""
+        self._inner.close()
+
+
+class AsyncCaptureDriver:
+    """Asynchronous mirror of `CaptureDriver`, over the `AsyncDriver` Protocol."""
+
+    __slots__ = ("_inner", "_system")
+
+    def __init__(self, inner: AsyncDriver, *, system: str = "") -> None:
+        """Same declaration as the synchronous one: the engine's `db.system.name`, given not guessed."""
+        self._inner = inner
+        self._system = system
+
+    async def fetch_all(
+        self, sql: str, params: Sequence[object]
+    ) -> list[tuple[object, ...]]:
+        """Run the async read; if there is a scope, record SQL, time and rows returned."""
+        collector = current_collector()
+        if collector is None:
+            return await self._inner.fetch_all(sql, params)
+        start = perf_counter()
+        rows = await self._inner.fetch_all(sql, params)
+        collector.add(
+            sql=sql,
+            params=params,
+            duration_ms=(perf_counter() - start) * 1000,
+            rows=len(rows),
+            kind=QueryKind.SELECT,
+            started_at=start,
+            system=self._system,
+        )
+        return rows
+
+    async def fetch_iter(
+        self, sql: str, params: Sequence[object], *, chunk: int = 1000
+    ) -> AsyncIterator[tuple[object, ...]]:
+        """Async mirror of `CaptureDriver.fetch_iter`: it records the rows CONSUMED, at the end."""
+        collector = current_collector()
+        if collector is None:
+            async for row in self._inner.fetch_iter(sql, params, chunk=chunk):
+                yield row
+            return
+        start = perf_counter()
+        consumed = 0
+        try:
+            async for row in self._inner.fetch_iter(sql, params, chunk=chunk):
+                consumed += 1
+                yield row
+        finally:
+            collector.add(
+                sql=sql,
+                params=params,
+                duration_ms=(perf_counter() - start) * 1000,
+                rows=consumed,
+                kind=QueryKind.SELECT,
+                started_at=start,
+                system=self._system,
+            )
+
+    async def execute(self, sql: str, params: Sequence[object]) -> int:
+        """Run the async write; if there is a scope, record SQL, time and rows affected."""
+        collector = current_collector()
+        if collector is None:
+            return await self._inner.execute(sql, params)
+        start = perf_counter()
+        affected = await self._inner.execute(sql, params)
+        collector.add(
+            sql=sql,
+            params=params,
+            duration_ms=(perf_counter() - start) * 1000,
+            rows=affected,
+            kind=QueryKind.WRITE,
+            started_at=start,
+            system=self._system,
+        )
+        return affected
+
+    @property
+    def last_insert_id(self) -> int:
+        """Delegate the id of the last INSERT: capturing the SQL does not change what the engine wrote."""
+        return self._inner.last_insert_id
+
+    async def commit(self) -> None:
+        """Delegate the commit."""
+        await self._inner.commit()
+
+    async def rollback(self) -> None:
+        """Delegate the rollback."""
+        await self._inner.rollback()
+
+    async def savepoint(self, name: str) -> None:
+        """Delegate the savepoint."""
+        await self._inner.savepoint(name)
+
+    async def release_savepoint(self, name: str) -> None:
+        """Delegate the savepoint release."""
+        await self._inner.release_savepoint(name)
+
+    async def rollback_to_savepoint(self, name: str) -> None:
+        """Delegate the rollback to the savepoint."""
+        await self._inner.rollback_to_savepoint(name)
+
+    async def close(self) -> None:
+        """Close the inner driver."""
+        await self._inner.close()

snakeorm/debug/channel.py

@@ -0,0 +1,131 @@
+"""Debug delivery channels and the parsing of `SNAKE_ORM_DEBUG`.
+
+A channel is a DELIVERY mode of the same report; they compose as a `frozenset[SnakeDebugChannel]`. The environment string is only their serialisation.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from enum import Enum, StrEnum
+
+from snakeorm.core.exceptions import SnakeConfigError
+
+DEBUG_ENV_KEY = "SNAKE_ORM_DEBUG"
+"""Environment variable that turns the channels on, as a comma-separated list."""
+
+
+class SnakeDebugChannel(StrEnum):
+    """How the report is DELIVERED. Independent channels that combine freely; each contrib applies only the ones that make sense in its framework."""
+
+    SSR = "ssr"  # an HTML panel injected into the response (Django/Flask)
+    ENVELOPE = "envelope"  # a `snakeorm` block in the JSON + a text table — NO tooling (Postman)
+    TIMING = "timing"  # a Server-Timing header — WITH tooling (the browser devtools)
+    SIDECAR = "sidecar"  # a token + its own page at /__snake__/{token}
+    OTEL = "otel"  # OpenTelemetry spans over OTLP — WITH tooling (Jaeger/Grafana)
+
+
+class ChannelAudience(Enum):
+    """WHO ends up holding what a channel delivers. It is the axis that decides risk.
+
+    The set of risky channels used to be written out by hand as `{envelope, sidecar}`, under the
+    heading "the ones that come back to the client". That heading is not the rule it was standing
+    in for: `ssr` comes back to the client too, and `timing` also does while being harmless. `ssr`
+    was missing, and what is missing from a hand-written set reads as harmless without anyone
+    deciding so — which is how a production deploy came to hand its SQL to anonymous visitors.
+
+    The real question is two-part, and this enum asks both halves: who receives it, and does what
+    they receive contain the SQL.
+    """
+
+    CLIENT_SQL = "client_sql"
+    """The requester gets the statements themselves. Never in production."""
+
+    CLIENT_METRICS = "client_metrics"
+    """The requester gets timings and counts, no SQL. Safe to leave on."""
+
+    OPERATOR = "operator"
+    """It goes out SIDEWAYS, to infrastructure the operator already runs — never on the response."""
+
+
+CHANNEL_AUDIENCE: Mapping[SnakeDebugChannel, ChannelAudience] = {
+    # The panel paints every statement with the placeholders ALREADY REPLACED by their values, plus
+    # the `file:line` of the application code that fired them. Strictly MORE than the envelope.
+    SnakeDebugChannel.SSR: ChannelAudience.CLIENT_SQL,
+    SnakeDebugChannel.ENVELOPE: ChannelAudience.CLIENT_SQL,
+    SnakeDebugChannel.SIDECAR: ChannelAudience.CLIENT_SQL,
+    # A `Server-Timing` header: how long, not what. It is the one delivery worth leaving on.
+    SnakeDebugChannel.TIMING: ChannelAudience.CLIENT_METRICS,
+    # Spans over OTLP, to the operator's own collector. Production is the ONLY place a tracing
+    # channel justifies existing, so filing it as risky would be declaring it dead.
+    SnakeDebugChannel.OTEL: ChannelAudience.OPERATOR,
+}
+"""Who receives each channel. Exhaustive by construction — see the guard right below."""
+
+
+def demand_every_channel_classified(
+    audience: Mapping[SnakeDebugChannel, ChannelAudience],
+) -> None:
+    """Blows up if a channel of the enum has no audience declared. Runs AT IMPORT.
+
+    Same mechanism the capability catalogue uses (`SnakeCapabilities.__post_init__`) and for the
+    same reason: a channel that nobody classified would simply not be risky, which is precisely the
+    silence this module exists to prevent. Declaring the audience is not paperwork — it is the only
+    moment somebody is forced to think about who ends up with the SQL.
+    """
+    missing = [
+        channel.value for channel in SnakeDebugChannel if channel not in audience
+    ]
+    if missing:
+        raise SnakeConfigError(
+            f"These debug channels do not declare who receives them: {', '.join(missing)}. "
+            f"Every channel declares an audience: an unclassified one would read as harmless "
+            f"and would survive the production filter without anyone having decided so."
+        )
+
+
+demand_every_channel_classified(CHANNEL_AUDIENCE)
+
+RISKY_CHANNELS: frozenset[SnakeDebugChannel] = frozenset(
+    channel
+    for channel, audience in CHANNEL_AUDIENCE.items()
+    if audience is ChannelAudience.CLIENT_SQL
+)
+"""Channels that hand the SQL to whoever asked: dropped in production even if configured.
+
+DERIVED, never written out. The literal it replaces was missing `ssr` and nothing could tell."""
+
+# Channels that are DECLARED but not built yet. Enabling one delivers nothing, so it WARNS instead
+# of failing silently. It is EMPTY today: `otel` was the last one in it and now exports for real
+# (`debug/otel/`). The mechanism stays for the next channel declared ahead of its exporter; what
+# does not stay is a warning telling users that a working channel delivers nothing.
+UNIMPLEMENTED_CHANNELS: frozenset[SnakeDebugChannel] = frozenset()
+
+
+def parse_channels(raw: str) -> frozenset[SnakeDebugChannel]:
+    """Parse `"ssr,envelope"` into a `frozenset`. Empty → off; spaces/uppercase are forgiven.
+
+    An UNKNOWN name blows up naming it: a typo that silently left you without debug is precisely the failure being fought.
+    """
+    channels: set[SnakeDebugChannel] = set()
+    for token in raw.split(","):
+        name = token.strip().lower()
+        if not name:
+            continue
+        try:
+            channels.add(SnakeDebugChannel(name))
+        except ValueError:
+            valid = ", ".join(channel.value for channel in SnakeDebugChannel)
+            raise SnakeConfigError(
+                f"Unknown debug channel: '{name}'. "
+                f"{DEBUG_ENV_KEY} accepts these channels: {valid}."
+            ) from None
+    return frozenset(channels)
+
+
+def channels_from_env(
+    environ: Mapping[str, str] | None = None,
+) -> frozenset[SnakeDebugChannel]:
+    """Read `SNAKE_ORM_DEBUG` from the environment (or the given map, for tests) and parse it into channels."""
+    env = os.environ if environ is None else environ
+    return parse_channels(env.get(DEBUG_ENV_KEY, ""))

snakeorm/debug/collector.py

@@ -0,0 +1,144 @@
+"""Per-scope collector where the `QueryRecord`s of a unit of work land.
+
+Built on `ContextVar` (neither global nor thread-local): it works in sync and async and does not get contaminated between concurrent requests that share a thread.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar
+from functools import wraps
+from time import perf_counter
+from typing import ParamSpec, TypeVar
+
+from snakeorm.debug.origin import capture_origin
+from snakeorm.debug.record import QueryKind, QueryRecord
+from snakeorm.debug.report import DebugReport
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class DebugCollector:
+    """Accumulate the records of a scope and freeze them into a `DebugReport` on demand.
+
+    It also holds the scope's MAPPING total. It lives here and not on the report because the
+    mapping happens INSIDE the scope, exactly like the queries do — the wall clock is the odd one
+    out, measured by the middleware around the scope and stamped afterwards.
+    """
+
+    __slots__ = ("_mapping_ms", "_records")
+
+    def __init__(self) -> None:
+        self._records: list[QueryRecord] = []
+        self._mapping_ms = 0.0
+
+    def add(
+        self,
+        *,
+        sql: str,
+        params: Sequence[object],
+        duration_ms: float,
+        rows: int,
+        kind: QueryKind,
+        started_at: float = 0.0,
+        system: str = "",
+    ) -> None:
+        """Record a statement, numbering it by arrival order (1-based) and noting its ORIGIN.
+
+        The origin (file/line/function of the user code that fired the query) is resolved HERE,
+        while the caller's stack is still alive: one frame up is the capture driver and, above
+        that, the app's code.
+
+        `started_at` is the monotonic instant the driver measured FROM; `system` the engine it
+        declared. Both are passed through untouched: this collector computes neither.
+        """
+        self._records.append(
+            QueryRecord(
+                n=len(self._records) + 1,
+                sql=sql,
+                params=tuple(params),
+                duration_ms=duration_ms,
+                rows=rows,
+                kind=kind,
+                origin=capture_origin(),
+                started_at=started_at,
+                system=system,
+            )
+        )
+
+    def add_mapping(self, duration_ms: float) -> None:
+        """Add a BATCH of hydration to the scope's mapping total (see `timed_mapping`)."""
+        self._mapping_ms += duration_ms
+
+    @property
+    def mapping_ms(self) -> float:
+        """Time spent turning rows into objects in this scope. Zero is MEASURED, not unknown."""
+        return self._mapping_ms
+
+    def report(self) -> DebugReport:
+        """The snapshot of what has been captured so far."""
+        return DebugReport.from_records(self._records, mapping_ms=self._mapping_ms)
+
+
+# The active collector of the current scope. `None` = nothing is being captured (passthrough).
+_active: ContextVar[DebugCollector | None] = ContextVar(
+    "snakeorm_debug_collector", default=None
+)
+
+
+@contextmanager
+def capture_queries() -> Iterator[DebugCollector]:
+    """Open a capture scope and return its collector; on the way out it restores the previous one.
+
+    A synchronous context manager on purpose and still valid for async: setting/restoring a `ContextVar` needs no `await` and the value travels with the task.
+    """
+    collector = DebugCollector()
+    token = _active.set(collector)
+    try:
+        yield collector
+    finally:
+        _active.reset(token)
+
+
+def current_collector() -> DebugCollector | None:
+    """The collector of the active scope, or `None` if nothing is being captured."""
+    return _active.get()
+
+
+def timed_mapping(function: Callable[P, R]) -> Callable[P, R]:
+    """Mark a callable that turns an ALREADY FETCHED result set into objects, and time it.
+
+    Decorate only a body that has its rows in hand and does nothing but build objects out of them.
+    Two things must stay outside or the number lies: I/O of any kind, and resolving a relationship
+    that fires its own query. Get that wrong and `DB + MAPPING + APP` stops adding up to the
+    request, which is the invariant the panel's cards promise.
+
+    ONE lookup per result set, never per row — the same argument `_hydrate_with_plan` makes about
+    the plan. Measured on the hydration loop with the debug OFF: a `ContextVar` read inside the row
+    loop costs +52 ns/row (+4.3% on a five-column row), while this gate costs ~130 ns per RESULT
+    SET however many rows it holds. A decorator and not a `with` block for the same reason: an
+    equivalent `@contextmanager` measured ~1000 ns per result set, which is +80% on the one-row
+    read `get()` and `first()` do.
+
+    Do NOT nest two of these: the inner one would be counted twice.
+
+    STREAMING (`iterate`) is deliberately NOT marked: the capture driver's stopwatch around
+    `fetch_iter` spans whatever the consumer does BETWEEN rows, so hydration during a stream is
+    already inside `db_ms` and timing it again would count it twice. A streaming read reports a
+    MAPPING that leaves that share out; the sum stays true.
+    """
+
+    @wraps(function)
+    def timed(*args: P.args, **kwargs: P.kwargs) -> R:
+        collector = current_collector()
+        if collector is None:
+            return function(*args, **kwargs)
+        start = perf_counter()
+        try:
+            return function(*args, **kwargs)
+        finally:
+            collector.add_mapping((perf_counter() - start) * 1000)
+
+    return timed