snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/decorators/model.py

@@ -0,0 +1,268 @@
+"""The @snake_model decorator: it turns a class into a compiled model."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar, dataclass_transform, overload
+
+from snakeorm.compiler import compile_model
+from snakeorm.core.placement import DEFAULT_SCHEMA
+from snakeorm.core.exceptions import SnakeModelError
+from snakeorm.core.sentinels import NOT_LOADED
+from snakeorm.fields import (
+    SnakeColumn,
+    snake_auto,
+    snake_column,
+    snake_datetime,
+    snake_datetimetz,
+    snake_float,
+    snake_time,
+    snake_timetz,
+    snake_decimal,
+    snake_discriminator,
+    snake_enum,
+    snake_int,
+    snake_json,
+    snake_str,
+    snake_to_many,
+    snake_to_many_through,
+    snake_to_one,
+)
+from snakeorm.helpers.inheritance import collect_inherited
+from snakeorm.metadata import SnakeTableInfo
+from snakeorm.decorators.polymorphic import guard_child_columns, resolve_polymorphic
+from snakeorm.registry import SnakeRegistry
+from snakeorm.registry import registry as default_registry
+
+T = TypeVar("T")
+
+
+def _make_init(cls: type, discriminator: tuple[str, str] | None = None) -> Any:
+    """Generate a keyword-only __init__ that assigns each column through its descriptor.
+
+    It is built by hand because @dataclass would take the descriptors as defaults. `discriminator`
+    is the `(column, value)` pair of a polymorphic subclass: the column is excluded from the
+    constructor (the CLASS decides its value, like an autoincrement) and gets filled in here. The
+    value travels in the closure, not in global state, because the source of truth is already
+    `table.polymorphic.value`.
+    """
+    # It walks the MRO (base→child): the child's __init__ also demands/fills the columns inherited
+    # from an abstract base, not only its own.
+    columns = list(collect_inherited(cls, SnakeColumn).items())
+    discriminator_column = discriminator[0] if discriminator is not None else None
+    discriminator_value = discriminator[1] if discriminator is not None else None
+
+    def __init__(self: Any, **kwargs: Any) -> None:
+        for attr, descriptor in columns:
+            if descriptor.column_name == discriminator_column:
+                setattr(self, attr, discriminator_value)
+                continue
+            if descriptor.autoincrement or descriptor.has_server_default:
+                continue  # excluded from the constructor (the DB supplies it); not an argument
+            if attr in kwargs:
+                setattr(self, attr, kwargs.pop(attr))
+            elif descriptor.has_default:
+                setattr(self, attr, descriptor.default)
+            elif descriptor.default_factory is not None:
+                setattr(
+                    self, attr, descriptor.default_factory()
+                )  # a fresh value per instance
+            else:
+                raise TypeError(f"{cls.__name__}() missing required argument: '{attr}'")
+        if kwargs:
+            raise TypeError(f"{cls.__name__}() unexpected arguments: {sorted(kwargs)}")
+
+    return __init__
+
+
+_UNSET = "<unassigned>"
+_NOT_LOADED_LABEL = "<not loaded>"
+"""What a column the query deliberately left out prints as. A repr must never raise."""
+_MISSING = object()
+"""Sentinel for "the storage key is not there at all", which is not the same as "left out"."""
+
+
+def _install_dunders(cls: type, reg: SnakeRegistry) -> None:
+    """Install `__repr__`, `__eq__` and `__hash__` by reading the PK off the already compiled GRAPH.
+
+    Equality goes by PRIMARY KEY, not by value: two objects of the same row are the same row even
+    if one of them is stale. The columns come from `SnakePrimaryKeyInfo.columns` (not from a magic
+    `pk`), so a composite PK works with the SAME code.
+    """
+    table = reg.table_of(cls)
+    if table is None:  # pragma: no cover - defensive: the decorator just registered it
+        return
+    column_attrs = tuple(column.attr_name or column.name for column in table.columns)
+    pk_attrs = tuple(
+        column.attr_name or column.name for column in table.primary_key.columns
+    )
+
+    def _pk_values(instance: object) -> tuple[object, ...] | None:
+        """The PK values, or None if there is no row identity to read.
+
+        It returns None in two cases: a table WITHOUT a PK (a `@snake_db_first` mirror, which falls
+        back to identity) and a table WITH a PK not yet set (an object that has not been inserted).
+        The first case is the critical one: without it, an empty `pk_attrs` would return `()` and
+        any two rows would compare equal → data loss inside a `set`.
+        """
+        if not pk_attrs:
+            return None
+        values: list[object] = []
+        for attr in pk_attrs:
+            if not hasattr(instance, f"__snake_{attr}"):
+                return None
+            values.append(getattr(instance, attr))
+        return tuple(values)
+
+    def _printable(instance: object, attr: str) -> str:
+        """One field of the repr. THREE states, the same three the descriptor tells apart.
+
+        Reading an unloaded column RAISES, which is the feature, and `__repr__` used to inherit that
+        raise: printing a narrowed row killed the inspection it was part of. So the sentinel is read
+        off the storage key here rather than through the descriptor.
+        """
+        stored = getattr(instance, f"__snake_{attr}", _MISSING)
+        if stored is _MISSING:
+            # A half-built object is STILL printable (useful right before the INSERT).
+            return f"{attr}={_UNSET}"
+        if stored is NOT_LOADED:
+            return f"{attr}={_NOT_LOADED_LABEL}"
+        return f"{attr}={getattr(instance, attr)!r}"
+
+    def __repr__(self: object) -> str:
+        fields = ", ".join(_printable(self, attr) for attr in column_attrs)
+        return f"{type(self).__name__}({fields})"
+
+    def __eq__(self: object, other: object) -> bool:
+        if type(self) is not type(other):
+            return NotImplemented
+        mine, theirs = _pk_values(self), _pk_values(other)
+        if mine is None or theirs is None:
+            # Without a PK there is no row identity to compare: it falls back to object identity.
+            return self is other
+        return mine == theirs
+
+    def __hash__(self: object) -> int:
+        # A table WITHOUT a PK (a legacy mirror): hashable by IDENTITY; nothing the INSERT fills in
+        # later, so the hash cannot mutate.
+        if not pk_attrs:
+            return object.__hash__(self)
+        values = _pk_values(self)
+        if values is None:
+            raise TypeError(
+                f"{type(self).__name__} is not hashable until it has a primary key: its hash "
+                f"would come from the PK, and the INSERT would fill it in afterwards MUTATING the "
+                f"hash inside whatever set or dict it was sitting in. Insert it first."
+            )
+        return hash((type(self).__name__, values))
+
+    for name, value in (
+        ("__repr__", __repr__),
+        ("__eq__", __eq__),
+        ("__hash__", __hash__),
+    ):
+        setattr(cls, name, value)
+
+
+@overload
+def snake_model(cls: type[T]) -> type[T]: ...
+@overload
+def snake_model(
+    *,
+    table: str | None = ...,
+    prefix: str | None = ...,
+    schema: str = ...,
+    database: str = ...,
+    discriminator_value: str | None = ...,
+    registry: SnakeRegistry = ...,
+) -> Callable[[type[T]], type[T]]: ...
+
+
+# A LITERAL tuple as PEP 681 demands; tied to SNAKE_FIELD_SPECIFIERS by a test.
+@dataclass_transform(
+    kw_only_default=True,
+    field_specifiers=(
+        snake_column,
+        snake_auto,
+        snake_enum,
+        snake_int,
+        snake_str,
+        snake_decimal,
+        snake_datetime,
+        snake_datetimetz,
+        snake_float,
+        snake_time,
+        snake_timetz,
+        snake_json,
+        snake_to_one,
+        snake_to_many,
+        snake_to_many_through,
+        snake_discriminator,
+    ),
+)
+def snake_model(
+    cls: type[T] | None = None,
+    *,
+    table: str | None = None,
+    prefix: str | None = None,
+    schema: str = DEFAULT_SCHEMA,
+    database: str = "default",
+    discriminator_value: str | None = None,
+    registry: SnakeRegistry = default_registry,
+) -> Any:
+    """Compile the model, store its SnakeTableInfo and install the __init__ at runtime.
+
+    It is used bare (`@snake_model`) or parametric. The table name is `{prefix}_{table}`: `table=`
+    changes only the table (keeping the prefix), `prefix=` changes the namespace.
+
+    A `snake_discriminator()` column opens a POLYMORPHIC hierarchy: the whole family shares this
+    table and that column says what each row is. The children inherit it in Python and declare
+    their `discriminator_value=`; they do not pick a table, because there is none to pick.
+
+    ```python
+    @snake_model(table="animals")
+    class Animal(SnakeModel):
+        id: SnakeColumn[int] = snake_auto()
+        kind: SnakeColumn[str] = snake_discriminator()
+
+    @snake_model(discriminator_value="dog")
+    class Dog(Animal):
+        breed: SnakeColumn[str | None] = snake_str()
+    ```
+
+    There is no `inherits=Animal`: Python inheritance ALREADY says who the base is (it avoids a
+    second source).
+    """
+
+    def wrap(klass: type[T]) -> type[T]:
+        placement = resolve_polymorphic(klass, discriminator_value, registry)
+        compiled = compile_model(
+            klass,
+            # A polymorphic child does NOT pick a table: it shares its base's, and name, schema
+            # and connection all come from there.
+            table=placement.table if placement.table is not None else table,
+            prefix=None if placement.table is not None else prefix,
+            schema=placement.schema if placement.schema is not None else schema,
+            database=placement.database if placement.database is not None else database,
+            polymorphic=placement.info,
+        )
+        # The guard operates on the ALREADY compiled table (without recompiling).
+        guard_child_columns(klass, compiled, placement)
+        registry.register(klass, compiled)
+        # The model remembers WHICH registry it lives in: typed navigation resolves relations
+        # against THAT registry, not the global one. Without this, `@snake_model(registry=reg)`
+        # broke `User.car.brand`.
+        setattr(klass, "__snake_registry__", registry)
+        setattr(klass, "__init__", _make_init(klass, placement.constructor_fills()))
+        _install_dunders(klass, registry)
+        return klass
+
+    return wrap if cls is None else wrap(cls)
+
+
+def snake_table(cls: type, reg: SnakeRegistry = default_registry) -> SnakeTableInfo:
+    """Return the compiled SnakeTableInfo of a @snake_model model."""
+    table = reg.table_of(cls)
+    if table is None:
+        raise SnakeModelError(f"{cls.__name__} is not a @snake_model.")
+    return table

snakeorm/decorators/polymorphic.py

@@ -0,0 +1,140 @@
+"""Resolving a polymorphic hierarchy: who the base is, which table they share and what is banned.
+
+All the judgement about polymorphic inheritance lives HERE (not scattered across the decorator, the
+compiler and the linker) so that it cannot decide differently in each place. Python's MRO says who
+the base is; there is no `inherits=Animal` because that would be a second source of truth next to
+`class Dog(Animal)`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from snakeorm.core.exceptions import SnakeModelDefinitionError
+from snakeorm.metadata import SnakePolymorphicInfo, SnakeTableInfo
+from snakeorm.registry import SnakeRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class PolymorphicPlacement:
+    """Where a class of the hierarchy lives: its inherited table, its role and its base.
+
+    `table`/`schema`/`database` are `None` when the class is NOT a polymorphic child: "I impose
+    nothing, the decorator decides with its usual parameters".
+    """
+
+    info: SnakePolymorphicInfo | None = None
+    table: str | None = None
+    schema: str | None = None
+    database: str | None = None
+    base: type | None = None
+    inherited: frozenset[str] = frozenset()
+    """Column names the child inherits from the base, so we know which ones are ITS OWN.
+
+    They get captured here because whoever resolves the hierarchy already had the base's table in
+    hand.
+    """
+
+    def constructor_fills(self) -> tuple[str, str] | None:
+        """The `(column, value)` pair the `__init__` must fill in by itself. `None` if it does not
+        apply.
+
+        It lives here, not in the decorator, so it is not recomposed from two loose fields and put
+        at risk of getting it wrong.
+        """
+        if self.info is None or self.info.value is None:
+            return None
+        return (self.info.column, self.info.value)
+
+
+def discriminator_column(cls: type) -> str | None:
+    """The SQL name of the column marked with `snake_discriminator()`, if there is one.
+
+    It is read from the MODEL (there is no `discriminator="kind"` in the decorator): it avoids a
+    second source, and only the field specifier can carry the `init: Literal[False]` that lines
+    mypy/pyright up with the runtime.
+    """
+    from snakeorm.fields import SnakeColumn
+    from snakeorm.helpers.inheritance import collect_inherited
+
+    for descriptor in collect_inherited(cls, SnakeColumn).values():
+        if descriptor.is_discriminator:
+            return descriptor.column_name
+    return None
+
+
+def resolve_polymorphic(
+    cls: type,
+    discriminator_value: str | None,
+    registry: SnakeRegistry,
+) -> PolymorphicPlacement:
+    """Decide this class's role in a hierarchy, or that it is in none.
+
+    1. Without `snake_discriminator()` nor `discriminator_value` → there is no hierarchy.
+    2. With its own `snake_discriminator()` → it is the BASE. The table is its own.
+    3. With `discriminator_value` → it is a CHILD. It looks the base up in the MRO and inherits its
+       whole table.
+    """
+    if discriminator_value is None:
+        column = discriminator_column(cls)
+        if column is None:
+            return PolymorphicPlacement()
+        return PolymorphicPlacement(info=SnakePolymorphicInfo(column=column))
+
+    base, base_table = _find_base(cls, registry)
+    assert base_table.polymorphic is not None  # _find_base guarantees it
+    return PolymorphicPlacement(
+        info=SnakePolymorphicInfo(
+            column=base_table.polymorphic.column, value=discriminator_value
+        ),
+        table=base_table.name,
+        schema=base_table.schema,
+        database=base_table.database,
+        base=base,
+        inherited=frozenset(column.name for column in base_table.columns),
+    )
+
+
+def _find_base(cls: type, registry: SnakeRegistry) -> tuple[type, SnakeTableInfo]:
+    """The class of the hierarchy, looked up in the MRO. The FIRST one that opened one wins.
+
+    It walks the class's MRO upwards. In a deep hierarchy the nearest ancestor wins, but its
+    `polymorphic.column` is the same as the root's: the answer does not depend on the level, so a
+    deep hierarchy is not a special case.
+    """
+    for ancestor in cls.__mro__[1:]:
+        table = registry.table_of(ancestor)
+        if table is not None and table.polymorphic is not None:
+            return ancestor, table
+    raise SnakeModelDefinitionError(
+        f"{cls.__name__} declares `discriminator_value`, but none of its base classes opens a "
+        f"polymorphic hierarchy. Add `discriminator='<column>'` to the `@snake_model` of the base, "
+        f"and make sure {cls.__name__} inherits from it in Python."
+    )
+
+
+def guard_child_columns(
+    cls: type, compiled: SnakeTableInfo, placement: PolymorphicPlacement
+) -> None:
+    """A child's OWN columns have to be nullable.
+
+    The whole hierarchy shares ONE table, so `Dog`'s `breed` column also exists in `Cat`'s rows,
+    where there is no value: a `NOT NULL` would make inserting a cat impossible. It gets checked at
+    declaration time (fixable with `| None`), not when inserting in production. It operates on the
+    ALREADY compiled table, without recompiling.
+    """
+    if placement.base is None:  # not a polymorphic child: there is nothing to check
+        return
+    not_nullable = [
+        column.name
+        for column in compiled.columns
+        if column.name not in placement.inherited and not column.nullable
+    ]
+    if not_nullable:
+        raise SnakeModelDefinitionError(
+            f"The columns that belong to {cls.__name__} itself have to accept NULL, and "
+            f"{not_nullable} do not. The whole hierarchy shares the table of "
+            f"{placement.base.__name__}, so those "
+            f"columns also exist in the rows of its siblings, where there is nothing to put in "
+            f"them. Declare them as `SnakeColumn[T | None]`."
+        )

snakeorm/decorators/result.py

@@ -0,0 +1,167 @@
+"""The @snake_result decorator: a TYPED result container for `session.annotate()`.
+
+You declare a class that inherits from `SnakeResult[Model]`: EXACTLY one field is the
+`@snake_model` model (the base row, = the generic parameter) and the rest are scalars.
+`@dataclass_transform` types its `__init__`.
+
+```python
+@snake_result
+class RealmStats(SnakeResult[Realm]):
+    realm: Realm          # the base row (a @snake_model), matching the SnakeResult[Realm] parameter
+    forge_count: int      # an aggregate
+    avg_size: float
+```
+
+Inheriting from `SnakeResult[Model]` serves to (a) reject in the checker a class that does not
+inherit and give `annotate` the concrete return type (`list[RealmStats]`), and (b) validate at
+runtime that the generic matches the base field and that the query is over that model.
+
+A typing NOTE: the STATIC tie between query and base model (catching
+`annotate(query_of_AnotherModel, RealmStats)`) is NOT expressible under `annotate(query, result)`:
+it would demand a dependent bound `R <: SnakeResult[T]`, and `TypeVar` bounds cannot be generic
+(mypy and pyright both reject it). That is why that mismatch stays as a runtime validation
+(`SnakeEmitError`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    Generic,
+    TypeVar,
+    dataclass_transform,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from snakeorm.helpers.annotations import unwrap_optional
+from snakeorm.core.exceptions import SnakeModelDefinitionError
+from snakeorm.registry import registry
+
+T = TypeVar("T")
+TModel = TypeVar("TModel")
+
+# The key where the compiled SnakeResultInfo is stored on the decorated class.
+_RESULT_INFO_KEY = "__snake_result__"
+
+
+class SnakeResult(Generic[TModel]):
+    """Generic base of a `@snake_result` container; the parameter is the base model (the row).
+
+    A typing marker with no runtime (see the module note). `TModel` MUST match the base field
+    declared in the subclass (`@snake_result` verifies it).
+    """
+
+    __slots__ = ()
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeResultInfo:
+    """Compiled metadata of a `@snake_result`: the base row and the scalars, in order.
+
+    `scalars` preserves the declaration order: the session projects the aggregates in that order
+    behind the columns of the base model.
+    """
+
+    base_field: str
+    base_model: type
+    scalars: tuple[tuple[str, type], ...]
+
+
+@dataclass_transform()
+def snake_result(cls: type[T]) -> type[T]:
+    """Compile the class into a typed result container and install its `__init__` (a dataclass).
+
+    The ONLY annotation that is a `@snake_model` is the base row; the rest are scalars. A scalar
+    `X | None` compiles to `X` (the correct declaration for SUM/AVG/MIN/MAX, NULL over zero rows;
+    the unwrapped type is the key of the coercion converter, and `coerce` does not touch nulls).
+
+    It fails with `SnakeModelDefinitionError` if: there are 0 or 2+ base models; it does not
+    inherit from `SnakeResult[Model]`; it inherits without parametrising; or the generic does not
+    match the base field.
+    """
+    if not (isinstance(cls, type) and issubclass(cls, SnakeResult)):
+        raise SnakeModelDefinitionError(
+            f"{cls.__name__} does not inherit from SnakeResult[Model]: a @snake_result has to be "
+            f"declared as `class {cls.__name__}(SnakeResult[YourModel])` so that "
+            f"session.annotate(...) accepts it and returns a typed list."
+        )
+
+    hints = get_type_hints(cls)
+    base_fields: list[tuple[str, type]] = []
+    scalars: list[tuple[str, type]] = []
+    for name, annotation in hints.items():
+        declared, _ = unwrap_optional(annotation)
+        if isinstance(declared, type) and registry.table_of(declared) is not None:
+            base_fields.append((name, declared))
+        else:
+            scalars.append((name, declared))
+
+    if len(base_fields) > 1:
+        names = ", ".join(name for name, _ in base_fields)
+        raise SnakeModelDefinitionError(
+            f"{cls.__name__} declares {len(base_fields)} base models ({names}); a @snake_result "
+            f"has to have EXACTLY one. The expected shape: one @snake_model field (the base row) "
+            f"and the rest scalars (int, float, str...)."
+        )
+    if not base_fields:
+        raise SnakeModelDefinitionError(
+            f"{cls.__name__} declares not a single base model: there is nothing to annotate. A "
+            f"@snake_result needs EXACTLY one @snake_model field (the base row) plus the "
+            f"scalars that session.annotate(...) will fill in."
+        )
+
+    base_field, base_model = base_fields[0]
+    _validate_generic_parameter(cls, base_field, base_model)
+    info = SnakeResultInfo(
+        base_field=base_field, base_model=base_model, scalars=tuple(scalars)
+    )
+    result_cls = dataclass(cls)
+    setattr(result_cls, _RESULT_INFO_KEY, info)
+    return result_cls
+
+
+def _validate_generic_parameter(cls: type, base_field: str, base_model: type) -> None:
+    """Check that the subclass's `SnakeResult[Model]` matches the `@snake_model` base field.
+
+    It reads the generic off `__orig_bases__`. It fails if it was inherited without parametrising
+    or if the model is not the one of the base field: the static type and the runtime metadata
+    must tell the same story.
+    """
+    declared = _declared_base_model(cls)
+    if declared is _UNPARAMETRIZED:
+        raise SnakeModelDefinitionError(
+            f"{cls.__name__} inherits SnakeResult without the base model; declare "
+            f"`SnakeResult[{base_model.__name__}]` so that the type matches field '{base_field}'."
+        )
+    if declared is not base_model:
+        declared_name = getattr(declared, "__name__", repr(declared))
+        raise SnakeModelDefinitionError(
+            f"{cls.__name__} inherits SnakeResult[{declared_name}], but its base field "
+            f"'{base_field}' is {base_model.__name__}: they do not match. The generic parameter "
+            f"has to be the SAME model as the base row."
+        )
+
+
+# A sentinel to tell "SnakeResult without parameters" apart from a parameter that does exist.
+_UNPARAMETRIZED = object()
+
+
+def _declared_base_model(cls: type) -> object:
+    """Model of the bases' `SnakeResult[Model]` parameter; `_UNPARAMETRIZED` if there is none."""
+    for base in getattr(cls, "__orig_bases__", ()):
+        if get_origin(base) is SnakeResult:
+            args = get_args(base)
+            return args[0] if args else _UNPARAMETRIZED
+    return _UNPARAMETRIZED
+
+
+def snake_result_info(cls: type) -> SnakeResultInfo:
+    """Return the compiled SnakeResultInfo of a `@snake_result` class; fail if it is not one."""
+    info = getattr(cls, _RESULT_INFO_KEY, None)
+    if not isinstance(info, SnakeResultInfo):
+        raise SnakeModelDefinitionError(
+            f"{cls.__name__} is not a @snake_result: it cannot be used in session.annotate(...)."
+        )
+    return info

snakeorm/decorators/row.py

@@ -0,0 +1,90 @@
+"""The @snake_row decorator: a typed ROW container for `session.call(...)`.
+
+A function/procedure is OPAQUE SQL: the ORM cannot verify what it returns. The contract is
+DECLARED, not verified: the user declares the expected shape (a @snake_row whose fields are ALL
+scalars) and the session hydrates each row into it (the same guarantee as reading a raw SELECT into
+a dataclass).
+
+```python
+@snake_row
+class Payroll(SnakeRow):
+    employee_id: int
+    gross: Decimal
+    net: Decimal
+
+rows: list[Payroll] = session.call("calculate_payroll", [1234], into=Payroll)
+```
+
+The difference with `@snake_result`: this one has NO base model, all its fields are scalars.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypeVar, dataclass_transform, get_type_hints
+
+from snakeorm.helpers.annotations import unwrap_optional
+from snakeorm.core.exceptions import SnakeModelDefinitionError
+
+T = TypeVar("T")
+
+# The key where the compiled SnakeRowInfo is stored on the decorated class.
+_ROW_INFO_KEY = "__snake_row__"
+
+
+class SnakeRow:
+    """Marker base for a `@snake_row`: a container of scalar rows, WITHOUT a base model.
+
+    A typing marker with no runtime: `session.call` bounds its `into` to `type[R]` with
+    `R: SnakeRow`, so a class that does not inherit from here is rejected IN THE CHECKER.
+    """
+
+    __slots__ = ()
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeRowInfo:
+    """Compiled metadata of a `@snake_row`: its columns (name + type), in order.
+
+    `columns` preserves the declaration order: `session.call` maps each row by POSITION (field
+    order == column order of the function).
+    """
+
+    columns: tuple[tuple[str, type], ...]
+
+
+@dataclass_transform()
+def snake_row(cls: type[T]) -> type[T]:
+    """Compile the class into a typed row container and install its `__init__` (a dataclass).
+
+    A field `X | None` compiles to `X` (the key of the coercion converter; the `None` survives
+    because `coerce` does not touch nulls). It fails with `SnakeModelDefinitionError` if it does
+    not inherit from `SnakeRow`.
+    """
+    if not (isinstance(cls, type) and issubclass(cls, SnakeRow)):
+        raise SnakeModelDefinitionError(
+            f"{cls.__name__} does not inherit from SnakeRow: a @snake_row has to be declared as "
+            f"`class {cls.__name__}(SnakeRow)` so that session.call(...) accepts it and returns "
+            f"a typed list."
+        )
+
+    hints = get_type_hints(cls)
+    columns: list[tuple[str, type]] = []
+    for name, annotation in hints.items():
+        declared, _ = unwrap_optional(annotation)
+        columns.append((name, declared))
+
+    info = SnakeRowInfo(columns=tuple(columns))
+    row_cls = dataclass(cls)
+    setattr(row_cls, _ROW_INFO_KEY, info)
+    return row_cls
+
+
+def snake_row_info(cls: type) -> SnakeRowInfo:
+    """Return the compiled SnakeRowInfo of a `@snake_row` class; fail if it is not one."""
+    info = getattr(cls, _ROW_INFO_KEY, None)
+    if not isinstance(info, SnakeRowInfo):
+        raise SnakeModelDefinitionError(
+            f"{cls.__name__} is not a @snake_row: it cannot be used in session.call(...)."
+        )
+    return info