snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/drivers/base.py

@@ -0,0 +1,76 @@
+"""The Protocol that defines a driver: how the SQL is EXECUTED (synchronous)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SnakeDriver(Protocol):
+    """How the SQL is executed: wraps the DBAPI (connection, cursor, transaction).
+
+    SYNCHRONOUS. The SQL arrives already compiled (colourless) from `sql/`; the driver only
+    runs it. The day async is needed, an AsyncDriver is added WITHOUT touching the compiler,
+    the dialect or the AST. Adding a new engine = one implementation of this Protocol, with
+    no refactor.
+    """
+
+    def fetch_all(self, sql: str, params: Sequence[object]) -> list[tuple[object, ...]]:
+        """Runs a query and returns every row (for SELECT / RETURNING)."""
+        ...
+
+    def fetch_iter(
+        self, sql: str, params: Sequence[object], *, chunk: int = 1000
+    ) -> Iterator[tuple[object, ...]]:
+        """Runs a query and yields the rows WITHOUT materialising them all.
+
+        This is the streaming seam, and that is why it lives in the Protocol and not in some
+        loose method on one driver: with only `fetch_all`, a ten-million-row query built a
+        Python list of ten million tuples before returning the first one, and there was no way
+        to fix that without touching this contract.
+
+        `chunk` is how many rows the engine brings back per round trip: the knob that decides
+        the memory. Whoever can, uses a SERVER-SIDE CURSOR (the result stays over there);
+        whoever cannot, a `fetchmany`, which at least bounds the peak.
+
+        The cursor lives for as long as the iteration does, so the consumer must exhaust it or
+        close it.
+        """
+        ...
+
+    def execute(self, sql: str, params: Sequence[object]) -> int:
+        """Runs a statement fetching no rows and returns the rowcount (used by bulk writes)."""
+        ...
+
+    @property
+    def last_insert_id(self) -> int:
+        """The autoincrement id of the last INSERT. The session only uses it on engines WITHOUT
+        `RETURNING` (MySQL); on Postgres/SQLite the PK comes back through RETURNING and this is
+        irrelevant (it may be 0).
+        """
+        ...
+
+    def commit(self) -> None:
+        """Commits the transaction in progress."""
+        ...
+
+    def rollback(self) -> None:
+        """Rolls back the transaction in progress."""
+        ...
+
+    def savepoint(self, name: str) -> None:
+        """Marks a SAVEPOINT: lets you roll back ONLY a part (via `rollback_to_savepoint`) without aborting the transaction."""
+        ...
+
+    def release_savepoint(self, name: str) -> None:
+        """Releases (RELEASE) a savepoint: its work is folded into the transaction in progress."""
+        ...
+
+    def rollback_to_savepoint(self, name: str) -> None:
+        """Rolls back to a savepoint: discards what was done since it, without aborting the transaction."""
+        ...
+
+    def close(self) -> None:
+        """Closes the connection."""
+        ...

snakeorm/drivers/failures.py

@@ -0,0 +1,181 @@
+"""Turning a driver's exception into the ORM's, by CODE and never by message.
+
+A violated constraint came back as `psycopg2.errors.UniqueViolation`, `pymysql.err.IntegrityError`
+and `sqlite3.IntegrityError`: three types for one condition, so the `except` that handled it was the
+one part of an application this ORM could not carry between engines.
+
+WHY BY CODE. Reading the message is how a detector fails open — it finds only what somebody already
+thought to look for. It is also not needed: all three engines say precisely which constraint broke,
+each in its own place.
+
+    postgres  SQLSTATE           23505 / 23503 / 23502 / 23514
+    mysql     errno              1062  / 1452  / 1048  / 4025
+              (its SQLSTATE is 23000 for all four and says nothing)
+    sqlite    sqlite_errorname   SQLITE_CONSTRAINT_UNIQUE / _FOREIGNKEY / _NOTNULL / _CHECK
+              (Python 3.11+, which is this project's declared floor)
+
+AND NEVER BY THE DRIVER'S CLASS, which is the trap this module exists to keep shut: on MySQL a CHECK
+violation arrives as `OperationalError` while the other three arrive as `IntegrityError`. Keyed on
+the class, that one lands in the wrong bucket on one engine only.
+
+One function for the three engines, the same way `session/retry.py::is_transient` reads them: it
+looks for each spelling in turn and does not need to know who raised.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Awaitable, Callable, Iterator
+from contextlib import contextmanager
+from typing import ParamSpec, TypeVar, cast
+
+from snakeorm.core.exceptions import (
+    SnakeCheckViolation,
+    SnakeForeignKeyViolation,
+    SnakeIntegrityError,
+    SnakeNotNullViolation,
+    SnakeUniqueViolation,
+)
+
+P = ParamSpec("P")
+T = TypeVar("T")
+AsyncMethod = TypeVar("AsyncMethod", bound=Callable[..., Awaitable[object]])
+"""An asynchronous driver method, PRESERVED. Bound and not `ParamSpec` + return, because what
+has to survive the decorator is the exact signature the Protocol declares, `CoroutineType`
+included."""
+
+_BY_SQLSTATE: dict[str, type[SnakeIntegrityError]] = {
+    "23505": SnakeUniqueViolation,
+    "23503": SnakeForeignKeyViolation,
+    "23502": SnakeNotNullViolation,
+    "23514": SnakeCheckViolation,
+}
+"""PostgreSQL, which is the only one whose SQLSTATE distinguishes the four."""
+
+_BY_MYSQL_ERRNO: dict[int, type[SnakeIntegrityError]] = {
+    1062: SnakeUniqueViolation,  # ER_DUP_ENTRY
+    1586: SnakeUniqueViolation,  # ER_DUP_ENTRY_WITH_KEY_NAME
+    1452: SnakeForeignKeyViolation,  # ER_NO_REFERENCED_ROW_2
+    1451: SnakeForeignKeyViolation,  # ER_ROW_IS_REFERENCED_2 (the delete side)
+    1048: SnakeNotNullViolation,  # ER_BAD_NULL_ERROR
+    3819: SnakeCheckViolation,  # ER_CHECK_CONSTRAINT_VIOLATED (MySQL 8)
+    4025: SnakeCheckViolation,  # ER_CONSTRAINT_FAILED (MariaDB)
+}
+"""MySQL and MariaDB. Two errnos per family where the engines disagree, and both are listed rather
+than one guessed: MariaDB reports a CHECK as 4025 and MySQL 8 as 3819, and a foreign key breaks from
+either side."""
+
+_BY_SQLITE_NAME: dict[str, type[SnakeIntegrityError]] = {
+    "SQLITE_CONSTRAINT_UNIQUE": SnakeUniqueViolation,
+    "SQLITE_CONSTRAINT_PRIMARYKEY": SnakeUniqueViolation,
+    "SQLITE_CONSTRAINT_FOREIGNKEY": SnakeForeignKeyViolation,
+    "SQLITE_CONSTRAINT_NOTNULL": SnakeNotNullViolation,
+    "SQLITE_CONSTRAINT_CHECK": SnakeCheckViolation,
+}
+"""SQLite's EXTENDED result codes. `PRIMARYKEY` is its own name for what the other two call a unique
+violation, so it maps to the same exception rather than falling through to the generic family."""
+
+
+_SAYS: dict[type[SnakeIntegrityError], str] = {
+    SnakeUniqueViolation: "a UNIQUE constraint refused the write: that value is already there",
+    SnakeForeignKeyViolation: (
+        "a FOREIGN KEY refused the write: the row it points at is not there, or it is still "
+        "pointed at"
+    ),
+    SnakeNotNullViolation: "a NOT NULL column was given nothing",
+    SnakeCheckViolation: "a CHECK constraint refused the write",
+}
+"""What the ORM says, in its OWN words, before quoting the engine.
+
+Passing the driver's text through unchanged was half a translation: the exception was portable and
+the sentence it carried still was not, so anything reading the message was back to three engines.
+In this ORM the message is the product.
+
+The engine's own words follow, because they carry what these cannot — WHICH constraint, and the
+value that collided. Two texts for one fact, in the right order: what happened, then who said so.
+"""
+
+
+def translate(error: BaseException) -> SnakeIntegrityError | None:
+    """The ORM exception this driver error corresponds to, or `None` if it is not a constraint.
+
+    `None` is the answer for everything else — a syntax error, a dropped connection, a timeout — and
+    those keep flying untouched. Wrapping what is not understood would put an ORM name on a problem
+    the ORM did not diagnose, which is worse than the raw exception it replaced.
+    """
+    for attribute in ("sqlstate", "pgcode"):
+        sqlstate = getattr(error, attribute, None)
+        if isinstance(sqlstate, str) and sqlstate in _BY_SQLSTATE:
+            return _built(_BY_SQLSTATE[sqlstate], error, sqlstate)
+    name = getattr(error, "sqlite_errorname", None)
+    if isinstance(name, str) and name in _BY_SQLITE_NAME:
+        return _built(_BY_SQLITE_NAME[name], error, name)
+    errno = error.args[0] if error.args else None
+    if isinstance(errno, int) and errno in _BY_MYSQL_ERRNO:
+        return _built(_BY_MYSQL_ERRNO[errno], error, errno)
+    return None
+
+
+def _built(
+    kind: type[SnakeIntegrityError], error: BaseException, code: str | int
+) -> SnakeIntegrityError:
+    """The exception, its message and what it was built from, in one place."""
+    return kind(
+        f"{_SAYS[kind]}. The engine said: {error}", driver_error=error, code=code
+    )
+
+
+@contextmanager
+def translating_failures() -> Iterator[None]:
+    """Runs a driver call and re-raises a constraint failure as the ORM's own, CHAINED.
+
+    `from error` is the whole difference between wrapping and hiding: the original stays in
+    `__cause__`, the traceback prints both, and whoever debugs still gets the server's own words
+    about what it refused.
+    """
+    try:
+        yield
+    except Exception as error:
+        translated = translate(error)
+        if translated is None:
+            raise
+        raise translated from error
+
+
+def translating(method: Callable[P, T]) -> Callable[P, T]:
+    """Applies the translation to one synchronous driver method.
+
+    A decorator and not a `with` inside each body, because it is the same line twenty times and a
+    decorator is the version somebody can see is MISSING from a method.
+
+    Not for `fetch_iter`: it is a generator, so this wrapper would return it without running a
+    statement and the exception would escape untranslated during iteration. It is also not needed —
+    it walks a SELECT, and a SELECT breaks no constraint.
+    """
+
+    @functools.wraps(method)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        with translating_failures():
+            return method(*args, **kwargs)
+
+    return wrapper
+
+
+def async_translating(method: AsyncMethod) -> AsyncMethod:
+    """The same for an asynchronous driver method. The colour changes; the classification does not.
+
+    It gives BACK the type it was handed, instead of describing the wrapper: a decorator that
+    translates exceptions must not change what the method IS. Spelling the return as
+    `Callable[P, Coroutine[object, object, T]]` looked equivalent and was not — an `async def`
+    declared in a Protocol is a `CoroutineType`, which a plain `Coroutine` does not satisfy, so
+    every driver wrapped by this stopped being an `AsyncDriver` for pyright while mypy said
+    nothing. The one function that hands the pair out (`connection.py::driver_and_dialect`) was
+    the visible casualty.
+    """
+
+    @functools.wraps(method)
+    async def wrapper(*args: object, **kwargs: object) -> object:
+        with translating_failures():
+            return await method(*args, **kwargs)
+
+    return cast("AsyncMethod", wrapper)

snakeorm/drivers/logging.py

@@ -0,0 +1,167 @@
+"""A driver that LOGS the SQL passing through it, by wrapping another one."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+
+from snakeorm.drivers.base import SnakeDriver
+
+# Where each line gets written. By default it writes nothing (leave it wired up without making a mess); inject `print`/a logger.
+Writer = Callable[[str], None]
+
+
+def _silent(line: str) -> None:
+    """Throws the line away (the default behaviour)."""
+
+
+def render_params(params: Sequence[object], keys: frozenset[str]) -> str:
+    """The named parameters, the rest hidden, and the count always.
+
+    The guide wires these drivers with `write=print`, whose output is the container's stdout and
+    from there the log aggregator. So `params=('ana@x.com', '$2b$12$...')` was an email and a
+    password hash sitting in a searchable index, with no flag to turn it off.
+
+    Written ONCE for both colours on purpose: the asynchronous driver went on printing raw
+    values after the synchronous one stopped, which is the drift this seam keeps suffering.
+    """
+    if not keys:
+        return f"<{len(params)} hidden>"
+    shown = [
+        repr(value) if str(index) in keys else "<hidden>"
+        for index, value in enumerate(params)
+    ]
+    return f"({', '.join(shown)})"
+
+
+@contextmanager
+def _logged(write: Writer, head: str) -> Iterator[list[str]]:
+    """Writes ONE line for the statement, whether it worked or not.
+
+    Every write point used to sit AFTER the inner call, so a statement that raised left no line
+    at all: you opened the log at 3:14, found the ten statements before it and a ROLLBACK —that
+    one wrote, because `rollback()` follows a call that does not fail— and no trace of what
+    caused the rollback. The log showed you everything except the thing you came for.
+
+    And the exception does not carry it either: `drivers/failures.py` builds its message from
+    the engine's words, with no SQL and no params in it. The log WAS the only place the failed
+    statement existed.
+
+    The caller appends its outcome to the yielded list; if it never gets there, the failure is
+    written instead. `except BaseException` and re-raise: a timeout or a cancellation is exactly
+    the kind of ending worth having in the log.
+
+    `fetch_iter` does NOT use this, deliberately — see its own docstring.
+    """
+    outcome: list[str] = []
+    try:
+        yield outcome
+    except BaseException as error:
+        write(f"{head} -> FAILED: {type(error).__name__}: {error}")
+        raise
+    # A boundary counts no rows: `COMMIT` stays `COMMIT`, byte for byte.
+    write(f"{head} -> {outcome[0]}" if outcome else head)
+
+
+class LoggingDriver:
+    """Wraps a `SnakeDriver` and logs SQL, params and how much it affected. A pure decorator: it changes nothing.
+    It also logs the transaction boundaries (commit/rollback/savepoints); without them the log lies by omission.
+    """
+
+    __slots__ = ("_inner", "_parameter_keys", "_write")
+
+    def __init__(
+        self,
+        inner: SnakeDriver,
+        write: Writer = _silent,
+        *,
+        parameter_keys: frozenset[str] = frozenset(),
+    ) -> None:
+        """`parameter_keys` names the parameter positions to WRITE OUT, and there is no environment
+        variable for it.
+
+        That omission is the decision, and it is the same one `debug/otel/exporter.py` already made
+        for the same data: an environment variable is precisely the switch somebody flips in
+        production by accident, and this one would put user values into the log aggregator. It takes
+        an explicit line of code, key by key — the key of a positional parameter is its 0-based
+        index, as the OpenTelemetry convention spells it.
+
+        By default the values are hidden and the COUNT is written instead. The count leaks nothing
+        and it is half of what makes a log line readable.
+        """
+        self._inner = inner
+        self._write = write
+        self._parameter_keys = parameter_keys
+
+    def _params(self, params: Sequence[object]) -> str:
+        """The parameters as this driver writes them. Delegates so both colours render alike."""
+        return render_params(params, self._parameter_keys)
+
+    def fetch_all(self, sql: str, params: Sequence[object]) -> list[tuple[object, ...]]:
+        """Runs the query, logs the SQL and how many rows it returned."""
+        with _logged(self._write, f"{sql} -- params={self._params(params)}") as outcome:
+            rows = self._inner.fetch_all(sql, params)
+            outcome.append(f"{len(rows)} row(s)")
+        return rows
+
+    def fetch_iter(
+        self, sql: str, params: Sequence[object], *, chunk: int = 1000
+    ) -> Iterator[tuple[object, ...]]:
+        """Logs the SQL and yields the rows, counting them WHEN IT IS DONE.
+
+        The counter goes at the end and not at the start on purpose: writing "-> N rows" before
+        walking them would require materialising them, which is exactly what this path avoids.
+        What actually got consumed is what gets logged, and that is also the interesting figure
+        when somebody cuts out with a `break`.
+        """
+        counter = 0
+        try:
+            for row in self._inner.fetch_iter(sql, params, chunk=chunk):
+                counter += 1
+                yield row
+        finally:
+            self._write(
+                f"{sql} -- params={self._params(params)} -> {counter} row(s) streamed"
+            )
+
+    def execute(self, sql: str, params: Sequence[object]) -> int:
+        """Runs the statement, logs the SQL and how many rows it affected."""
+        with _logged(self._write, f"{sql} -- params={self._params(params)}") as outcome:
+            affected = self._inner.execute(sql, params)
+            outcome.append(f"{affected} row(s)")
+        return affected
+
+    @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 transaction and writes it down."""
+        with _logged(self._write, "COMMIT"):
+            self._inner.commit()
+
+    def rollback(self) -> None:
+        """Rolls the transaction back and writes it down."""
+        with _logged(self._write, "ROLLBACK"):
+            self._inner.rollback()
+
+    def savepoint(self, name: str) -> None:
+        """Marks a savepoint and writes it down."""
+        with _logged(self._write, f"SAVEPOINT {name}"):
+            self._inner.savepoint(name)
+
+    def release_savepoint(self, name: str) -> None:
+        """Releases a savepoint and writes it down."""
+        with _logged(self._write, f"RELEASE SAVEPOINT {name}"):
+            self._inner.release_savepoint(name)
+
+    def rollback_to_savepoint(self, name: str) -> None:
+        """Rolls back to a savepoint and writes it down."""
+        with _logged(self._write, f"ROLLBACK TO SAVEPOINT {name}"):
+            self._inner.rollback_to_savepoint(name)
+
+    def close(self) -> None:
+        """Closes the INNER driver: the decorator does not keep the connection."""
+        with _logged(self._write, "CLOSE"):
+            self._inner.close()