snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/contrib/django.py

@@ -0,0 +1,245 @@
+"""Django adapter: middleware that branches by `Content-Type` (the panel in HTML, `snakeorm` in JSON) for the hybrid SSR + `/api/` case.
+
+The production gate is tied to `settings.DEBUG`. Django is imported LAZILY (only when serving the sidecar), so the module imports and tests without Django installed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from time import perf_counter
+from typing import TYPE_CHECKING, Any, cast
+
+from snakeorm.advisor import DEFAULT_MIN_MS
+
+# `X as X`: an EXPLICIT re-export — the user's settings.py imports them from here (Django's world).
+from snakeorm.contrib.config import SnakeOrmDatabase as SnakeOrmDatabase
+from snakeorm.contrib.config import SnakeOrmSettings as SnakeOrmSettings
+from snakeorm.contrib.config import (
+    SnakeOrmConfig,
+    connection_from_mapping,
+    debug_config_from_mapping,
+)
+from snakeorm.contrib.deliver import (
+    allowed_channels,
+    index_advice,
+    plan_delivery,
+    serve_sidecar,
+    transform_body,
+)
+from snakeorm.contrib.sidecar import SidecarBuffer, new_token
+from snakeorm.debug import (
+    SnakeDebugChannel,
+    SnakeDebugConfig,
+    SnakeDebugLanguage,
+    SnakeWebFramework,
+    capture_queries,
+    channels_from_env,
+    export_report,
+    RequestInfo,
+    warn_unimplemented,
+    warn_unsupported,
+)
+
+if TYPE_CHECKING:
+    from snakeorm.session import SnakeSession
+
+_SIDECAR_PREFIX = "/__snake__/"
+
+
+def _django_is_production() -> bool:
+    """`True` if Django says it is NOT in debug; `False` if Django is absent (falls back to dev).
+
+    It only resolves the `settings.DEBUG` signal; the real gate is exercised by the pure layer
+    `allowed_channels`.
+    """
+    try:
+        from django.conf import settings  # pyright: ignore[reportMissingImports]
+
+        return not settings.DEBUG
+    except Exception:
+        return False
+
+
+def _csp_nonce_for(request: Any, config: SnakeDebugConfig) -> str | None:
+    """The REQUEST's nonce (`request.csp_nonce`) if there is one; otherwise the config's.
+
+    django-csp mints one per response and hangs it there, which is what CSP asks for; a nonce fixed
+    in the config is the same for every response. Django is the only one of the three adapters with
+    a request object to ask. Absent django-csp the attribute is not there and the config wins.
+    `str()` because the value is a lazy object, not a `str`.
+    """
+    nonce = getattr(request, "csp_nonce", None)
+    return config.csp_nonce if nonce is None else str(nonce)
+
+
+def _accept_of(request: Any) -> str:
+    """The request's `Accept` header, or an empty string when there is none to read.
+
+    `request.headers` is Django's own case-insensitive mapping. It is read defensively because this
+    method also runs against request doubles that carry nothing but a path.
+    """
+    headers = getattr(request, "headers", None)
+    if headers is None:
+        return ""
+    return str(headers.get("Accept", ""))
+
+
+class SnakeDebugMiddleware:
+    """Django middleware that captures the SQL and delivers the debug per `SNAKE_ORM_DEBUG`."""
+
+    def __init__(self, get_response: Any) -> None:
+        self._get_response = get_response
+        # The config comes out of the `SNAKEORM` constant of settings.py (Django's idiomatic way).
+        # If it is not declared (or Django is not configured, in the tests), it falls back to the
+        # environment as before.
+        snakeorm = _django_setting("SNAKEORM")
+        if snakeorm:
+            channels, self._config = debug_config_from_mapping(
+                cast("SnakeOrmSettings", snakeorm)
+            )
+        else:
+            channels, self._config = channels_from_env(), SnakeDebugConfig.from_env()
+        self._channels = allowed_channels(channels, production=_django_is_production())
+        self._buffer = SidecarBuffer()
+        warn_unsupported(self._channels, SnakeWebFramework.DJANGO)
+        warn_unimplemented(self._channels)
+
+    def __call__(self, request: Any) -> Any:
+        """Serve the sidecar, or capture and add the debug to the view's response."""
+        path: str = getattr(request, "path", "")
+        if (
+            path.startswith(_SIDECAR_PREFIX)
+            and SnakeDebugChannel.SIDECAR in self._channels
+        ):
+            return self._serve_sidecar(path, request)
+        if not self._channels:
+            return self._get_response(request)
+
+        start = perf_counter()
+        at = datetime.now(UTC)  # the instant, taken where the wall clock starts
+        with capture_queries() as collector:
+            response = self._get_response(request)
+        report = collector.report().with_wall_ms((perf_counter() - start) * 1000)
+        report = report.with_index_hints(index_advice(report, self._config))
+        report = report.with_request(
+            RequestInfo(
+                method=getattr(request, "method", ""),
+                path=path,
+                status=int(getattr(response, "status_code", 0)),
+                at=at,
+            )
+        )
+
+        token = None
+        if SnakeDebugChannel.SIDECAR in self._channels:
+            token = new_token()
+            self._buffer.store(token, report)
+        # The `otel` channel: OUT of `plan_delivery`, which is a pure function that answers
+        # `(headers, envelope)` — two things that change the response, which a network send is not.
+        # Shared the same way `index_advice` is, and OUTSIDE the streaming `if` below: a
+        # `StreamingHttpResponse` has no body to inject a panel into, but it ran the same
+        # queries — dropping its trace would hide exactly the endpoints that stream because
+        # they are big.
+        export_report(report, self._channels)
+        delivery = plan_delivery(report, self._channels, token=token)
+
+        # A StreamingHttpResponse has no `.content` (accessing it raises): headers get added to it
+        # but the body is not touched — a streaming response is no place for a panel.
+        if not getattr(response, "streaming", False):
+            content_type = response.get("Content-Type", "")
+            new_body = transform_body(
+                response.content,
+                content_type,
+                delivery,
+                report,
+                self._channels,
+                self._config.language,
+                _csp_nonce_for(request, self._config),
+                token=token,
+            )
+            if new_body != response.content:
+                response.content = new_body
+                # Re-seal Content-Length with the REAL length of the already transformed body. If
+                # an inner middleware set it earlier (with the HTML WITHOUT the panel), it would be
+                # short and the server would truncate the body on the way out: the panel would be
+                # lost. Django's test client reads `.content` and does not catch it; a real server
+                # (runserver/gunicorn) does.
+                response["Content-Length"] = str(len(response.content))
+        for name, value in delivery.headers:
+            response[name] = value
+        return response
+
+    def _serve_sidecar(self, path: str, request: Any) -> Any:
+        """Serve `/__snake__/{token}`: the panel page, or the report as JSON if `Accept` asks.
+
+        Django is imported here, lazily. WHAT to answer is decided in `serve_sidecar`, shared with
+        the other two adapters; the 404 keeps its own class because that is the status Django reads
+        off the response type, not off an argument.
+        """
+        from django.http import (  # pyright: ignore[reportMissingImports]
+            HttpResponse,
+            HttpResponseNotFound,
+        )
+
+        page = serve_sidecar(
+            self._buffer.get(path[len(_SIDECAR_PREFIX) :]),
+            accept=_accept_of(request),
+            language=self._config.language,
+        )
+        if page.status == 404:
+            return HttpResponseNotFound(page.body)
+        return HttpResponse(page.body, content_type=page.content_type)
+
+
+# --- Django linker: it reads the NATIVE config (settings.DATABASES / settings.SNAKEORM) -------------
+# The user works AS ALWAYS (their lifelong `DATABASES`); the translation to `SnakeConnectionConfig`
+# is generic and lives in `contrib.config`. Here there is only what is specific to Django: reading
+# from `settings`.
+
+
+def _django_setting(name: str) -> dict[str, Any]:
+    """Read a constant off Django's `settings.py`, or `{}` if Django is not configured (tests)."""
+    try:
+        from django.conf import settings  # pyright: ignore[reportMissingImports]
+
+        return getattr(settings, name, {})
+    except Exception:
+        return {}
+
+
+def config_from_django(
+    *,
+    databases: Mapping[str, SnakeOrmDatabase] | None = None,
+    snakeorm: SnakeOrmSettings | None = None,
+) -> SnakeOrmConfig:
+    """Translate Django's NATIVE config (`settings.DATABASES` + `settings.SNAKEORM`) into the ROOT
+    config.
+
+    That way Django CONVERGES on the SAME `SnakeOrmConfig` that Flask/FastAPI build by hand: a
+    single normalised shape out of which sessions and the panel config come. The args are injected
+    in the tests; in a real app they fall back to `settings` (`{}` if Django is not configured).
+    """
+    raw_dbs = _django_setting("DATABASES") if databases is None else databases
+    raw_settings = _django_setting("SNAKEORM") if snakeorm is None else snakeorm
+    connections = {alias: connection_from_mapping(db) for alias, db in raw_dbs.items()}
+    return SnakeOrmConfig(
+        databases=connections,
+        debug=raw_settings.get("DEBUG", ""),
+        advise_ms=float(raw_settings.get("ADVISE_MS", DEFAULT_MIN_MS)),
+        language=SnakeDebugLanguage.coerce(raw_settings.get("LANG")),
+    )
+
+
+def django_session(
+    alias: str = "default",
+    *,
+    databases: Mapping[str, SnakeOrmDatabase] | None = None,
+) -> SnakeSession:
+    """Open a session reading Django's `DATABASES` (the `alias`, `"default"` by default).
+
+    A shortcut over `config_from_django(...).open(alias)`. `databases` is injected in the tests (the
+    project pattern) so global Django does not have to be configured; in a real app it falls back to
+    `settings.DATABASES`.
+    """
+    return config_from_django(databases=databases).open(alias)

snakeorm/contrib/sidecar.py

@@ -0,0 +1,44 @@
+"""The sidecar buffer: recent reports by token, served at `/__snake__/{token}`.
+
+A bounded ring buffer over `OrderedDict`: in a long-lived process it does not grow without limit (the footgun of Django's global `connection.queries`).
+"""
+
+from __future__ import annotations
+
+import secrets
+import threading
+from collections import OrderedDict
+
+from snakeorm.debug import DebugReport
+
+
+def new_token() -> str:
+    """A short, unguessable token to reference a report from the response."""
+    return secrets.token_urlsafe(9)
+
+
+class SidecarBuffer:
+    """Keep the last N reports by token, evicting the oldest one when it fills up.
+
+    With a lock: a WSGI server is multithreaded and `store()` does three non-atomic operations together on the `OrderedDict`.
+    """
+
+    __slots__ = ("_store", "_capacity", "_lock")
+
+    def __init__(self, capacity: int = 50) -> None:
+        self._store: OrderedDict[str, DebugReport] = OrderedDict()
+        self._capacity = capacity
+        self._lock = threading.Lock()
+
+    def store(self, token: str, report: DebugReport) -> None:
+        """Store a report under its token, evicting the oldest one if the capacity is exceeded."""
+        with self._lock:
+            self._store[token] = report
+            self._store.move_to_end(token)
+            while len(self._store) > self._capacity:
+                self._store.popitem(last=False)
+
+    def get(self, token: str) -> DebugReport | None:
+        """The report of that token, or `None` if it is gone (expired) or never existed."""
+        with self._lock:
+            return self._store.get(token)

snakeorm/contrib/wsgi.py

@@ -0,0 +1,176 @@
+"""WSGI adapter (Flask and any WSGI app): pure middleware that branches by `Content-Type` (the panel in HTML, `snakeorm` in JSON).
+
+It does not import Flask; it also serves the sidecar at `/__snake__/{token}`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from datetime import UTC, datetime
+from time import perf_counter
+
+from snakeorm.contrib.deliver import (
+    allowed_channels,
+    resolve_production,
+    index_advice,
+    plan_delivery,
+    serve_sidecar,
+    transform_body,
+)
+from snakeorm.contrib.sidecar import SidecarBuffer, new_token
+from snakeorm.debug import (
+    SnakeDebugChannel,
+    SnakeDebugConfig,
+    SnakeWebFramework,
+    capture_queries,
+    channels_from_env,
+    export_report,
+    RequestInfo,
+    warn_unimplemented,
+    warn_unsupported,
+)
+
+StartResponse = Callable[[str, list[tuple[str, str]]], object]
+WSGIApp = Callable[[dict[str, str], StartResponse], Iterable[bytes]]
+
+_SIDECAR_PREFIX = "/__snake__/"
+
+# WSGI writes the status as a LINE, so the two the sidecar can answer are spelled here.
+_STATUS_LINE = {200: "200 OK", 404: "404 Not Found"}
+
+
+class SnakeDebugWSGI:
+    """WSGI middleware that captures the SQL and delivers the debug per `SNAKE_ORM_DEBUG`."""
+
+    def __init__(
+        self,
+        app: WSGIApp,
+        *,
+        channels: frozenset[SnakeDebugChannel] | None = None,
+        production: bool | None = None,
+        buffer: SidecarBuffer | None = None,
+        config: SnakeDebugConfig | None = None,
+    ) -> None:
+        asked = channels_from_env() if channels is None else channels
+        self._app = app
+        self._config = config or SnakeDebugConfig.from_env()
+        # The config is resolved BEFORE the channels because it is one of the two places the
+        # environment can be declared, and `resolve_production` refuses rather than guessing when
+        # neither says anything and a risky channel is on.
+        self._channels = allowed_channels(
+            asked, production=resolve_production(production, self._config, asked)
+        )
+        self._buffer = buffer or SidecarBuffer()
+        warn_unsupported(self._channels, SnakeWebFramework.FLASK)
+        warn_unimplemented(self._channels)
+
+    def __call__(
+        self, environ: dict[str, str], start_response: StartResponse
+    ) -> Iterable[bytes]:
+        """WSGI entry point: it serves the sidecar, or captures and delivers the response's debug."""
+        path = environ.get("PATH_INFO", "")
+        if (
+            path.startswith(_SIDECAR_PREFIX)
+            and SnakeDebugChannel.SIDECAR in self._channels
+        ):
+            return self._serve_sidecar(path, environ, start_response)
+        if not self._channels:
+            return self._app(environ, start_response)
+        return self._capture_and_deliver(environ, start_response)
+
+    def _serve_sidecar(
+        self, path: str, environ: dict[str, str], start_response: StartResponse
+    ) -> Iterable[bytes]:
+        """Serve `/__snake__/{token}`: the panel page, or the report as JSON if `Accept` asks.
+
+        `HTTP_ACCEPT` is where a WSGI environ keeps the header; WHAT to answer with it is decided in
+        `serve_sidecar`, shared with the other two adapters.
+        """
+        page = serve_sidecar(
+            self._buffer.get(path[len(_SIDECAR_PREFIX) :]),
+            accept=environ.get("HTTP_ACCEPT", ""),
+            language=self._config.language,
+        )
+        start_response(
+            _STATUS_LINE[page.status],
+            [
+                ("Content-Type", page.content_type),
+                ("Content-Length", str(len(page.body))),
+            ],
+        )
+        return [page.body]
+
+    def _capture_and_deliver(
+        self, environ: dict[str, str], start_response: StartResponse
+    ) -> Iterable[bytes]:
+        """Wrap the app, buffer its response and deliver it with the debug added."""
+        captured_status = "200 OK"
+        captured_headers: list[tuple[str, str]] = []
+
+        def capture_start(status: str, headers: list[tuple[str, str]]) -> object:
+            nonlocal captured_status, captured_headers
+            captured_status = status
+            captured_headers = headers
+            return None
+
+        # Wall clock of the WHOLE request (app + DB + template): out of here comes the panel's
+        # "en app" (wall - DB). It is measured around the app, not around the panel injection
+        # (which is not part of the request).
+        start = perf_counter()
+        at = datetime.now(UTC)  # the instant, taken where the wall clock starts
+        with capture_queries() as collector:
+            body = b"".join(self._app(environ, capture_start))
+        report = collector.report().with_wall_ms((perf_counter() - start) * 1000)
+        report = report.with_index_hints(index_advice(report, self._config))
+        report = report.with_request(
+            RequestInfo(
+                method=environ.get("REQUEST_METHOD", ""),
+                path=environ.get("PATH_INFO", ""),
+                status=_status_code(captured_status),
+                at=at,
+            )
+        )
+
+        token = None
+        if SnakeDebugChannel.SIDECAR in self._channels:
+            token = new_token()
+            self._buffer.store(token, report)
+        # The `otel` channel: OUT of `plan_delivery`, which is a pure function that answers
+        # `(headers, envelope)` — two things that change the response, which a network send is not.
+        # Shared the same way `index_advice` is.
+        export_report(report, self._channels)
+        delivery = plan_delivery(report, self._channels, token=token)
+
+        content_type = next(
+            (value for key, value in captured_headers if key.lower() == "content-type"),
+            "",
+        )
+        new_body = transform_body(
+            body,
+            content_type,
+            delivery,
+            report,
+            self._channels,
+            self._config.language,
+            # WSGI has no per-request seam for this: `environ` carries no nonce convention, so the
+            # config's is the only one. It is FIXED for the process; a strict CSP wants one per
+            # response, which here means the app must repeat it in its own header.
+            self._config.csp_nonce,
+            token=token,
+        )
+        headers = [
+            (key, value)
+            for key, value in captured_headers
+            if key.lower() != "content-length"
+        ]
+        headers.extend(delivery.headers)
+        headers.append(("Content-Length", str(len(new_body))))
+
+        start_response(captured_status, headers)
+        return [new_body]
+
+
+def _status_code(status: str) -> int:
+    """The number out of a WSGI status line (`"404 Not Found"` -> `404`); 0 if it is not one."""
+    code, _, _ = status.partition(" ")
+    return int(code) if code.isdigit() else 0

snakeorm/core/__init__.py

@@ -0,0 +1 @@
+"""The ORM's core: the cross-cutting identity (base model, exceptions, signals, config)."""

snakeorm/core/config.py

@@ -0,0 +1,173 @@
+"""The one place that turns the environment (`.env` included) into a psycopg2 DSN; shared by CLI
+and tests.
+
+`find_dotenv(usecwd=True)`: a bare `load_dotenv()` searches from the calling file, which with the
+package installed would point at `site-packages`; anchoring it to the cwd is what the user expects.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+from dotenv import find_dotenv, load_dotenv
+
+from snakeorm.core.exceptions import SnakeConfigError
+
+# Each piece of the DSN: (environment variable, key in the DSN, devcontainer default).
+# The order fixes the order of the emitted DSN; it is the ONLY source of the names and defaults.
+_PARTS: tuple[tuple[str, str, str], ...] = (
+    ("DB_HOST", "host", "127.0.0.1"),
+    ("DB_PORT", "port", "5432"),
+    ("DB_USER", "user", "postgres"),
+    ("DB_PASSWORD", "password", "snakeorm_pass"),
+    ("DB_NAME", "dbname", "snakeorm_db"),
+)
+
+# Environment variables that describe the connection (derived from _PARTS, no duplication).
+DB_ENV_KEYS: tuple[str, ...] = tuple(env_key for env_key, _, _ in _PARTS)
+
+
+_SCHEME = re.compile(r"^([A-Za-z][A-Za-z0-9+.-]*)://")
+"""The RFC 3986 shape of a scheme, and a regex rather than `split("://", 1)`.
+
+A password containing `://` would otherwise be read as the scheme — the same failure this guard is
+about, arriving through a value nobody thinks of as configuration."""
+
+
+def load_env() -> None:
+    """Loads the cwd's `.env` (or an ancestor's), without stomping on variables already present
+    (the environment wins)."""
+    path = find_dotenv(
+        usecwd=True
+    )  # empty string if there is no .env in the cwd's tree
+    if path:
+        load_dotenv(path)
+
+
+def dsn_from_env(*, connect_timeout: int | None = None) -> str:
+    """Builds the psycopg2 DSN from `.env`/environment, with the devcontainer defaults.
+
+    `connect_timeout` adds the parameter of the same name when given (the tests lower it so they do
+    not hang).
+    """
+    load_env()
+    parts = [
+        f"{dsn_key}={os.environ.get(env_key, default)}"
+        for env_key, dsn_key, default in _PARTS
+    ]
+    if connect_timeout is not None:
+        parts.append(f"connect_timeout={connect_timeout}")
+    return " ".join(parts)
+
+
+# -- NAMED connections (multi-DB) ------------------------------------------------------------
+# Here we only resolve WHICH DSN belongs to each name; `snake_session(...)` assembles the driver.
+# `default` resolves as always (a single-DB project changes nothing); the rest through
+# `SNAKEORM_DSN_<NAME>` in uppercase.
+
+DEFAULT_DATABASE = "default"
+
+
+def _env_key(database: str) -> str:
+    """The environment variable that declares a named connection's DSN."""
+    return f"SNAKEORM_DSN_{database.upper()}"
+
+
+def dsn_for(database: str = DEFAULT_DATABASE) -> str:
+    """DSN of a connection BY NAME.
+
+    `default` falls into the usual resolution; any other name is looked up in
+    `SNAKEORM_DSN_<NAME>`, and if it is missing we say EXACTLY which one: resolving blindly ends up
+    connecting to the wrong DB.
+    """
+    if database == DEFAULT_DATABASE:
+        return dsn_from_env()
+    load_env()
+    value = os.environ.get(_env_key(database))
+    if not value:
+        raise SnakeConfigError(
+            f"There is no DSN for connection '{database}': set the environment variable "
+            f"{_env_key(database)} (or put it in the .env). Connection '{DEFAULT_DATABASE}' is the "
+            f"only one resolved from the DB_* pieces."
+        )
+    return value
+
+
+_BACKEND_DEFAULT_KEY = "DB_BACKEND"
+"""The engine of the DEFAULT connection, beside the `DB_*` pieces that build its DSN.
+
+The name is not invented here: `frameworks/shared/config.py` already reads it, because the demos
+needed to pick an engine and the ORM offered nowhere to say so. That is the asymmetry this closes —
+the convention existed, it just lived in the showcase instead of the library.
+"""
+
+_BACKEND_NAMES: dict[str, str] = {
+    # DSN scheme -> engine. It is a DECLARATION, not a guess: whoever writes `mysql://` said which
+    # engine they meant, and reading it is not divination.
+    "postgresql": "postgres",
+    "postgres": "postgres",
+    "mysql": "mysql",
+    "mariadb": "mysql",
+    "sqlite": "sqlite",
+}
+
+_KNOWN_BACKENDS = ("postgres", "mysql", "sqlite")
+
+
+def _backend_key(database: str) -> str:
+    """The environment variable that declares a named connection's ENGINE."""
+    return f"SNAKEORM_BACKEND_{database.upper()}"
+
+
+def backend_name_for(database: str = DEFAULT_DATABASE) -> str:
+    """The engine of a connection BY NAME, as a plain string. It is READ, never guessed.
+
+    1. `SNAKEORM_BACKEND_<NAME>` — or `DB_BACKEND` for the default connection — which always wins:
+       saying it out loud beats inferring it.
+    2. The DSN's own scheme (`postgresql://`, `mysql://`, `sqlite://`).
+    3. Postgres, when the DSN carries NO scheme. That is a derivation and not a fallback: a DSN
+       shaped `host=x dbname=y` is libpq keyword syntax, which no other engine speaks.
+
+    A value that is not one of the three is REFUSED naming what it read. The demos already paid for
+    the alternative and wrote it down: a `postgress` with one extra `s` brought the app up on SQLite,
+    talking to the wrong database without a word.
+
+    It returns a `str` and not a `SnakeBackend` on purpose: `connection.py` — where that enum lives —
+    sits ABOVE this module and pulls in every driver and dialect. Importing it from here would close
+    a circle between the layers, and the acyclicity net says so.
+    """
+    load_env()
+    key = (
+        _BACKEND_DEFAULT_KEY if database == DEFAULT_DATABASE else _backend_key(database)
+    )
+    declared = os.environ.get(key, "").strip().lower()
+    if declared:
+        if declared not in _KNOWN_BACKENDS:
+            raise SnakeConfigError(
+                f"{key}='{declared}' is not a known engine. The three are: "
+                f"{', '.join(_KNOWN_BACKENDS)}. It is refused instead of falling back, because "
+                f"falling back means talking to another database without saying so."
+            )
+        return declared
+    dsn = dsn_for(database)
+    match = _SCHEME.match(dsn)
+    if match is None:
+        # NO scheme is the libpq keyword/value form (`host=x dbname=y`), which is Postgres and is
+        # not an error. This is the case the fallback existed for.
+        return "postgres"
+    scheme = match.group(1).lower()
+    if scheme not in _BACKEND_NAMES:
+        # And an UNKNOWN scheme is refused, for the reason written fifteen lines above about
+        # `DB_BACKEND`: falling back means talking to another database without saying so. The old
+        # `.get(scheme, "postgres")` could not tell the two cases apart, so `sqlite3://` —the name
+        # of the Python module, and an alias `contrib/config.py` accepts elsewhere— came out as
+        # Postgres. Same class of typo, two opposite treatments, in the one function that decides
+        # which engine you are talking to.
+        raise SnakeConfigError(
+            f"The DSN of '{database}' starts with '{scheme}://', which is not an engine this ORM "
+            f"knows. The schemes it reads are: {', '.join(sorted(_BACKEND_NAMES))}. A DSN with no "
+            f"scheme at all is the libpq keyword/value form and resolves to postgres; a scheme it "
+            f"does not recognise is refused rather than guessed at."
+        )
+    return _BACKEND_NAMES[scheme]