snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/core/converters.py

@@ -0,0 +1,172 @@
+"""The registry for the SECOND axis of the type vocabulary: how a value TRAVELS there and back.
+
+The type vocabulary has two axes, and until now only one of them was open:
+
+- **How the column is WRITTEN** — `dialect.register_type(type, sql)`. It goes per dialect, because
+  the same Python type is written `INET` in Postgres and `TEXT` in SQLite.
+- **How the value TRAVELS** — this. It goes global, and it can go global because `from_db` is
+  IDEMPOTENT.
+
+That idempotence is the piece the whole design rests on. The eleven internal converters already
+honour it: `_to_decimal` swallows the `Decimal` Postgres returns and the `str` SQLite returns with
+the same code, so nobody has to ask which engine they are on. Without it we would have to register
+one converter per engine, and the value axis would stop being agnostic.
+
+It lives in `core/` because both ends of the journey consult it: `sql/adapt.py` on write and
+`session/coercion.py` on read. Anywhere else would create a cycle between `sql/` and `session/`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import TypeVar, cast
+
+from snakeorm.core.exceptions import SnakeConfigError
+
+T = TypeVar("T")
+
+ToDb = Callable[[object], object]
+"""From the domain type to something a DBAPI driver knows how to send, as it is STORED in the
+registry.
+
+Converters come in typed —`register_converter` is generic in the type being declared, so whoever
+writes the `to_db` receives their own type and not `object`— and are stored untyped because the
+registry is heterogeneous: a single table with a different type per key.
+"""
+
+FromDb = Callable[[object], object]
+"""From what the driver returns to the domain type. It MUST be idempotent. See `ToDb`."""
+
+_TO_DB: dict[type, ToDb] = {}
+_FROM_DB: dict[type, FromDb] = {}
+
+_BUILTIN: set[type] = set()
+"""The types whose journey the ORM already defines. `session/coercion.py` DECLARES them on import.
+
+The direction matters: `core/` cannot import `session/` —`test_layering` checks it, and rightly so:
+a cycle between layers turns import order into part of the behaviour—. So the upper layer registers
+itself when it loads, instead of this one going off to ask it.
+"""
+
+_PROBES: tuple[object, ...] = ("", 0, b"")
+"""The values idempotence is tested with at registration time.
+
+They do not aim to cover the type's domain: all it takes is ONE round the converter knows how to
+make, so we can make it again and compare. If it can make none of them, the check keeps quiet —
+testing with what the converter does not accept would claim it is not idempotent when something else
+is going on.
+"""
+
+
+def register_converter(
+    python_type: type[T],
+    *,
+    to_db: Callable[[T], object],
+    from_db: Callable[[object], T],
+) -> None:
+    """Declares how a domain type travels: from Python to the driver and back.
+
+    Generic in the declared type, so whoever writes the converters works with THEIR type and not
+    with `object`: `to_db` receives an `Inet` and `from_db` returns an `Inet`, and the checker
+    verifies it. An ORM whose selling point is typing cannot ask for untyped lambdas in its own API.
+
+    `from_db` MUST be idempotent —`from_db(from_db(x)) == from_db(x)`— because the same converter
+    serves all three engines and each returns the column in one shape: Postgres may hand over the
+    object already and SQLite the text. It is checked here, at registration time, and not on the
+    first read in production.
+
+    It does not rewrite the types the ORM already handles. A global registry is an invitation for a
+    third-party library to change how a `Decimal` travels for the entire process just by being
+    imported.
+    """
+    if python_type in _BUILTIN:
+        raise SnakeConfigError(
+            f"{python_type!r} is a type the ORM already handles, so its converter is not rewritten. "
+            f"A global registry is shared by the whole process: changing here how a core type "
+            f"travels would change it too for code that asked for nothing."
+        )
+    _demand_idempotent(python_type, from_db)
+    # The registry is heterogeneous (one key per type, each with its own signature), so they are
+    # stored untyped. The `cast` loses nothing: the generic signature already checked the pair at
+    # the call site.
+    _TO_DB[python_type] = cast("ToDb", to_db)
+    _FROM_DB[python_type] = cast("FromDb", from_db)
+
+
+def _demand_idempotent(python_type: type, from_db: Callable[[object], object]) -> None:
+    """Checks that applying `from_db` twice gives the same as applying it once.
+
+    It is tested with probe values, ignoring the ones the converter cannot swallow: what we are
+    after is a round it CAN make, so we can make it again. If no probe works, nothing is claimed —
+    a false positive here would block a perfectly correct type.
+
+    The two calls are attempted SEPARATELY, and that separation is the whole guard rather than a
+    tidying-up. Under a single `try` both failures looked the same and both were read as "this probe
+    does not fit the type, try the next one" — but they are opposite facts. The FIRST call failing
+    says nothing about the converter: the probe simply is not of its shape. The SECOND call failing
+    says everything: the converter swallowed a value and then choked on the value it had just
+    produced, which is exactly what happens the day the engine underneath hands back the object
+    already built instead of its text. So the more dangerous of the two ways of not being idempotent
+    was the one that registered without a word, and it surfaces on a READ, in production, over rows
+    that are already written.
+    """
+    for probe in _PROBES:
+        try:
+            once = from_db(probe)
+        except Exception:  # noqa: BLE001 - the probe does not fit this type; try the next one
+            continue
+        try:
+            twice = from_db(once)
+        except Exception as error:
+            raise SnakeConfigError(
+                f"The `from_db` of {python_type!r} is not idempotent: it accepted {probe!r} and "
+                f"then failed on the value it had just returned ({error!r}). It has to accept its "
+                f"own output, because the same converter reads from the three engines and each one "
+                f"returns the column in a different shape: one may hand over the object already and "
+                f"another the text. Make it return the value as it is when it already is the "
+                f"expected type."
+            ) from error
+        if once != twice:
+            raise SnakeConfigError(
+                f"The `from_db` of {python_type!r} is not idempotent: converting twice gives "
+                f"something different from converting once ({once!r} and then {twice!r}). It has to be, "
+                f"because the same converter reads from the three engines, and each one returns the "
+                f"column in a different shape: one may hand over the object already and another the "
+                f"text. Make it return the value as it is when it already is the expected type."
+            )
+        return
+
+
+def mark_builtin(types: Iterable[object]) -> None:
+    """Declares which types the ORM already handles, so `register_converter` will not rewrite them.
+
+    `session/coercion.py` calls it on import, with the keys of its own registry: that way the list
+    is not duplicated —nor can it drift— and `core/` still imports nobody from above.
+    """
+    _BUILTIN.update(klass for klass in types if isinstance(klass, type))
+
+
+def to_db_for(value: object) -> ToDb | None:
+    """The adapter for a VALUE, looked up by its type and its bases', or `None` if there is none.
+
+    By MRO and not by exact `type(value)` so a subclass of the registered type inherits the journey,
+    which is what anyone declaring `class IPv4(Inet)` expects.
+    """
+    if not _TO_DB:
+        return None
+    for klass in type(value).__mro__:
+        adapter = _TO_DB.get(klass)
+        if adapter is not None:
+            return adapter
+    return None
+
+
+def from_db_for(python_type: object) -> FromDb | None:
+    """The read converter of a DECLARED type, or `None` if none was registered."""
+    if not isinstance(python_type, type):
+        return None
+    for klass in python_type.__mro__:
+        converter = _FROM_DB.get(klass)
+        if converter is not None:
+            return converter
+    return None

snakeorm/core/exceptions.py

@@ -0,0 +1,175 @@
+"""Public exception hierarchy: every ORM error hangs off `SnakeError`.
+
+Each one ALSO inherits from the builtin it replaces (ValueError/TypeError/...) for compatibility:
+`except SnakeError` gains precision and `except ValueError` keeps working. Multiple inheritance,
+deliberately. The `TypeError`s from the generated `__init__` (calling a callable wrong) do NOT live
+here.
+"""
+
+from __future__ import annotations
+
+
+class SnakeError(Exception):
+    """Root of every SnakeORM error."""
+
+
+class SnakeModelError(SnakeError, TypeError):
+    """Something without `@snake_model` was passed as a model: the type is inappropriate."""
+
+
+class SnakeModelDefinitionError(SnakeError, ValueError):
+    """The model carries `@snake_model` but is declared wrong (with no PK, for instance).
+
+    It is a valid class with invalid content: hence `ValueError` and not `TypeError`.
+    """
+
+
+class SnakeRegistryError(SnakeError, ValueError):
+    """Trouble in the registry: unregistered model or table collision."""
+
+
+class SnakeUnknownRelationship(SnakeError, ValueError):
+    """A relation the table does not declare was named."""
+
+
+class SnakeUnlinkedRelationship(SnakeError, RuntimeError):
+    """A relation was used before calling `snake_link()`."""
+
+
+class SnakeRelationshipNotLoaded(SnakeError, AttributeError):
+    """A relation the query did not load was accessed (the anti-N+1 lock)."""
+
+
+class SnakeAggregateNotLoaded(SnakeError, AttributeError):
+    """An aggregate asked for through the escape hatch (`obj.aggregate.x`) was not loaded (a missing
+    `annotate`, or a missing name)."""
+
+
+class SnakeColumnNotLoaded(SnakeError, AttributeError):
+    """A column left out by `only()`/`defer()` was read on the instance.
+
+    The sibling of `SnakeRelationshipNotLoaded`, and it exists for the same reason: the alternative
+    is the descriptor falling through to the column's DEFAULT, which hands back `None` or `0` for a
+    value nobody loaded. A wrong answer with no error is the one outcome this ORM does not produce.
+    """
+
+
+class SnakeUnknownColumn(SnakeError, ValueError):
+    """A column the table does not declare was named."""
+
+
+class SnakeConfigError(SnakeError, ValueError):
+    """Configuration is missing to operate (e.g. there is no way to determine the DSN)."""
+
+
+class SnakePoolTimeout(SnakeError, TimeoutError):
+    """The pool could not hand over a healthy connection within the deadline.
+
+    It has a name of its own because the engine's raw error ("connection pool exhausted") does not
+    tell apart two situations that call for opposite actions: "there is no slot right now" (wait, or
+    raise the pool size) and "I have spent thirty seconds failing to get a live one" (the database
+    is down). It inherits from `TimeoutError` so a generic retry treats it as what it is.
+    """
+
+
+class SnakeIntegrityError(SnakeError):
+    """A constraint refused the write. ONE exception where the three drivers raised three.
+
+    A duplicate key came back as `psycopg2.errors.UniqueViolation`, `pymysql.err.IntegrityError` and
+    `sqlite3.IntegrityError`, so the `except` handling it was the one part of an application that
+    could not be moved between engines.
+
+    The driver's exception is CHAINED, never swallowed: it stays in `__cause__` and the traceback
+    prints both. Whoever catches gets a portable name, whoever debugs still gets the server's own
+    words.
+
+    Catch this one to be coarse, or a subtype below to be precise. Every engine says which
+    constraint broke, so the subtype is read off a CODE and never off the message: reading text is
+    how a detector fails open.
+
+    It KEEPS what it was built from, in `driver_error` and `code`, so the classification is testable
+    without an engine — checking that MariaDB's 4025 lands in `SnakeCheckViolation` needs no
+    MariaDB, while `__cause__` proves the chaining and says nothing about the DECISION. The engine
+    tests then check the other half, that the engine really does send that code.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        driver_error: BaseException | None = None,
+        code: str | int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.driver_error = driver_error
+        """The exception the DBAPI raised, kept whole. Also reachable as `__cause__`."""
+        self.code = code
+        """The engine's own code that decided the subtype: a SQLSTATE, a MySQL errno or an SQLite
+        extended-result name. What was READ, not what was guessed — so a wrong classification can be
+        argued with rather than re-derived."""
+
+
+class SnakeUniqueViolation(SnakeIntegrityError):
+    """A UNIQUE constraint or a primary key already holds that value."""
+
+
+class SnakeForeignKeyViolation(SnakeIntegrityError):
+    """A foreign key points at a row that is not there, or a referenced row was removed."""
+
+
+class SnakeNotNullViolation(SnakeIntegrityError):
+    """A NOT NULL column was given nothing.
+
+    Rare from a typed model —`SnakeColumn[int]` refuses a `None` long before any driver sees it— and
+    that is exactly why it is here: it arrives from what the type system does not cover, such as raw
+    SQL or a column a migration added.
+    """
+
+
+class SnakeCheckViolation(SnakeIntegrityError):
+    """A CHECK constraint said no.
+
+    The one that proves the classification cannot key on the driver's exception CLASS: MySQL raises
+    `OperationalError` for this and `IntegrityError` for the other three.
+    """
+
+
+class SnakeUnsupportedFeature(SnakeError, ValueError):
+    """The combination asked for exists in the design but is not built yet."""
+
+
+class SnakeDialectError(SnakeError, ValueError):
+    """The dialect does not know how to translate something (a Python type, a SQL literal)."""
+
+
+class SnakeMigrationError(SnakeError, ValueError):
+    """Trouble with the migration history on disk: duplicated numbering, gaps, a file that does not
+    expose `migration`, or a migration that fails while being applied without transactional DDL
+    (leaving the DB half done)."""
+
+
+class SnakeEmitError(SnakeError, ValueError):
+    """Valid SQL cannot be emitted from what was given (an INSERT with no columns...)."""
+
+
+class SnakeNodeError(SnakeError, TypeError):
+    """The emitter received an AST node it does not know how to translate into SQL."""
+
+
+class SnakeValueError(SnakeError, ValueError):
+    """A value does not fit its declared column (e.g. a `Decimal` with more decimals than the
+    `scale`). Raised on WRITE, before touching the DB, so the engine does not round it or store it
+    half-way silently."""
+
+
+class SnakeDtoError(SnakeError, ValueError):
+    """A generated DTO cannot be honoured: its declaration is contradictory, it names a column the
+    model does not have, or the file it has to be written into holds something the generator does
+    not manage. It is raised at DECLARATION time whenever it can be, so the mistake dies where it
+    was written and never becomes a body that quietly lost a column."""
+
+
+class SnakeWarning(UserWarning):
+    """An ORM warning that does not stop you, but is worth seeing: a bulk write that fires no
+    signals, or an engine with less fidelity than another. It inherits from `UserWarning` so that
+    `filterwarnings("ignore", category=SnakeWarning)` silences ONLY the ORM's."""

snakeorm/core/placement.py

@@ -0,0 +1,15 @@
+"""The two axes that place a table: in WHICH database and in WHICH schema (their defaults).
+
+No imports on purpose: half the codebase reads it (metadata, compiler, decorators, migrations,
+CLI), so any import of its own would be a cycle — and putting it in `config.py` would drag `dotenv`
+into everyone who touches a table.
+"""
+
+from __future__ import annotations
+
+DEFAULT_SCHEMA = "public"
+"""A table's default schema. Postgres's; SQLite ignores it (it has no schemas)."""
+
+DEFAULT_DATABASE = "default"
+"""The default connection. Resolved through `DATABASE_URL`/`SNAKEORM_DSN`/`DB_*`; every other one
+through `SNAKEORM_DSN_<NAME>`."""

snakeorm/core/sentinels.py

@@ -0,0 +1,37 @@
+"""Sentinels the whole package shares. One module, so no two of them mean the same thing.
+
+A sentinel is worth a module of its own for a reason `None` explains: `None` is a VALUE a column may
+legitimately hold, so it cannot also mean "there is nothing here". These do not collide with any
+value a database can return.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+
+class _NotLoaded:
+    """The type of `NOT_LOADED`. A class rather than `object()` so the `repr` says what it is."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "<not loaded>"
+
+    def __bool__(self) -> bool:
+        """Falsy, and deliberately so: `if row.column` on an unloaded one must not read as a value.
+
+        It never reaches user code through the descriptor —that raises— but it does sit in the
+        instance's `__dict__`, where a `vars(row)` or a debugger will meet it.
+        """
+        return False
+
+
+NOT_LOADED: Final[Any] = _NotLoaded()
+"""Written by hydration into every column a query left out (`only()` / `defer()`).
+
+Typed `Any` on purpose: it is assigned into slots declared as `str`, `int` or whatever the column is,
+and the checker has no way to express "this is that type or the sentinel" without infecting every
+column's type with a union the user would then have to narrow. The guarantee is upheld at RUNTIME by
+the descriptor, which raises rather than ever handing this out.
+"""

snakeorm/core/signals.py

@@ -0,0 +1,114 @@
+"""CODE signals: `PRE_SAVE` / `POST_SAVE` / `PRE_DELETE` / `POST_DELETE`.
+
+The difference from `snake_trigger` (one of GUARANTEE, not of implementation): a trigger lives in
+the schema and always holds; a signal lives in the app and only fires if the write goes through the
+session —which is why it NEVER guarantees integrity; if it must always hold, it is a trigger. The
+handlers run INSIDE the transaction: if one raises, the write is undone.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from enum import Enum
+from typing import TypeVar
+
+from snakeorm.core.exceptions import SnakeWarning
+
+T = TypeVar("T")
+
+Handler = Callable[[object], None]
+"""A handler receives the instance and returns nothing."""
+
+
+class SnakeSignal(Enum):
+    """The moment a handler fires relative to the write."""
+
+    PRE_SAVE = "pre_save"
+    POST_SAVE = "post_save"
+    PRE_DELETE = "pre_delete"
+    POST_DELETE = "post_delete"
+
+
+_HANDLERS: dict[tuple[type, SnakeSignal], list[Handler]] = {}
+"""Connected handlers, by (model, signal). Module-global, like the registry."""
+
+
+def snake_on(
+    model: type[T], signal: SnakeSignal
+) -> Callable[[Callable[[T], None]], Callable[[T], None]]:
+    """Connects a handler to a model's signal. Returns the function untouched.
+
+        @snake_on(Order, SnakeSignal.POST_SAVE)
+        def notify(order: Order) -> None:
+            ...
+
+    The handler receives the instance with the model's TYPE (to the checker it is a `Order`, not
+    `Any`).
+    """
+
+    def decorator(handler: Callable[[T], None]) -> Callable[[T], None]:
+        connect(model, signal, handler)
+        return handler
+
+    return decorator
+
+
+def connect(model: type[T], signal: SnakeSignal, handler: Callable[[T], None]) -> None:
+    """Connects a handler without the decorator (handy for connecting at runtime)."""
+    _HANDLERS.setdefault((model, signal), []).append(handler)  # type: ignore[arg-type]
+
+
+def disconnect_all(model: type | None = None) -> None:
+    """Disconnects a model's handlers, or ALL of them if none is given (mostly for tests: the
+    dictionary is global and a handler left in place contaminates the ones that follow)."""
+    if model is None:
+        _HANDLERS.clear()
+        return
+    for key in [key for key in _HANDLERS if key[0] is model]:
+        del _HANDLERS[key]
+
+
+def signals_of(model: type) -> tuple[SnakeSignal, ...]:
+    """The signals that model has connected. The bulk-write warning uses it."""
+    return tuple(
+        sorted(
+            {key[1] for key in _HANDLERS if key[0] is model and _HANDLERS[key]},
+            key=lambda signal: signal.value,
+        )
+    )
+
+
+def models_with_signals() -> tuple[type, ...]:
+    """The models that have any signal connected. The `check` command lists them."""
+    return tuple({key[0] for key in _HANDLERS if _HANDLERS[key]})
+
+
+def emit(model: type, signal: SnakeSignal, instance: object) -> None:
+    """Fires the handlers of `(model, signal)` in connection order.
+
+    Exceptions are deliberately not caught: if a handler fails, the write must be undone with it.
+    """
+    for handler in _HANDLERS.get((model, signal), ()):
+        handler(instance)
+
+
+def warn_bulk_skips_signals(model: type, operation: str) -> None:
+    """Warns that a BULK write is not going to fire the model's signals.
+
+    Neither an error (bulk writing is legitimate) nor silence (the `queryset.update()` trap in
+    Django): the bulk path resolves the UPDATE in the engine without fetching the rows, and firing
+    them would force a SELECT of N rows — the very N+1 the rest of the ORM avoids. So we warn.
+    """
+    signals = signals_of(model)
+    if not signals:
+        return
+    names = ", ".join(signal.value for signal in signals)
+    warnings.warn(
+        f"{operation}() over '{model.__name__}' does NOT fire its signals ({names}): a bulk write "
+        f"is resolved by the engine without fetching the rows. If that logic has to run here, walk "
+        f"the rows and use update()/delete() on each one; if it has to hold ALWAYS — outside the ORM "
+        f"too — move it into a trigger.",
+        SnakeWarning,
+        stacklevel=3,
+    )

snakeorm/debug/__init__.py

@@ -0,0 +1,42 @@
+"""DEBUG subsystem: it captures the SQL that runs and delivers it readable. A core that is AGNOSTIC of the web framework.
+
+It captures the queries (a driver decorator + a per-scope collector), normalises them into a `DebugReport` and offers several renderers of that same report. The web adapters live in `snakeorm.contrib.*` and only CONSUME this.
+"""
+
+from snakeorm.debug.channel import DEBUG_ENV_KEY as DEBUG_ENV_KEY
+from snakeorm.debug.config import PRODUCTION_ENV_KEY as PRODUCTION_ENV_KEY
+from snakeorm.debug.channel import CHANNEL_AUDIENCE as CHANNEL_AUDIENCE
+from snakeorm.debug.channel import ChannelAudience as ChannelAudience
+from snakeorm.debug.channel import RISKY_CHANNELS as RISKY_CHANNELS
+from snakeorm.debug.channel import (
+    demand_every_channel_classified as demand_every_channel_classified,
+)
+from snakeorm.debug.channel import (
+    UNIMPLEMENTED_CHANNELS as UNIMPLEMENTED_CHANNELS,
+)
+from snakeorm.debug.channel import SnakeDebugChannel as SnakeDebugChannel
+from snakeorm.debug.channel import channels_from_env as channels_from_env
+from snakeorm.debug.channel import parse_channels as parse_channels
+from snakeorm.debug.config import ADVISE_MS_ENV_KEY as ADVISE_MS_ENV_KEY
+from snakeorm.debug.config import LANG_ENV_KEY as LANG_ENV_KEY
+from snakeorm.debug.config import SnakeDebugConfig as SnakeDebugConfig
+from snakeorm.debug.config import SnakeDebugLanguage as SnakeDebugLanguage
+from snakeorm.debug.matrix import SnakeWebFramework as SnakeWebFramework
+from snakeorm.debug.matrix import channels_without_effect as channels_without_effect
+from snakeorm.debug.matrix import warn_unimplemented as warn_unimplemented
+from snakeorm.debug.matrix import warn_unsupported as warn_unsupported
+from snakeorm.debug.testing import assert_queries as assert_queries
+from snakeorm.debug.capture import AsyncCaptureDriver as AsyncCaptureDriver
+from snakeorm.debug.capture import CaptureDriver as CaptureDriver
+from snakeorm.debug.collector import DebugCollector as DebugCollector
+from snakeorm.debug.collector import capture_queries as capture_queries
+from snakeorm.debug.collector import current_collector as current_collector
+from snakeorm.debug.html import render_report_html as render_report_html
+from snakeorm.debug.html import render_report_page as render_report_page
+from snakeorm.debug.record import QueryKind as QueryKind
+from snakeorm.debug.record import QueryOrigin as QueryOrigin
+from snakeorm.debug.record import QueryRecord as QueryRecord
+from snakeorm.debug.report import DebugReport as DebugReport
+from snakeorm.debug.report import DuplicateGroup as DuplicateGroup
+from snakeorm.debug.report import RequestInfo as RequestInfo
+from snakeorm.debug.otel import export_report as export_report