snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/drivers/pymysql.py

@@ -0,0 +1,176 @@
+"""PyMySQLDriver: runs SQL against MySQL/MariaDB with PyMySQL (synchronous). PyMySQL (pure Python) so
+no C toolchain is required; whoever wants `mysqlclient` plugs it in here without touching the dialect
+(same `%s`). A THIN adapter like `PsycopgDriver`: it only runs the compiled `(sql, params)`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from typing import Any, Protocol, cast
+
+from snakeorm.drivers.failures import translating
+from snakeorm.drivers.savepoints import quote_savepoint
+
+from snakeorm.sql.adapt import adapt_params
+
+_QUOTE = "`"
+"""The character THIS engine quotes an identifier with.
+
+MySQL and MariaDB reject a double-quoted identifier unless `ANSI_QUOTES` is on, so a shared helper
+that always wrote a double quote turned every `SAVEPOINT` into `ERROR 1064` here. The RULE about
+what a valid name is, is shared; the quoting character is the engine's own grammar.
+"""
+
+
+class _Cursor(Protocol):
+    """The minimal DBAPI cursor the driver needs."""
+
+    @property
+    def rowcount(self) -> int: ...
+    @property
+    def lastrowid(self) -> int: ...
+    @translating
+    # `| None` is how these two libraries spell NO PARAMETERS, and it is not the same as an
+    # empty sequence: given `()` they re-read the SQL as a format template, so a literal `%` —
+    # every DDL statement the migration runner emits — dies before reaching the server. The
+    # Protocol has to admit it or the drivers cannot say it.
+    def execute(self, sql: str, params: Sequence[object] | None) -> object: ...
+    # `Sequence` and not `list`, because PyMySQL hands back a TUPLE of tuples. Declaring `list`
+    # here was a claim about somebody else's library that nothing ever measured, and mypy believed
+    # it: `fetch_all` promised a list and returned a tuple on this engine alone.
+    def fetchall(self) -> Sequence[tuple[object, ...]]: ...
+    def fetchmany(self, size: int) -> Sequence[tuple[object, ...]]: ...
+    def close(self) -> None: ...
+
+
+class _Connection(Protocol):
+    """The minimal DBAPI connection the driver needs."""
+
+    def cursor(self, cursor_class: object = ...) -> _Cursor: ...
+    @translating
+    def commit(self) -> None: ...
+    def rollback(self) -> None: ...
+    def close(self) -> None: ...
+
+
+class PyMySQLDriver:
+    """Synchronous driver over PyMySQL. Implements the SnakeDriver Protocol."""
+
+    def __init__(self, connection: _Connection) -> None:
+        self._connection = connection
+        self._last_insert_id = 0  # the id generated by the last INSERT (MySQL has no RETURNING; MariaDB does)
+
+    def server_version(self) -> str:
+        """What the server calls itself: `11.8.8-MariaDB-ubu2404`, `8.0.46`.
+
+        Empty if it does not answer: a flavour read wrong is worse than none.
+        """
+        try:
+            cursor = self._connection.cursor()
+            cursor.execute("SELECT VERSION()", ())
+            rows = cursor.fetchall()
+            return str(rows[0][0]) if rows else ""
+        except Exception:
+            return ""
+
+    @classmethod
+    def adopt(cls, connection: object) -> PyMySQLDriver:
+        """Wraps a raw PyMySQL connection, adapting it to our minimal DBAPI (the edge)."""
+        return cls(cast("_Connection", connection))
+
+    @classmethod
+    def connect(cls, **kwargs: Any) -> PyMySQLDriver:
+        """Opens a PyMySQL connection with the given kwargs (host, user, password, database, port...).
+        MySQL uses arguments, not a one-piece DSN. Lazy import: whoever only generates SQL does not need PyMySQL.
+        """
+        import pymysql
+
+        return cls.adopt(pymysql.connect(**kwargs))
+
+    @translating
+    def fetch_all(self, sql: str, params: Sequence[object]) -> list[tuple[object, ...]]:
+        """Runs a query and returns all of its rows, closing the cursor."""
+        cursor = self._connection.cursor()
+        try:
+            cursor.execute(
+                sql, adapt_params(params, native_arrays=False, percent_formatting=True)
+            )
+            # `list(...)` and not the cursor's own answer: the Protocol promises a list and PyMySQL
+            # gives a tuple. Everything downstream only iterates, so it went unnoticed — until
+            # somebody compared the result to one.
+            return list(cursor.fetchall())
+        finally:
+            cursor.close()
+
+    def fetch_iter(
+        self, sql: str, params: Sequence[object], *, chunk: int = 1000
+    ) -> Iterator[tuple[object, ...]]:
+        """Yields the rows in chunks using PyMySQL's UNBUFFERED cursor (`SSCursor`).
+
+        `SSCursor` is the MySQL equivalent of Postgres's named cursor: the result stays on the
+        server and arrives on demand. With the normal cursor, PyMySQL pulls EVERYTHING to the
+        client on execute, and `fetchmany` would only be slicing a list that is already fully in
+        memory.
+
+        Its price, and you have to know it: while the unbuffered cursor is alive, that connection
+        cannot fire another query. That is why the cursor is closed once the iteration runs out.
+        """
+        import pymysql.cursors
+
+        cursor = self._connection.cursor(pymysql.cursors.SSCursor)
+        try:
+            cursor.execute(
+                sql, adapt_params(params, native_arrays=False, percent_formatting=True)
+            )
+            while True:
+                rows = cursor.fetchmany(chunk)
+                if not rows:
+                    return
+                yield from rows
+        finally:
+            cursor.close()
+
+    @translating
+    def execute(self, sql: str, params: Sequence[object]) -> int:
+        """Runs a statement fetching no rows and returns the rowcount.
+        It stores `lastrowid` (read BEFORE closing the cursor): on MySQL, which has no RETURNING, that is the only way to recover the generated PK.
+        """
+        cursor = self._connection.cursor()
+        try:
+            cursor.execute(
+                sql, adapt_params(params, native_arrays=False, percent_formatting=True)
+            )
+            self._last_insert_id = cursor.lastrowid
+            return cursor.rowcount
+        finally:
+            cursor.close()
+
+    @property
+    def last_insert_id(self) -> int:
+        """The autoincrement id of the last INSERT. The session uses it where there is no RETURNING."""
+        return self._last_insert_id
+
+    @translating
+    def commit(self) -> None:
+        """Commits the transaction in progress."""
+        self._connection.commit()
+
+    def rollback(self) -> None:
+        """Rolls back the transaction in progress."""
+        self._connection.rollback()
+
+    def savepoint(self, name: str) -> None:
+        """Emits `SAVEPOINT \\`n\\``. MySQL supports savepoints; the name is quoted with backticks."""
+        self.execute(f"SAVEPOINT {quote_savepoint(name, quote=_QUOTE)}", ())
+
+    def release_savepoint(self, name: str) -> None:
+        """Emits `RELEASE SAVEPOINT \\`n\\``."""
+        self.execute(f"RELEASE SAVEPOINT {quote_savepoint(name, quote=_QUOTE)}", ())
+
+    def rollback_to_savepoint(self, name: str) -> None:
+        """Emits `ROLLBACK TO SAVEPOINT \\`n\\``."""
+        self.execute(f"ROLLBACK TO SAVEPOINT {quote_savepoint(name, quote=_QUOTE)}", ())
+
+    def close(self) -> None:
+        """Closes the connection."""
+        self._connection.close()

snakeorm/drivers/savepoints.py

@@ -0,0 +1,46 @@
+"""How a savepoint NAME is written, once, for every driver.
+
+What is shared is the RULE — what counts as a valid name — and NOT the quoting character. MySQL and
+MariaDB reject a double-quoted identifier unless `ANSI_QUOTES` is on, so `SAVEPOINT "sp1"` comes
+back as `ERROR 1064` — measured, not reasoned about. The quote is engine grammar; the rule is not.
+Each driver answers with its own character and there is no default, for the same reason
+`adapt_params` has none: a new driver has to DECIDE.
+
+The names the ORM itself generates come from `SnakeSession.savepoint` (`f"sp{depth}"`), so no
+caller-supplied name reaches here through the public API.
+
+It lives with the DRIVERS and not with the dialects, even though it is grammar. A driver has no
+dialect and never has had — `TimeoutDriver` receives one as a call argument for exactly that reason —
+so putting it there would mean handing every driver a dialect to write one pair of quotes.
+"""
+
+from __future__ import annotations
+
+import re
+
+_PLAIN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+"""A plain ASCII identifier, which is all the ORM ever generates.
+
+Stricter than the `isalnum()` two of the four copies used, and deliberately: a name starting with a
+digit and a non-ASCII one both pass that check and neither is something this ORM produces.
+"""
+
+
+def quote_savepoint(name: str, *, quote: str) -> str:
+    """The name, quoted for a `SAVEPOINT` statement with THIS engine's character, or a refusal.
+
+    It REFUSES rather than escaping, and that is the decision. The name is always generated by the
+    session, so anything that is not a plain identifier is a bug in whoever called — and escaping a
+    bug is how it ends up written into the database instead of reported.
+
+    `quote` is keyword-only and has no default: a driver has to say which character its engine
+    accepts. A default of `"` looked harmless and is what broke MySQL, where an identifier in double
+    quotes is a syntax error unless `ANSI_QUOTES` is set.
+    """
+    if not _PLAIN.match(name):
+        raise ValueError(
+            f"Invalid savepoint name: {name!r}. The ORM generates these itself, so a name it does "
+            f"not recognise means somebody called the driver directly with one of their own. It "
+            f"must be a plain ASCII identifier."
+        )
+    return f"{quote}{name}{quote}"

snakeorm/drivers/sqlite.py

@@ -0,0 +1,170 @@
+"""SQLite driver over the stdlib's `sqlite3`. It mirrors `PsycopgDriver` (same Protocol) except for
+two connector decisions that bite in silence:
+
+1. `PRAGMA foreign_keys = ON`: SQLite ignores FKs by default; emitting FKs that are not enforced is
+   exactly the silent failure this project hunts down.
+2. `isolation_level = None` + a lazy `BEGIN` issued by the driver ITSELF. sqlite3's "magic" handling
+   does not wrap DDL (it breaks migrations); with `None` it stays in autocommit and `rollback()`
+   undoes nothing. The driver opens the transaction on the first statement and closes it on
+   commit/rollback (like psycopg2), so the DDL goes inside the transaction, which is what
+   `supports_transactional_ddl=True` promises.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from snakeorm.drivers.failures import translating
+from snakeorm.drivers.savepoints import quote_savepoint
+
+from snakeorm.core.exceptions import SnakeConfigError
+from snakeorm.sql.adapt import adapt_params
+
+_QUOTE = '"'
+"""The character THIS engine quotes an identifier with.
+
+MySQL and MariaDB reject a double-quoted identifier unless `ANSI_QUOTES` is on, so a shared helper
+that always wrote a double quote turned every `SAVEPOINT` into `ERROR 1064` here. The RULE about
+what a valid name is, is shared; the quoting character is the engine's own grammar.
+"""
+
+
+class SQLiteDriver:
+    """A connection to SQLite. A file, or `:memory:` for an ephemeral database (tests).
+    `sqlite3` is imported INSIDE `connect` (like psycopg2), so it is not loaded on every `import snakeorm`.
+    """
+
+    def __init__(self, connection: Any) -> None:
+        self._connection = connection
+        self._in_tx = False  # is there a transaction opened by our lazy BEGIN?
+
+    def _ensure_tx(self) -> None:
+        """Opens a transaction if there is none, before the first statement (like psycopg2), so the
+        session sees a coherent snapshot and the rollback has something to undo.
+        """
+        if not self._in_tx:
+            self._connection.execute("BEGIN")
+            self._in_tx = True
+
+    @classmethod
+    def connect(cls, database: str) -> SQLiteDriver:
+        """Opens the database and leaves the connector in a state with no surprises.
+
+        `database` is a NAME, not a DSN: a path, `:memory:`, or a `file:` URI. A `sqlite:` scheme
+        RAISES, because stripping it here would make this a SECOND place translating a DSN, and one
+        string would name two databases, silently (bug #38).
+
+        `uri=True` is passed unconditionally, and that is measured rather than assumed. SQLite reads
+        a connection string as a URI only when it begins with `file:`; everything else is a literal
+        filename, question marks included (`weird?name.db` is still that file). So there is no flag
+        and no heuristic about what the caller meant.
+
+        WITHOUT IT, `file:cache?mode=memory&cache=shared` — the standard spelling of a shared
+        in-memory database — is taken as a FILENAME, and SQLite creates a file called exactly that.
+        It does not fail; it opens the wrong database and carries on, and everything downstream
+        works because it IS a real database. With it, a MALFORMED `file:` DSN raises instead of
+        quietly creating a file named after the mistake.
+        """
+        import sqlite3
+
+        # On the SCHEME, not a prefix match: `sqlite_backup.db` is an ordinary filename.
+        if database.startswith("sqlite:"):
+            raise SnakeConfigError(
+                f"SQLiteDriver.connect() takes a database name, not a DSN, and got {database!r}. "
+                "A DSN is translated in ONE place: "
+                "SnakeConnectionConfig.from_dsn(dsn, SnakeBackend.SQLITE), whose `.name` is what "
+                "belongs here. Two places translating is how one string ends up naming two "
+                "different databases."
+            )
+        # `isolation_level=None`: the session drives the transactions, not the connector.
+        connection = sqlite3.connect(
+            database or ":memory:", isolation_level=None, uri=True
+        )
+        # Without this, SQLite accepts the FKs and does NOT enforce them. Unacceptable silence.
+        connection.execute("PRAGMA foreign_keys = ON")
+        return cls(connection)
+
+    @translating
+    def fetch_all(self, sql: str, params: Sequence[object]) -> list[tuple[object, ...]]:
+        """Runs the query and returns every row as tuples, closing the cursor."""
+        self._ensure_tx()
+        cursor = self._connection.execute(
+            sql, adapt_params(params, native_arrays=False, percent_formatting=False)
+        )
+        try:
+            return [tuple(row) for row in cursor.fetchall()]
+        finally:
+            cursor.close()
+
+    def fetch_iter(
+        self, sql: str, params: Sequence[object], *, chunk: int = 1000
+    ) -> Iterator[tuple[object, ...]]:
+        """Yields the rows in chunks with `fetchmany`.
+
+        SQLite has no server-side cursors —the database IS the process—, so there is nothing to
+        leave over there. What this does avoid is building the whole result list in Python: the
+        memory peak becomes the chunk, not the result. Less than on Postgres, but real, and the
+        same contract for whoever calls it.
+        """
+        self._ensure_tx()
+        cursor = self._connection.execute(
+            sql, adapt_params(params, native_arrays=False, percent_formatting=False)
+        )
+        try:
+            while True:
+                rows = cursor.fetchmany(chunk)
+                if not rows:
+                    return
+                for row in rows:
+                    yield tuple(row)
+        finally:
+            cursor.close()
+
+    @translating
+    def execute(self, sql: str, params: Sequence[object]) -> int:
+        """Runs a statement fetching no rows and returns how many it affected."""
+        self._ensure_tx()
+        cursor = self._connection.execute(
+            sql, adapt_params(params, native_arrays=False, percent_formatting=False)
+        )
+        try:
+            return int(cursor.rowcount)
+        finally:
+            cursor.close()
+
+    @property
+    def last_insert_id(self) -> int:
+        """The id of the last INSERT (see the Protocol). Unused: this engine returns the PK through RETURNING."""
+        return 0  # SQLite returns the PK through RETURNING; this value is not used
+
+    @translating
+    def commit(self) -> None:
+        """Commits the transaction in progress (if any). The next statement opens another one."""
+        if self._in_tx:
+            self._connection.execute("COMMIT")
+            self._in_tx = False
+
+    def rollback(self) -> None:
+        """Rolls back the transaction in progress (if any). A no-op if nothing was open."""
+        if self._in_tx:
+            self._connection.execute("ROLLBACK")
+            self._in_tx = False
+
+    def savepoint(self, name: str) -> None:
+        """Opens a named savepoint. `execute` opens the transaction lazily, so a `SAVEPOINT` as the
+        very first operation works too.
+        """
+        self.execute(f"SAVEPOINT {quote_savepoint(name, quote=_QUOTE)}", ())
+
+    def release_savepoint(self, name: str) -> None:
+        """Commits the savepoint (you can no longer go back to it)."""
+        self.execute(f"RELEASE SAVEPOINT {quote_savepoint(name, quote=_QUOTE)}", ())
+
+    def rollback_to_savepoint(self, name: str) -> None:
+        """Goes back to the savepoint, undoing what was done since it was opened."""
+        self.execute(f"ROLLBACK TO SAVEPOINT {quote_savepoint(name, quote=_QUOTE)}", ())
+
+    def close(self) -> None:
+        """Closes the connection."""
+        self._connection.close()

snakeorm/drivers/threaded.py

@@ -0,0 +1,143 @@
+"""A SYNCHRONOUS driver served as an `AsyncDriver`, on a thread of its own.
+
+All three engines are first class, but only one has a native asyncio library among the project's
+deps (psycopg 3). For the other two, the synchronous driver is served from a thread instead of
+adding a dependency per engine.
+
+**It is not faking async.** It is exactly what `aiosqlite` does on the inside, and for MySQL it
+gives REAL concurrency: Python releases the GIL while the socket waits, so two queries from two
+different tasks really do overlap. What it does NOT give is the performance of a native protocol
+under heavy concurrency, because every connection takes up a thread.
+
+**One thread per connection, and not a shared pool.** A DBAPI connection is not thread-safe:
+`sqlite3` checks and refuses, and PyMySQL simply corrupts itself if two threads use it at once.
+With a single thread per driver, the calls serialise by construction and the connection always
+sees the same thread. Serialising costs nothing here: a session already waits for each query
+before firing the next one, and whoever wants parallelism opens more connections.
+
+Once a native driver exists for an engine, it comes in as its own implementation of the Protocol
+and this adapter stops being used for that one. The seam does not change: both are `AsyncDriver`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from itertools import islice
+from collections.abc import AsyncIterator, Callable, Iterator, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from typing import Self, TypeVar
+
+from snakeorm.drivers.base import SnakeDriver
+
+T = TypeVar("T")
+
+_END = object()
+"""End-of-iteration sentinel. A `StopIteration` cannot cross a `Future`: asyncio turns it into a
+`RuntimeError` and the message says nothing about what actually happened."""
+
+
+class ThreadedAsyncDriver:
+    """Wraps a `SnakeDriver` and exposes it as an `AsyncDriver`, on a dedicated thread."""
+
+    def __init__(self, inner: SnakeDriver, *, executor: ThreadPoolExecutor) -> None:
+        self._inner = inner
+        self._executor = executor
+
+    @classmethod
+    async def open(cls, factory: Callable[[], SnakeDriver]) -> Self:
+        """Opens the connection INSIDE the adapter's thread and wraps it.
+
+        Having the thread that will use it open it is not a precaution: `sqlite3` TIES the
+        connection to its creating thread and raises `ProgrammingError` if another one touches it,
+        so building it outside and using it inside blew up on the first `close()`. With this, the
+        connection is born and dies on the same thread.
+
+        `max_workers=1` is what makes the wrapper correct, not a performance knob: a DBAPI
+        connection is not thread-safe, and a single thread serialises the calls by construction.
+        """
+        executor = ThreadPoolExecutor(
+            max_workers=1, thread_name_prefix="snakeorm-driver"
+        )
+        try:
+            inner = await asyncio.get_running_loop().run_in_executor(executor, factory)
+        except BaseException:
+            # If the connection never gets opened, the thread stays alive and the process never ends.
+            executor.shutdown(wait=False)
+            raise
+        return cls(inner, executor=executor)
+
+    async def _run(self, work: Callable[[], T]) -> T:
+        """Runs `work` on the driver's thread and waits without blocking the loop."""
+        return await asyncio.get_running_loop().run_in_executor(self._executor, work)
+
+    async def fetch_all(
+        self, sql: str, params: Sequence[object]
+    ) -> list[tuple[object, ...]]:
+        """Runs the query and returns every row as tuples."""
+        return await self._run(lambda: self._inner.fetch_all(sql, params))
+
+    async def fetch_iter(
+        self, sql: str, params: Sequence[object], *, chunk: int = 1000
+    ) -> AsyncIterator[tuple[object, ...]]:
+        """Yields the rows WITHOUT materialising them all, crossing the thread once per CHUNK.
+
+        It stays LAZY, at the granularity of `chunk` — which is what `chunk` means everywhere else
+        in this ORM, the inner driver included (`sqlite.py` uses `fetchmany(chunk)`). That `chunk`
+        governs the round trip to the SERVER; this one governs the crossing of the thread.
+
+        Crossing per ROW instead —a Future, a callback on the loop and waking a thread, for every
+        row— measured 103 trips to the executor for 100 rows, where the chunked read costs a
+        handful. `islice` is what keeps the laziness and the chunking at the same time, and this is
+        the only async path two of the three first-class engines have.
+
+        What a `break` costs goes from one row to one chunk. It never costs the whole result: the
+        synchronous iterator is still only advanced as far as it is read.
+        """
+        iterator: Iterator[tuple[object, ...]] = await self._run(
+            lambda: iter(self._inner.fetch_iter(sql, params, chunk=chunk))
+        )
+        size = max(1, chunk)
+        try:
+            while True:
+                batch = await self._run(lambda: list(islice(iterator, size)))
+                if not batch:
+                    return
+                for row in batch:
+                    yield row
+        finally:
+            # The cursor lives as long as the iteration does; closing it here covers the `break` too.
+            await self._run(lambda: iterator.close())  # type: ignore[attr-defined]
+
+    async def execute(self, sql: str, params: Sequence[object]) -> int:
+        """Runs a statement fetching no rows; returns how many it affected."""
+        return await self._run(lambda: self._inner.execute(sql, params))
+
+    @property
+    def last_insert_id(self) -> int:
+        """The autoincrement id of the last INSERT. It does not travel to the database: no thread needed."""
+        return self._inner.last_insert_id
+
+    async def commit(self) -> None:
+        """Commits the transaction in progress."""
+        await self._run(self._inner.commit)
+
+    async def rollback(self) -> None:
+        """Rolls back the transaction in progress."""
+        await self._run(self._inner.rollback)
+
+    async def savepoint(self, name: str) -> None:
+        """Opens a named savepoint."""
+        await self._run(lambda: self._inner.savepoint(name))
+
+    async def release_savepoint(self, name: str) -> None:
+        """Commits the savepoint."""
+        await self._run(lambda: self._inner.release_savepoint(name))
+
+    async def rollback_to_savepoint(self, name: str) -> None:
+        """Goes back to the savepoint, undoing what was done since it was opened."""
+        await self._run(lambda: self._inner.rollback_to_savepoint(name))
+
+    async def close(self) -> None:
+        """Closes the connection AND shuts the thread down. Without the second, the process never ends."""
+        await self._run(self._inner.close)
+        self._executor.shutdown(wait=True)

snakeorm/drivers/timeout.py

@@ -0,0 +1,87 @@
+"""A driver that caps how long a statement may take, by wrapping another one."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+
+from snakeorm.core.exceptions import SnakeDialectError
+from snakeorm.dialects.base import SnakeDialect
+from snakeorm.drivers.base import SnakeDriver
+
+
+class TimeoutDriver:
+    """Wraps a `SnakeDriver` and sets a `statement_timeout` for the whole connection: one hung
+    query drains the pool. The setting is emitted ONCE on wrapping (it is per CONNECTION, not per
+    statement).
+    """
+
+    __slots__ = ("_inner",)
+
+    def __init__(
+        self, inner: SnakeDriver, dialect: SnakeDialect, *, statement_timeout_ms: int
+    ) -> None:
+        if statement_timeout_ms <= 0:
+            # On Postgres `statement_timeout = 0` means NO LIMIT: accepting 0 would silently do the opposite.
+            raise ValueError(
+                "statement_timeout_ms has to be greater than zero: in Postgres 0 means NO limit, "
+                "so asking for 0 would switch the timeout off instead of tightening it."
+            )
+        # The statement is ASKED of the dialect. It used to be written here as
+        # `SET statement_timeout = <ms>`, which is Postgres and only Postgres, under a class name
+        # that promises nothing about engines: MySQL answered `1193 Unknown system variable` and
+        # SQLite a syntax error, so the knob that keeps one hung query from draining the pool
+        # worked on one engine out of three.
+        statement = dialect.statement_timeout_sql(statement_timeout_ms)
+        if statement is None:
+            raise SnakeDialectError(
+                f"{type(dialect).__name__} has no server-side statement timeout, so this driver "
+                f"cannot cap anything on it. Accepting the wrap would hand back a connection that "
+                f"LOOKS capped and is not, which is the opposite of what asking for a timeout "
+                f"means. (SQLite's `busy_timeout` waits for a lock; it does nothing about a slow "
+                f"query.)"
+            )
+        self._inner = inner
+        self._inner.execute(statement, ())
+
+    def fetch_all(self, sql: str, params: Sequence[object]) -> list[tuple[object, ...]]:
+        """Delegates the query; the limit is already set on the connection."""
+        return self._inner.fetch_all(sql, params)
+
+    def fetch_iter(
+        self, sql: str, params: Sequence[object], *, chunk: int = 1000
+    ) -> Iterator[tuple[object, ...]]:
+        """Delegates the streaming; the limit is already set on the connection."""
+        return self._inner.fetch_iter(sql, params, chunk=chunk)
+
+    def execute(self, sql: str, params: Sequence[object]) -> int:
+        """Delegates the statement; the limit is already set on the connection."""
+        return self._inner.execute(sql, params)
+
+    @property
+    def last_insert_id(self) -> int:
+        """The id of the last INSERT (see the Protocol). Forwarded to the wrapped driver."""
+        return self._inner.last_insert_id
+
+    def commit(self) -> None:
+        """Commits the inner driver's transaction."""
+        self._inner.commit()
+
+    def rollback(self) -> None:
+        """Rolls back the inner driver's transaction."""
+        self._inner.rollback()
+
+    def savepoint(self, name: str) -> None:
+        """Marks a savepoint on the inner driver."""
+        self._inner.savepoint(name)
+
+    def release_savepoint(self, name: str) -> None:
+        """Releases a savepoint on the inner driver."""
+        self._inner.release_savepoint(name)
+
+    def rollback_to_savepoint(self, name: str) -> None:
+        """Rolls back to a savepoint on the inner driver."""
+        self._inner.rollback_to_savepoint(name)
+
+    def close(self) -> None:
+        """Closes the inner driver."""
+        self._inner.close()

snakeorm/dto/__init__.py

@@ -0,0 +1,55 @@
+"""Typed DTOs: you declare the shape, `snakeorm dto --sync` writes the TypedDicts into your file.
+
+    if TYPE_CHECKING:
+        from blog.models import Author, Post
+        from snakeorm.dto import snake_dto
+
+        snake_dto(Author, fields=[Author.id, Author.username], name="AuthorDto")
+        snake_dto(Post, fields=[Post.id, Post.title, Post.author], name="PostCard")
+
+The declaration sits inside `if TYPE_CHECKING:` because that buys three things at once: the checker
+validates every path, nothing runs at import, and the module does not drag in the models. The
+generator READS that block with `ast` and never executes the file it rewrites.
+
+Four modules, one job each:
+
+    spec.py     what a declaration may say, and the checks both routes share
+    read.py     what this file says, read from source without importing it
+    resolve.py  what it MEANS against the compiled graph: types, nesting, write order
+    region.py   where it is written, and why nothing outside the markers is touched
+
+It writes the SHAPE and never the query. A spec that nests `Post.author` describes a row loaded with
+`include(Post.author)`; forget it and the ORM raises `SnakeRelationshipNotLoaded` naming the call.
+
+The facade does not re-export any of this — it is a prototype. Import from `snakeorm.dto`.
+See `docs/users/guide/typed-dtos.md`.
+"""
+
+from __future__ import annotations
+
+from snakeorm.dto.read import (
+    specs_in_source as specs_in_source,
+)
+from snakeorm.dto.region import (
+    BEGIN as BEGIN,
+    END as END,
+    SnakeDtoChange as SnakeDtoChange,
+    SnakeDtoChangeKind as SnakeDtoChangeKind,
+    SnakeDtoSyncResult as SnakeDtoSyncResult,
+    sync_file as sync_file,
+    sync_source as sync_source,
+)
+from snakeorm.dto.resolve import (
+    SnakeDtoField as SnakeDtoField,
+    SnakeDtoShape as SnakeDtoShape,
+    resolve_all as resolve_all,
+)
+from snakeorm.dto.spec import (
+    SnakeDtoEntry as SnakeDtoEntry,
+    SnakeDtoPath as SnakeDtoPath,
+    SnakeDtoPick as SnakeDtoPick,
+    SnakeDtoSelection as SnakeDtoSelection,
+    SnakeDtoSpec as SnakeDtoSpec,
+    build_spec as build_spec,
+    snake_dto as snake_dto,
+)