snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/connection.py

@@ -0,0 +1,228 @@
+"""CENTRALISED connection config: the object that crowns any framework's connection config.
+
+Django feeds it by translating its `DATABASES` (`contrib.django`); Flask, FastAPI and anything else
+without a convention build THIS directly and open it with `contrib.open_session`. The `backend`
+picks driver AND dialect PAIRED — the user cannot put a `SQLiteDriver` together with a
+`PostgresDialect` because they never pick the two pieces separately. Each engine's heavy deps
+(`psycopg2`, `pymysql`) stay OPTIONAL: every driver imports them inside its `connect()`, not when the
+class is defined, so importing the driver here does not drag them in.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from urllib.parse import urlsplit
+
+from snakeorm.dialects.matrix import flavour_of
+from snakeorm.dialects import MySQLDialect, PostgresDialect, SQLiteDialect
+from snakeorm.registry import SnakeRegistry
+from snakeorm.dialects.base import SnakeDialect
+from snakeorm.drivers import PyMySQLDriver, SQLiteDriver
+from snakeorm.drivers.asyncbase import AsyncDriver
+from snakeorm.drivers.asyncpsycopg import AsyncPsycopgDriver
+from snakeorm.drivers.asyncpymysql import AsyncPyMySQLDriver
+from snakeorm.drivers.asyncsqlite import AsyncSQLiteDriver
+from snakeorm.drivers.psycopg import PsycopgDriver, with_utc_timezone
+from snakeorm.drivers.base import SnakeDriver
+from snakeorm.session import AsyncSession, SnakeSession
+
+
+class SnakeBackend(Enum):
+    """The engine: it picks driver (how it EXECUTES) and dialect (how it WRITES SQL) at once."""
+
+    POSTGRES = "postgres"
+    SQLITE = "sqlite"
+    MYSQL = "mysql"
+
+    @property
+    def db_system_name(self) -> str:
+        """What OpenTelemetry calls this engine (`db.system.name`), for the `otel` debug channel.
+
+        It answers HERE because this enum is the one place engine identity is written down. The
+        alternatives are all second spellings of the same fact: the driver's class is hidden the
+        moment a pool or a timeout decorator wraps it, and the SQL's placeholders say nothing about
+        MariaDB.
+
+        `mariadb` IS a value of its own in the convention and not an alias of `mysql`. SnakeORM
+        reaches both through PyMySQL and cannot tell them apart without asking the server for its
+        banner, so it reports `mysql` and leaves the correction to whoever knows: the capture driver
+        takes the name as an argument.
+        """
+        return _DB_SYSTEM_NAMES[self]
+
+
+# The engine's OpenTelemetry name, per member. A dict and not a second enum value so the member's
+# own value (`postgres`, what a user writes in `ENGINE`) stays the public spelling: they are two
+# different vocabularies for the same engine and merging them would break one of the two.
+_DB_SYSTEM_NAMES: dict[SnakeBackend, str] = {
+    SnakeBackend.POSTGRES: "postgresql",
+    SnakeBackend.SQLITE: "sqlite",
+    SnakeBackend.MYSQL: "mysql",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeConnectionConfig:
+    """Everything defining ONE connection, in a typed object (frozen: not overwritten mid-request).
+
+    `name` is the database (Postgres/MySQL) or, for SQLite, whatever it calls a database: a file
+    path, `:memory:`, or a `file:` URI — the last being the only one that gives several connections
+    ONE in-memory database. The remaining pieces only apply to the networked engines; SQLite ignores
+    them.
+    """
+
+    backend: SnakeBackend
+    name: str
+    host: str = "localhost"
+    port: str = ""
+    user: str = ""
+    password: str = ""
+    dsn: str | None = None
+    """An already-written DSN, for when the connection comes as one rather than in pieces.
+
+    It exists so that ONE single piece pairs driver and dialect. `snake_session(name)` resolves the
+    connection through its DSN — multi-DB by environment variable — and used to assemble the pair by
+    hand, which left two places where somebody could join a driver to another engine's dialect. That
+    path now comes through here, and the pairing goes on living in a single method.
+    """
+
+    @classmethod
+    def from_dsn(cls, dsn: str, backend: SnakeBackend) -> SnakeConnectionConfig:
+        """Takes a DSN apart into the pieces THAT engine's driver actually wants.
+
+        Each one asks for the connection in its own shape and there is no common denominator:
+        psycopg reads a DSN string, SQLite wants a filesystem PATH, and PyMySQL wants loose keyword
+        arguments. So a DSN has to be translated, and it is translated HERE — beside
+        `driver_and_dialect` — because this class exists so that pairing a driver with another
+        engine's dialect is not expressible. A second place doing the same translation would be a
+        second place to get it wrong.
+
+        It was `snake_session` that needed it, and needed it badly: it handed the connection's ALIAS
+        over as `name`, which Postgres ignores (its DSN wins) and SQLite reads as the path. So
+        `snake_session("reports")` created a file literally called `reports` in the working
+        directory instead of opening the one the DSN named — and a test that only checked the
+        dialect passed over it.
+        """
+        if backend is SnakeBackend.POSTGRES:
+            # psycopg parses its own DSN, in either form (URL or libpq keywords), so it travels whole.
+            return cls(backend=backend, name="", dsn=dsn)
+
+        parsed = urlsplit(dsn)
+        if backend is SnakeBackend.SQLITE:
+            # The THIRD slash is the URL's separator, so exactly one comes off: `sqlite:///tmp/x.db`
+            # is the relative `tmp/x.db`, `sqlite:////tmp/x.db` is `/tmp/x.db`. SQLAlchemy's rule.
+            # A relative path STAYS relative — resolving it here would be guessing (bug #38).
+            # `:memory:` arrives in the authority, where no slash rule applies. The query string is
+            # kept only for a `file:` URI, which is the half of #37 that survived fixing the driver.
+            database = f"{parsed.netloc}{parsed.path}"
+            if database.startswith("/"):
+                database = database[1:]
+            if database.startswith("file:") and parsed.query:
+                database = f"{database}?{parsed.query}"
+            return cls(backend=backend, name=database or ":memory:")
+        return cls(
+            backend=backend,
+            name=parsed.path.lstrip("/"),
+            host=parsed.hostname or "localhost",
+            port=str(parsed.port) if parsed.port else "",
+            user=parsed.username or "",
+            password=parsed.password or "",
+        )
+
+    def driver_and_dialect(self) -> tuple[SnakeDriver, SnakeDialect]:
+        """Builds driver and dialect PAIRED according to `backend` (impossible to unpair them)."""
+        if self.backend is SnakeBackend.SQLITE:
+            return SQLiteDriver.connect(self.name), SQLiteDialect()
+        if self.backend is SnakeBackend.POSTGRES:
+            return PsycopgDriver.connect(self.postgres_dsn()), PostgresDialect()
+        driver = PyMySQLDriver.connect(**self._mysql_kwargs())
+        return driver, MySQLDialect(flavour_of(driver.server_version()))
+
+    def open(
+        self,
+        wrap: Callable[[SnakeDriver], SnakeDriver] | None = None,
+        *,
+        model_registry: SnakeRegistry | None = None,
+    ) -> SnakeSession:
+        """Assembles the whole session (driver + dialect paired) in a single call.
+
+        `wrap` wraps the driver before the session is assembled: the seam for `CaptureDriver` (so the
+        debug panel sees the SQL), pooling, logging or timeout. It is passed FROM outside — this
+        module does not import it — so the central config stays uncoupled from the debug subsystem
+        and from the decorators.
+        """
+        driver, dialect = self.driver_and_dialect()
+        if wrap is not None:
+            driver = wrap(driver)
+        return SnakeSession(driver, dialect, model_registry=model_registry)
+
+    async def async_driver_and_dialect(self) -> tuple[AsyncDriver, SnakeDialect]:
+        """The async pair PAIRED according to `backend`, just like its synchronous sibling.
+
+        It is `async` because opening can wait: `AsyncPsycopgDriver.connect` is. Reusing the
+        synchronous method was no good, hence there are two: `driver_and_dialect` connects eagerly.
+        """
+        if self.backend is SnakeBackend.SQLITE:
+            return await AsyncSQLiteDriver.connect(self.name), SQLiteDialect()
+        if self.backend is SnakeBackend.POSTGRES:
+            return await AsyncPsycopgDriver.connect(self.postgres_dsn()), (
+                PostgresDialect()
+            )
+        driver = await AsyncPyMySQLDriver.connect(**self._mysql_kwargs())
+        return driver, MySQLDialect(flavour_of(await driver.server_version()))
+
+    async def open_async(
+        self,
+        wrap: Callable[[AsyncDriver], AsyncDriver] | None = None,
+        *,
+        model_registry: SnakeRegistry | None = None,
+    ) -> AsyncSession:
+        """Assembles the whole ASYNCHRONOUS session (driver + dialect paired) in one call.
+
+        Without this, the async user picked driver and dialect separately — which is exactly what this
+        module exists to prevent: nobody can put a `SQLiteDriver` together with a `PostgresDialect`
+        because they never choose the two pieces.
+
+        `wrap` wraps the driver before the session is assembled, as on the synchronous path.
+        """
+        driver, dialect = await self.async_driver_and_dialect()
+        if wrap is not None:
+            driver = wrap(driver)
+        return AsyncSession(driver, dialect, model_registry=model_registry)
+
+    def postgres_dsn(self) -> str:
+        """psycopg's DSN: the declared one if there is one, or built from the pieces.
+
+        It only includes what was declared (no empty pieces). The UTC zone is pinned the same way on
+        both paths: that is what makes opening the database to look at a date show the instant that
+        was stored, and not the server's local time.
+        """
+        if self.dsn is not None:
+            return with_utc_timezone(self.dsn)
+        parts = [f"host={self.host}", f"dbname={self.name}"]
+        if self.port:
+            parts.append(f"port={self.port}")
+        if self.user:
+            parts.append(f"user={self.user}")
+        if self.password:
+            parts.append(f"password={self.password}")
+        # The session's zone, pinned in the DSN itself: `TIMESTAMPTZ` stores the instant but SHOWS
+        # it in the session's zone, so without this, opening the database to check the dates shows
+        # the server's local time and the look tells you nothing.
+        return with_utc_timezone(" ".join(parts))
+
+    def _mysql_kwargs(self) -> dict[str, object]:
+        """Kwargs for `PyMySQLDriver.connect` (its signature is not a DSN string, but loose args)."""
+        kwargs: dict[str, object] = {"host": self.host, "database": self.name}
+        if self.port:
+            kwargs["port"] = int(self.port)
+        if self.user:
+            kwargs["user"] = self.user
+        if self.password:
+            kwargs["password"] = self.password
+        # The MySQL equivalent, which has no libpq `options`. Same guarantee by another mechanism:
+        # what you see when querying is what was stored.
+        kwargs["init_command"] = "SET time_zone = '+00:00'"
+        return kwargs

snakeorm/contrib/__init__.py

@@ -0,0 +1,17 @@
+"""Optional web adapters: they CONSUME the `snakeorm.debug` kernel, they do not define it (a thin edge, hexagonal architecture).
+
+None of them imports its framework at module level, so they import and test without FastAPI/Flask/Django installed.
+"""
+
+from snakeorm.contrib.asgi import SnakeDebugASGI as SnakeDebugASGI
+from snakeorm.contrib.config import SnakeOrmConfig as SnakeOrmConfig
+from snakeorm.debug import SnakeDebugLanguage as SnakeDebugLanguage
+from snakeorm.contrib.config import SnakeOrmSettings as SnakeOrmSettings
+from snakeorm.contrib.config import (
+    debug_config_from_mapping as debug_config_from_mapping,
+)
+from snakeorm.contrib.config import open_session as open_session
+from snakeorm.contrib.config import open_session_async as open_session_async
+from snakeorm.contrib.django import SnakeDebugMiddleware as SnakeDebugMiddleware
+from snakeorm.contrib.sidecar import SidecarBuffer as SidecarBuffer
+from snakeorm.contrib.wsgi import SnakeDebugWSGI as SnakeDebugWSGI

snakeorm/contrib/asgi.py

@@ -0,0 +1,192 @@
+"""ASGI adapter (FastAPI/Starlette): pure ASGI middleware that captures per request and delivers the debug by channel.
+
+It does not import FastAPI, it serves the sidecar at `/__snake__/{token}` itself, and the SSR stays a no-op unless the app returns HTML.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, MutableMapping
+from datetime import UTC, datetime
+from time import perf_counter
+from typing import Any
+
+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,
+)
+
+Scope = MutableMapping[str, Any]
+Message = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[Message]]
+Send = Callable[[Message], Awaitable[None]]
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+_SIDECAR_PREFIX = "/__snake__/"
+
+
+class SnakeDebugASGI:
+    """ASGI middleware that captures the SQL and delivers the debug per `SNAKE_ORM_DEBUG`."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        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.FASTAPI)
+        warn_unimplemented(self._channels)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """ASGI entry point: it serves the sidecar, or captures and delivers the response's debug."""
+        if scope["type"] != "http" or not self._channels:
+            await self._app(scope, receive, send)
+            return
+        path: str = scope["path"]
+        if (
+            path.startswith(_SIDECAR_PREFIX)
+            and SnakeDebugChannel.SIDECAR in self._channels
+        ):
+            await self._serve_sidecar(path, scope, send)
+            return
+        await self._capture_and_deliver(scope, receive, send)
+
+    async def _serve_sidecar(self, path: str, scope: Scope, send: Send) -> None:
+        """Serve `/__snake__/{token}`: the panel page, or the report as JSON if `Accept` asks.
+
+        An ASGI scope keeps the headers as bytes pairs; WHAT to answer with them is decided in
+        `serve_sidecar`, shared with the other two adapters.
+        """
+        page = serve_sidecar(
+            self._buffer.get(path[len(_SIDECAR_PREFIX) :]),
+            accept=_header(list(scope.get("headers", [])), b"accept"),
+            language=self._config.language,
+        )
+        await _send_response(send, page.status, page.content_type, page.body)
+
+    async def _capture_and_deliver(
+        self, scope: Scope, receive: Receive, send: Send
+    ) -> None:
+        """Wrap the app in a scope, buffer its response and deliver it with the debug added."""
+        start: Message = {}
+        body = bytearray()
+
+        async def capture_send(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                start.update(message)
+            elif message["type"] == "http.response.body":
+                body.extend(message.get("body", b""))
+
+        t0 = perf_counter()
+        at = datetime.now(UTC)  # the instant, taken where the wall clock starts
+        with capture_queries() as collector:
+            await self._app(scope, receive, capture_send)
+        report = collector.report().with_wall_ms((perf_counter() - t0) * 1000)
+        report = report.with_index_hints(index_advice(report, self._config))
+        report = report.with_request(
+            RequestInfo(
+                method=scope.get("method", ""),
+                path=scope.get("path", ""),
+                status=int(start.get("status", 200)),
+                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)
+
+        headers: list[tuple[bytes, bytes]] = list(start.get("headers", []))
+        content_type = _header(headers, b"content-type")
+        new_body = transform_body(
+            bytes(body),
+            content_type,
+            delivery,
+            report,
+            self._channels,
+            self._config.language,
+            # ASGI has no per-request seam for this: no spec field and no framework convention
+            # holds a nonce, so the config's is the only one. FIXED for the process.
+            self._config.csp_nonce,
+            token=token,
+        )
+        for name, value in delivery.headers:
+            headers.append((name.encode("latin1"), value.encode("latin1")))
+        headers = _replace(headers, b"content-length", str(len(new_body)).encode())
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": start.get("status", 200),
+                "headers": headers,
+            }
+        )
+        await send({"type": "http.response.body", "body": new_body})
+
+
+def _header(headers: list[tuple[bytes, bytes]], name: bytes) -> str:
+    """The (decoded) value of a header by name, or an empty string if it is not there."""
+    for key, value in headers:
+        if key.lower() == name:
+            return value.decode("latin1")
+    return ""
+
+
+def _replace(
+    headers: list[tuple[bytes, bytes]], name: bytes, value: bytes
+) -> list[tuple[bytes, bytes]]:
+    """Return the headers with `name` set to `value` (removing any previous value)."""
+    kept = [(key, val) for key, val in headers if key.lower() != name]
+    kept.append((name, value))
+    return kept
+
+
+async def _send_response(
+    send: Send, status: int, content_type: str, body: bytes
+) -> None:
+    """Emit a complete ASGI response (start + body) in a single body."""
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": [
+                (b"content-type", content_type.encode("latin1")),
+                (b"content-length", str(len(body)).encode()),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})