snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/expressions/scalar.py

@@ -0,0 +1,293 @@
+"""Scalar text and date functions (`LOWER`, `TRIM`, `DATE_TRUNC`, `EXTRACT`...).
+
+A single node (`SnakeFunc`) with an agnostic enum instead of one class per function: a new node
+would be one more place to forget something. The dialect translates the names. The TYPE is pinned
+down by the constructors (`snake_length(User.name)` is `SnakeValue[int]`), typing the projection
+with no `Any`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, TypeVar
+
+from snakeorm.core.exceptions import SnakeUnsupportedFeature
+from snakeorm.expressions.expression import CASTABLE, SnakeCast, SnakeValue
+
+T = TypeVar("T")
+V = TypeVar("V")
+
+
+class SnakeFunc(Enum):
+    """Supported scalar functions, with agnostic names that the dialect translates."""
+
+    LOWER = "lower"
+    UPPER = "upper"
+    TRIM = "trim"
+    LENGTH = "length"
+    CONCAT = "concat"
+    DATE_TRUNC = "date_trunc"
+    EXTRACT = "extract"
+    ABS = "abs"
+    ROUND = "round"
+    SUBSTRING = "substring"
+    REPLACE = "replace"
+    CEIL = "ceil"
+    FLOOR = "floor"
+    SQRT = "sqrt"
+    POWER = "power"
+
+
+class SnakeDatePart(Enum):
+    """A part of a date, for `DATE_TRUNC` and `EXTRACT`. Standard SQL names."""
+
+    YEAR = "year"
+    QUARTER = "quarter"
+    MONTH = "month"
+    WEEK = "week"
+    DAY = "day"
+    HOUR = "hour"
+    MINUTE = "minute"
+    SECOND = "second"
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class SnakeFuncCall(SnakeValue[T]):
+    """A call to a scalar function: `FUNC(arg, ...)`.
+
+    It is a VALUE (it gets compared, projected, aggregated). `part` is only used by the date
+    functions and travels separately (in SQL, `EXTRACT(year FROM col)` is not a normal argument).
+    """
+
+    func: SnakeFunc
+    arguments: tuple[SnakeValue[object] | object, ...]
+    part: SnakeDatePart | None = None
+
+    def paths(self) -> tuple[tuple[str, ...], ...]:
+        """Paths of the arguments that are columns, so the planner sees their JOINs."""
+        return tuple(
+            path
+            for argument in self.arguments
+            if isinstance(argument, SnakeValue)
+            for path in argument.paths()
+        )
+
+
+def snake_lower(value: SnakeValue[str]) -> SnakeFuncCall[str]:
+    """`LOWER(value)`."""
+    return SnakeFuncCall(SnakeFunc.LOWER, (value,))
+
+
+def snake_upper(value: SnakeValue[str]) -> SnakeFuncCall[str]:
+    """`UPPER(value)`."""
+    return SnakeFuncCall(SnakeFunc.UPPER, (value,))
+
+
+def snake_trim(value: SnakeValue[str]) -> SnakeFuncCall[str]:
+    """`TRIM(value)`: strips the whitespace off both ends."""
+    return SnakeFuncCall(SnakeFunc.TRIM, (value,))
+
+
+def snake_length(value: SnakeValue[str]) -> SnakeFuncCall[int]:
+    """`LENGTH(value)`: returns an INTEGER, not text. That is the whole point of the typing."""
+    return SnakeFuncCall(SnakeFunc.LENGTH, (value,))
+
+
+def snake_concat(*values: SnakeValue[str] | str) -> SnakeFuncCall[str]:
+    """`CONCAT(a, b, ...)`. Unlike `||`, it ignores NULLs instead of propagating them."""
+    return SnakeFuncCall(SnakeFunc.CONCAT, values)
+
+
+D = TypeVar("D", bound=datetime)
+"""The datetime a date function was handed, kept instead of flattened.
+
+`SnakeValue[T]` is INVARIANT, so a parameter annotated `SnakeValue[datetime]` rejects a
+`SnakeValue[SnakeUtc]` even though `SnakeUtc` is a `datetime` subclass and the call runs fine. That
+left the ORM's own recommended timestamp type unable to use the date functions, with no cast to
+reach for: `CASTABLE` is `int`, `float`, `bool`.
+
+Bounded rather than free, because `EXTRACT` over a `str` is a different mistake and one worth
+keeping.
+"""
+
+
+def snake_date_trunc(part: SnakeDatePart, value: SnakeValue[D]) -> SnakeFuncCall[D]:
+    """`DATE_TRUNC('part', value)`: trims the date to the given precision (grouping by month).
+
+    It gives back the type it was handed. Trimming a timestamp to the month does not change what
+    KIND of thing it is, so a `SnakeUtc` column keeps coming out a `SnakeUtc` — the alternative
+    would hand back a plain `datetime` and lose the guarantee the column was declared for.
+    """
+    return SnakeFuncCall(SnakeFunc.DATE_TRUNC, (value,), part=part)
+
+
+def snake_extract(part: SnakeDatePart, value: SnakeValue[D]) -> SnakeFuncCall[int]:
+    """`EXTRACT(part FROM value)`: pulls out one component as a NUMBER (the year, the month...)."""
+    return SnakeFuncCall(SnakeFunc.EXTRACT, (value,), part=part)
+
+
+def snake_abs(value: SnakeValue[T]) -> SnakeFuncCall[T]:
+    """`ABS(value)`: keeps the numeric type of its argument."""
+    return SnakeFuncCall(SnakeFunc.ABS, (value,))
+
+
+def snake_round(value: SnakeValue[T], digits: int = 0) -> SnakeFuncCall[T]:
+    """`ROUND(value)`, or `ROUND(value, digits)` when digits are asked for.
+
+    The zero is NOT passed through, and that is not tidiness. Postgres has `ROUND(double precision)`
+    and `ROUND(numeric, int)` but no `ROUND(double precision, int)`, so emitting the second argument
+    unasked made `snake_round()` on a float column fail there while working on the other two — for
+    the default call, the one nobody would think to test on three engines. `ROUND(x)` means the same
+    thing on all three.
+
+    Asking for digits DOES work on all three now. Postgres has no `ROUND(double precision, int)`,
+    so it declares the type its two-argument form wants —`syntax.round_casts_first_argument_to`— and
+    the emitter casts. A SHAPE difference, translated, never stopping the plan.
+    """
+    if digits:
+        return SnakeFuncCall(SnakeFunc.ROUND, (value, digits))
+    return SnakeFuncCall(SnakeFunc.ROUND, (value,))
+
+
+def snake_cast(value: SnakeValue[Any], as_type: type[V]) -> SnakeCast[V]:
+    """`CAST(value AS <type>)`: an EXPLICIT change of type, named by whoever writes it.
+
+    THE ORM DOES NOT PROMOTE, and this is the door that makes that stance liveable. The arithmetic
+    operators carry one single `T` for both operands and the result, so `Stock.reserved /
+    Stock.on_hand` is an `int` — which is what SQL does, and sometimes what you want. When it is not,
+    you say so:
+
+        snake_cast(Stock.reserved, float) / Stock.on_hand   ->  SnakeArith[float]
+
+    `as_type` is what the RESULT is typed as, so the conversion travels through the type system
+    instead of around it. The SQL name of that type is the dialect's business: measured, SQLite needs
+    `REAL` where `NUMERIC` would answer 0.
+
+    The whitelist refuses by name at the CALL SITE rather than at emission, which is where a refusal
+    is worth something: the alternative is SQL the engine rejects and a driver explaining a decision
+    this ORM made.
+    """
+    if as_type not in CASTABLE:
+        raise SnakeUnsupportedFeature(
+            f"There is no cast to {getattr(as_type, '__name__', as_type)!r}: an explicit cast "
+            f"targets one of {', '.join(t.__name__ for t in CASTABLE)}. This is a whitelist and not "
+            f"an oversight — a type the dialects cannot spell would be emitted as SQL the engine "
+            f"rejects, and the complaint would arrive from the driver rather than from here."
+        )
+    return SnakeCast(source=value, as_type=as_type)
+
+
+# What a date can be shifted by. A WHITELIST built by removing from `SnakeDatePart`, not a second
+# enum: a quarter is a real thing to TRUNCATE to and not a thing any of the three engines spells as
+# an interval, so it is refused by name rather than silently translated into three months.
+SHIFTABLE: tuple[SnakeDatePart, ...] = (
+    SnakeDatePart.YEAR,
+    SnakeDatePart.MONTH,
+    SnakeDatePart.WEEK,
+    SnakeDatePart.DAY,
+    SnakeDatePart.HOUR,
+    SnakeDatePart.MINUTE,
+    SnakeDatePart.SECOND,
+)
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class SnakeDateShift(SnakeValue[T]):
+    """Moving a date or a timestamp by a fixed amount: `placed_on + 30 days`.
+
+    ONE node for both directions: subtracting is adding a negative `amount`, which the three engines
+    accept and which keeps the sign in the VALUE instead of in a second node. `T` is the type of the
+    SOURCE — shifting a date gives a date.
+
+    The three spellings share nothing (`+ INTERVAL`, `DATE_ADD`, a modifier string), so the SQL is
+    the dialect's business. It is the clearest case in the whole ORM for that seam.
+    """
+
+    value: SnakeValue[Any]
+    amount: int
+    unit: SnakeDatePart
+
+    def paths(self) -> tuple[tuple[str, ...], ...]:
+        """What it shifts: the amount is a literal and contributes no navigation of its own."""
+        return self.value.paths()
+
+
+def _shift(value: SnakeValue[T], amount: int, unit: SnakeDatePart) -> SnakeDateShift[T]:
+    """Shared guard for both directions: the unit has to be one a date can actually move by."""
+    if unit not in SHIFTABLE:
+        raise SnakeUnsupportedFeature(
+            f"A date cannot be shifted by {unit.name}: no engine spells it as an interval. "
+            f"`SnakeDatePart` is shared with DATE_TRUNC and EXTRACT, where {unit.name} is real. "
+            f"Shift by one of {', '.join(part.name for part in SHIFTABLE)} — a quarter is three "
+            f"MONTHs, and writing that out is the caller's decision rather than a silent rewrite."
+        )
+    return SnakeDateShift(value=value, amount=amount, unit=unit)
+
+
+def snake_date_add(
+    value: SnakeValue[T], amount: int, unit: SnakeDatePart
+) -> SnakeDateShift[T]:
+    """Moves a date FORWARD: `snake_date_add(Order.placed_on, 30, SnakeDatePart.DAY)`.
+
+    CALENDAR UNITS ARE NOT PORTABLE and the ORM says so rather than hiding it. Measured, `2026-01-31`
+    plus one month is `2026-02-28` on PostgreSQL and MySQL —both clamp— and `2026-03-03` on SQLite,
+    which overflows. That divergence is declared as `Cap.CALENDAR_INTERVAL`, so the session warns
+    once instead of letting whichever engine the developer happens to run be the one that gets
+    tested. DAY, HOUR, MINUTE, SECOND and WEEK are a fixed span and identical on all three.
+
+    Emulating the clamp was the alternative, and it is the wrong one: the ORM would be computing
+    dates in Python behind an expression that claims to be SQL.
+    """
+    return _shift(value, amount, unit)
+
+
+def snake_date_sub(
+    value: SnakeValue[T], amount: int, unit: SnakeDatePart
+) -> SnakeDateShift[T]:
+    """Moves a date BACKWARD. Same node with the sign flipped, because that is all it is."""
+    return _shift(value, -amount, unit)
+
+
+def snake_substring(
+    value: SnakeValue[str], start: int, length: int
+) -> SnakeFuncCall[str]:
+    """`SUBSTRING(value, start, length)`: a slice of text, counted from ONE like SQL does.
+
+    The bounds are VALUES and travel as parameters, which is not obvious enough to leave unsaid: a
+    slice computed from user input with the numbers written into the statement is the shape an
+    injection takes when nobody is looking at strings.
+    """
+    return SnakeFuncCall(SnakeFunc.SUBSTRING, (value, start, length))
+
+
+def snake_replace(value: SnakeValue[str], old: str, new: str) -> SnakeFuncCall[str]:
+    """`REPLACE(value, old, new)`: every occurrence, not the first. Both strings are parameters."""
+    return SnakeFuncCall(SnakeFunc.REPLACE, (value, old, new))
+
+
+def snake_ceil(value: SnakeValue[T]) -> SnakeFuncCall[T]:
+    """`CEIL(value)`: rounds UP, keeping the type of its argument.
+
+    `T -> T` and not `-> int`, and that was measured rather than assumed: `CEIL(1.2)` answers `2` on
+    PostgreSQL and MySQL and `2.0` on SQLite. Declaring `int` would be false on one engine of three,
+    which is the exact family of bug the integer-division work removed. Keeping the argument's type
+    is true everywhere — a float in, a float back.
+    """
+    return SnakeFuncCall(SnakeFunc.CEIL, (value,))
+
+
+def snake_floor(value: SnakeValue[T]) -> SnakeFuncCall[T]:
+    """`FLOOR(value)`: rounds DOWN, keeping the type of its argument. Same measurement as `CEIL`."""
+    return SnakeFuncCall(SnakeFunc.FLOOR, (value,))
+
+
+def snake_sqrt(value: SnakeValue[Any]) -> SnakeFuncCall[float]:
+    """`SQRT(value)`: always a float. Measured `double precision` on PostgreSQL and a real on SQLite."""
+    return SnakeFuncCall(SnakeFunc.SQRT, (value,))
+
+
+def snake_power(value: SnakeValue[Any], exponent: float) -> SnakeFuncCall[float]:
+    """`POWER(value, exponent)`: always a float, and the exponent travels as a parameter."""
+    return SnakeFuncCall(SnakeFunc.POWER, (value, exponent))

snakeorm/expressions/window.py

@@ -0,0 +1,248 @@
+"""Window functions: `<func> OVER (PARTITION BY ... ORDER BY ...)`.
+
+They compute one value per row by looking at NEIGHBOURING rows without collapsing them (unlike a
+GROUP BY). Without windows, that gets solved with a correlated subquery per row (the N+1 of SQL).
+`SnakeWindow` is a plain `SnakeValue` (it gets projected and dispatched by type). It is not allowed
+in WHERE/GROUP BY/HAVING (SQL evaluates them afterwards): the condition emitter watches for that.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from enum import Enum
+from typing import Any, TypeVar
+
+from snakeorm.core.exceptions import SnakeUnsupportedFeature, SnakeValueError
+
+from snakeorm.expressions.expression import (
+    SnakeAggregate,
+    SnakeArith,
+    SnakeOrder,
+    SnakeValue,
+)
+
+T = TypeVar("T")
+
+
+# `eq=False` is NOT optional: `SnakeValue.__eq__` returns `SnakeCondition`, and a dataclass `__eq__`
+# would return `bool`, breaking `window == value`. Same reason in `SnakeAggregate` and `SnakeOrder`.
+@dataclass(frozen=True, slots=True, eq=False)
+class SnakeWindow(SnakeValue[T]):
+    """`<func>(<arg>...) OVER (PARTITION BY ... ORDER BY ...)`.
+
+    `func` is the SQL NAME, kept as a string because two families live side by side (ranking, and
+    aggregates used as windows, which already have their own enum): a union enum would lie.
+    `extra_args` are literals of the function (the offset of `LAG`/`LEAD`), parametrised like every
+    other value.
+    """
+
+    func: str
+    arg: SnakeValue[Any] | None = None
+    extra_args: tuple[object, ...] = ()
+    partition_by: tuple[SnakeValue[Any], ...] = ()
+    order_by: tuple[SnakeOrder, ...] = ()
+    frame: SnakeFrame | None = None
+
+    def over(
+        self,
+        *,
+        partition_by: tuple[SnakeValue[Any], ...] | list[SnakeValue[Any]] = (),
+        order_by: tuple[SnakeOrder, ...] | list[SnakeOrder] = (),
+        frame: SnakeFrame | None = None,
+    ) -> SnakeWindow[T]:
+        """The same function with its window defined. Without `over(...)`, the window is ALL the rows.
+
+        `frame` is what turns a running total into a MOVING one. Without it the default frame runs
+        from the start of the partition to the current row, which is one useful answer out of many:
+        a trailing average, a centred window or a look-ahead all need the frame said out loud.
+
+        A FRAME WITHOUT AN ORDER IS REFUSED. `6 PRECEDING` has to be preceding IN something, and with
+        no `ORDER BY` the engine picks an order of its own — so the same query answers differently on
+        two runs with nothing to show for it. That is the shape of failure this ORM does not ship.
+
+        It returns a NEW node (immutable AST): reusing a stored window holds no surprises.
+        """
+        if frame is not None and not order_by:
+            raise SnakeUnsupportedFeature(
+                "A window frame needs an order to be measured against: pass order_by= alongside "
+                "frame=. Without it, '6 PRECEDING' is six rows before whichever row the engine "
+                "happened to put first, which can change between two runs of the same query."
+            )
+        return replace(
+            self,
+            partition_by=tuple(partition_by),
+            order_by=tuple(order_by),
+            frame=frame,
+        )
+
+    def paths(self) -> tuple[tuple[str, ...], ...]:
+        """Paths of everything the window touches (argument, partition, order): all three plan JOINs."""
+        paths: list[tuple[str, ...]] = []
+        if self.arg is not None:
+            paths.extend(self.arg.paths())
+        for value in self.partition_by:
+            paths.extend(value.paths())
+        for key in self.order_by:
+            paths.extend(key.expr.paths())
+        return tuple(paths)
+
+
+def _rank_window(name: str) -> SnakeWindow[int]:
+    """Ranking function with no argument: it returns one integer per row."""
+    return SnakeWindow[int](func=name)
+
+
+def row_number() -> SnakeWindow[int]:
+    """`ROW_NUMBER()`: position within the partition, with no ties (1, 2, 3, 4...)."""
+    return _rank_window("ROW_NUMBER")
+
+
+def rank() -> SnakeWindow[int]:
+    """`RANK()`: position with ties, SKIPPING the gaps (1, 2, 2, 4...)."""
+    return _rank_window("RANK")
+
+
+def dense_rank() -> SnakeWindow[int]:
+    """`DENSE_RANK()`: position with ties and NO gaps (1, 2, 2, 3...)."""
+    return _rank_window("DENSE_RANK")
+
+
+def lag(value: SnakeValue[T], offset: int = 1) -> SnakeWindow[T | None]:
+    """`LAG(value, n)`: the value of the row n positions BEFORE in the window.
+
+    Optional: on the first n rows there is no previous one and the result is NULL.
+    """
+    return SnakeWindow[T | None](func="LAG", arg=value, extra_args=(offset,))
+
+
+def lead(value: SnakeValue[T], offset: int = 1) -> SnakeWindow[T | None]:
+    """`LEAD(value, n)`: the value of the row n positions AFTER. Optional for the same reason."""
+    return SnakeWindow[T | None](func="LEAD", arg=value, extra_args=(offset,))
+
+
+def as_window(aggregate: SnakeAggregate[T]) -> SnakeWindow[T]:
+    """Turns an aggregate into a window: `SUM(x)` -> `SUM(x) OVER (...)`.
+
+    With GROUP BY it returns one row per group; as a window, every row with its running total. Used by `SnakeAggregate.over(...)`.
+    """
+    return SnakeWindow[T](func=aggregate.func.value, arg=aggregate.arg)
+
+
+def has_window(value: object) -> bool:
+    """Does this value contain a window function, however nested?
+
+    It walks the nodes that WRAP another value (arithmetic, aggregate); the rest are leaves. It exists
+    to REJECT the window where SQL forbids it: `WHERE row_number() + 1 > 3` is just as impossible as it is without the `+ 1`.
+    """
+    if isinstance(value, SnakeWindow):
+        return True
+    if isinstance(value, SnakeArith):
+        return has_window(value.left) or has_window(value.right)
+    if isinstance(value, SnakeAggregate):
+        return value.arg is not None and has_window(value.arg)
+    return False
+
+
+class SnakeFrameMode(Enum):
+    """`ROWS` counts ROWS, `RANGE` counts VALUES. With ties they answer differently.
+
+    Offering only `ROWS` would be the smaller API and the wrong one: somebody ordering by a day that
+    has several readings in it means RANGE, and handing them ROWS is a wrong answer with no error.
+    """
+
+    ROWS = "ROWS"
+    RANGE = "RANGE"
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeFrameBound:
+    """One end of a frame. `offset=None` is UNBOUNDED; `offset=0` is the current row.
+
+    The offset reaches the STATEMENT rather than `params`, and that is measured rather than lazy:
+    PostgreSQL and SQLite take a placeholder in a bound and MariaDB rejects it outright, so the only
+    portable spelling is the literal. It is safe for the same reason the JSON key path is — the value
+    is an `int` from Python's own type system and it is checked when the bound is BUILT, before any
+    SQL exists. An integer carries no injection.
+    """
+
+    offset: int | None
+    following: bool
+
+    def sql(self) -> str:
+        """The bound as standard SQL. The three engines spell this identically (measured)."""
+        direction = "FOLLOWING" if self.following else "PRECEDING"
+        if self.offset is None:
+            return f"UNBOUNDED {direction}"
+        if self.offset == 0:
+            return "CURRENT ROW"
+        return f"{self.offset} {direction}"
+
+    def rank(self) -> tuple[int, int]:
+        """Where this bound sits on the timeline, so a frame can check it does not run backwards."""
+        if self.offset is None:
+            return (4, 0) if self.following else (0, 0)
+        if self.offset == 0:
+            return (2, 0)
+        return (3, self.offset) if self.following else (1, -self.offset)
+
+
+@dataclass(frozen=True, slots=True)
+class SnakeFrame:
+    """`<mode> BETWEEN <start> AND <end>`: which neighbouring rows the function may look at."""
+
+    mode: SnakeFrameMode
+    start: SnakeFrameBound
+    end: SnakeFrameBound
+
+    def sql(self) -> str:
+        """The whole clause. No dialect involved: it is the same on the three engines."""
+        return f"{self.mode.value} BETWEEN {self.start.sql()} AND {self.end.sql()}"
+
+
+# The current row, which is the commonest end of a trailing window. A constant rather than a
+# function because it takes no argument and there is exactly one of it.
+SNAKE_CURRENT_ROW = SnakeFrameBound(offset=0, following=False)
+
+
+def _bound(rows: int | None, following: bool) -> SnakeFrameBound:
+    """Shared guard. Refusing here is what lets the number be interpolated later."""
+    if rows is not None and rows < 0:
+        raise SnakeValueError(
+            f"A frame bound cannot be negative (got {rows}): the DIRECTION is the function you "
+            f"call, so the distance is always counted forwards from here. For {abs(rows)} rows the "
+            f"other way, call the other one."
+        )
+    return SnakeFrameBound(offset=rows, following=following)
+
+
+def snake_preceding(rows: int | None = None) -> SnakeFrameBound:
+    """`n PRECEDING`, or `UNBOUNDED PRECEDING` with no argument."""
+    return _bound(rows, following=False)
+
+
+def snake_following(rows: int | None = None) -> SnakeFrameBound:
+    """`n FOLLOWING`, or `UNBOUNDED FOLLOWING` with no argument."""
+    return _bound(rows, following=True)
+
+
+def _frame(
+    mode: SnakeFrameMode, start: SnakeFrameBound, end: SnakeFrameBound
+) -> SnakeFrame:
+    """Shared guard: a frame that ends before it starts is empty by construction."""
+    if start.rank() > end.rank():
+        raise SnakeValueError(
+            f"This frame starts after it ends ({start.sql()} .. {end.sql()}), so it can never "
+            f"contain a row. The engines reject it too — it is caught here so the complaint names "
+            f"the frame instead of arriving from the driver."
+        )
+    return SnakeFrame(mode=mode, start=start, end=end)
+
+
+def snake_rows(start: SnakeFrameBound, end: SnakeFrameBound) -> SnakeFrame:
+    """`ROWS BETWEEN start AND end`: counts ROWS, so ties are separate rows."""
+    return _frame(SnakeFrameMode.ROWS, start, end)
+
+
+def snake_range(start: SnakeFrameBound, end: SnakeFrameBound) -> SnakeFrame:
+    """`RANGE BETWEEN start AND end`: counts VALUES, so tied rows come in together."""
+    return _frame(SnakeFrameMode.RANGE, start, end)

snakeorm/fields/__init__.py

@@ -0,0 +1,68 @@
+"""SnakeORM field descriptors and their field specifiers."""
+
+from snakeorm.fields.check import snake_check as snake_check
+from snakeorm.fields.check import snake_checks as snake_checks
+from snakeorm.fields.check import snake_indexes as snake_indexes
+from snakeorm.fields.column import MISSING as MISSING
+from snakeorm.fields.column import SnakeColumn as SnakeColumn
+from snakeorm.fields.column import snake_auto as snake_auto
+from snakeorm.fields.column import snake_column as snake_column
+from snakeorm.fields.column import snake_discriminator as snake_discriminator
+from snakeorm.fields.enum import snake_enum as snake_enum
+from snakeorm.fields.index import SnakeIndex as SnakeIndex
+from snakeorm.fields.relationship import SnakeCollection as SnakeCollection
+from snakeorm.fields.relationship import SnakePrefetch as SnakePrefetch
+from snakeorm.fields.relationship import SnakePrefetchHop as SnakePrefetchHop
+from snakeorm.core.exceptions import (
+    SnakeRelationshipNotLoaded as SnakeRelationshipNotLoaded,
+)
+from snakeorm.fields.relationship import SnakePathProxy as SnakePathProxy
+from snakeorm.fields.relationship import SnakeToMany as SnakeToMany
+from snakeorm.fields.relationship import path_of as path_of
+from snakeorm.fields.relationship import SnakeToOne as SnakeToOne
+from snakeorm.fields.relationship import snake_to_many as snake_to_many
+from snakeorm.fields.relationship import snake_to_many_through as snake_to_many_through
+from snakeorm.fields.relationship import snake_to_one as snake_to_one
+from snakeorm.fields.typed import snake_datetime as snake_datetime
+from snakeorm.fields.typed import snake_datetimetz as snake_datetimetz
+from snakeorm.fields.typed import snake_decimal as snake_decimal
+from snakeorm.fields.typed import snake_int as snake_int
+from snakeorm.fields.typed import snake_json as snake_json
+from snakeorm.fields.typed import snake_str as snake_str
+from snakeorm.fields.typed import snake_float as snake_float
+from snakeorm.fields.typed import snake_time as snake_time
+from snakeorm.fields.typed import snake_timetz as snake_timetz
+
+# CANONICAL reference of the field specifiers. It CANNOT be passed to `@dataclass_transform`:
+# PEP 681 demands a literal tuple at each site and mypy rejects it; the language imposes the
+# duplication across the FIVE sites — `SnakeModel` and `SnakeView` in `model.py`, and the
+# `@snake_model`, `@snake_view` and `@snake_db_first` decorators.
+#
+# `test/typing/test_field_specifiers.py` checks that they all match, and it DISCOVERS them through
+# the `__dataclass_transform__` PEP 681 leaves at runtime instead of listing them: forgetting a
+# site silently stops typing that path — with every test still green — so the count is exactly the
+# thing that must not be remembered.
+#
+# The three relation specifiers ARE here, and NOT because relations are constructor arguments —
+# they are not. `snake_to_one`, `snake_to_many` and `snake_to_many_through` each declare
+# `init: Literal[False]`, and a checker only reads that signal off a call it recognises as a field
+# specifier, i.e. one listed here. Leaving one out makes the checker read it as "a field with a
+# default" and bless a line the runtime rejects with `TypeError`.
+SNAKE_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,
+)

snakeorm/fields/check.py

@@ -0,0 +1,79 @@
+"""Declaring CHECK constraints: `snake_check(...)` in the body of the model."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from snakeorm.core.exceptions import SnakeModelError
+from snakeorm.expressions import SnakeCondition
+from snakeorm.fields.index import SnakeIndex
+from snakeorm.metadata import SnakeIndexInfo
+from snakeorm.fields.relationship import _registry_of
+from snakeorm.metadata.check import SnakeCheckInfo
+
+
+def snake_check(
+    condition: SnakeCondition, *, name: str | None = None
+) -> SnakeCheckInfo:
+    """Declare a typed CHECK constraint: the condition is the same `SnakeCondition` as
+    `.filter()`.
+
+    It gets validated here, at declaration time, and not when generating the migration: a
+    condition with a subquery or an EXISTS does not fit in a CHECK, and the useful place to find
+    out is where you wrote it.
+    """
+    info = SnakeCheckInfo(condition=condition, name=name)
+    # A dry render so the rejection fires now; `render_condition` is the only one that knows which
+    # nodes are reconstructible (duplicating that criterion would mean having two truths).
+    from snakeorm.migration.render import render_condition
+
+    render_condition(condition)
+    return info
+
+
+def snake_checks(model: type, *checks: SnakeCheckInfo) -> None:
+    """Add CHECK constraints to an ALREADY decorated model, referencing its TYPED columns.
+
+        snake_checks(Person, snake_check(Person.age >= 18, name="adult"))
+
+    Outside the class body (not inside it like `SnakeIndexes`) because a condition is built on the
+    spot and inside the body `age` is the raw descriptor, with `__set_name__` not yet run: it does
+    not know its name yet. Once decorated, `Person.age` is CLASS access → `SnakeExpr[int]`, which
+    preserves the typing.
+    """
+    reg = _registry_of(model)
+    table = reg.table_of(model)
+    if table is None:
+        raise SnakeModelError(
+            f"{model.__name__} is not a @snake_model: declare the model before adding checks to it."
+        )
+    reg.register(model, replace(table, checks=(*table.checks, *checks)))
+
+
+def snake_indexes(model: type, *indexes: SnakeIndex) -> None:
+    """Add indexes to an ALREADY decorated model, referencing its TYPED columns.
+
+        snake_indexes(Customer, SnakeIndex(Customer.name, unique=True, where=Customer.closed_at.is_null()))
+
+    Same reason as `snake_checks`: a PARTIAL index needs a condition, which is built on the spot
+    and does not fit in the `SnakeIndexes` of the body. It re-registers the model instead of
+    mutating an attribute (assigning `SnakeIndexes` after the decorator never reaches the graph:
+    it has already compiled).
+    """
+    reg = _registry_of(model)
+    table = reg.table_of(model)
+    if table is None:
+        raise SnakeModelError(
+            f"{model.__name__} is not a @snake_model: declare the model before adding indexes to it."
+        )
+    compiled = tuple(
+        SnakeIndexInfo(
+            columns=index.column_names(),
+            unique=index.unique,
+            name=index.name,
+            where=index.where,
+            method=index.method,
+        )
+        for index in indexes
+    )
+    reg.register(model, replace(table, indexes=(*table.indexes, *compiled)))