snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/migration/runner.py

@@ -0,0 +1,314 @@
+"""Migration runtime: applies and reverts migrations, with tracking in the database.
+
+The order comes from the files' linear numbering (there is no `down_revision`). The applied versions
+are stored in `snake_migrations`, which makes `apply` IDEMPOTENT. Every migration is ATOMIC if the
+engine has transactional DDL; if it does not, on error it reports how many operations were applied.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from snakeorm.core.placement import DEFAULT_SCHEMA
+from snakeorm.dialects import SnakeDialect
+from snakeorm.drivers import SnakeDriver
+from snakeorm.core.exceptions import SnakeMigrationError
+from snakeorm.metadata import SnakeStrParams
+from snakeorm.migration.operations import (
+    RebuildTable,
+    SnakeDataOperation,
+    SnakeMigrationOperation,
+    SnakeOperation,
+)
+from snakeorm.migration.realize import realize
+from snakeorm.session import SnakeSession
+from snakeorm.sql.refs import qualified
+
+_TRACKING_TABLE = "snake_migrations"
+_SCHEMA = DEFAULT_SCHEMA
+
+
+@dataclass(frozen=True, slots=True)
+class Migration:
+    """A versioned unit of operations (schema and/or data). The order comes from its number."""
+
+    version: str
+    operations: tuple[SnakeMigrationOperation, ...]
+    replaces: tuple[str, ...] = ()
+    """Versions this migration REPLACES (a squash). Empty in a normal migration.
+
+    It allows a history to be collapsed without breaking the databases where the originals were
+    already applied: there the squash is marked applied without being executed. See `apply`.
+    """
+
+
+def squash_already_done(migration: Migration, already: set[str]) -> bool:
+    """Is this squash's work already done by the migrations it replaces?
+
+    - ALL applied -> yes. The DB is already in that state; running it would repeat a `CREATE TABLE`.
+    - NONE applied -> no. Fresh install: it runs.
+    - SOME yes and others no -> it STOPS. Running it would repeat what is done and marking it would
+      skip what is missing; both corrupt, so it is flagged and the human decides.
+
+    A loose function (not a method) so both runners share THE SAME answer: a duplicated criterion
+    that drifts decides differently in silence.
+    """
+    done = [version for version in migration.replaces if version in already]
+    if not done:
+        return False
+    if len(done) == len(migration.replaces):
+        return True
+    missing = [version for version in migration.replaces if version not in already]
+    raise SnakeMigrationError(
+        f"The squash '{migration.version}' replaces a history that was applied HALF-WAY: "
+        f"{sorted(done)} are already there and {sorted(missing)} are missing. It can neither "
+        f"be run (it would repeat what is done) nor be marked as applied (it would skip what is "
+        f"missing). Apply the missing ones first with the original history and try again."
+    )
+
+
+def explain_rebuild_failure(
+    plan: Sequence[SnakeMigrationOperation], dialect: SnakeDialect, error: Exception
+) -> SnakeMigrationError | None:
+    """Turns a rebuild's integrity failure into a sentence, or `None` if that is not what happened.
+
+    A loose function, like `squash_already_done` and `tracking_table_ddl`, and for the same reason:
+    the two runners must not be able to answer this differently.
+
+    WHAT IT IS EXPLAINING, measured on SQLite 3.50. A rebuild drops the old table halfway through,
+    and that orphans every row of every OTHER table whose foreign key names it. The keys are
+    deferred, so nothing fails there — but SQLite counts deferred violations instead of rechecking
+    them, and putting the table back three statements later does not bring the counter down. So the
+    COMMIT refuses with four words, `PRAGMA foreign_key_check` says the database is clean, and the
+    person reading the deploy log has no way in.
+
+    It does not repair anything: the migration has already rolled back, which is correct. What it
+    adds is the name of the table, the reason the check disagrees, and the one instrument that lifts
+    the limit — `PRAGMA foreign_keys = OFF` on a connection with NO transaction open, which is where
+    that pragma stops being a no-op.
+
+    IT ANSWERS A SECOND FAILURE, and the two do not look alike. A rebuild finishes with a `RENAME`,
+    and on this engine a rename REPARSES the whole schema — so a view standing over the table makes
+    that statement fail with `error in view <v>: no such table: main.<t>`, naming a table the reader
+    can see with their own eyes and a view nobody touched. The generator emits the rebuild bare on
+    purpose, because which tables a view reads is not something the metadata says, so this turns the
+    engine's sentence into the two operations the migration was missing.
+    """
+    if dialect.syntax.defer_constraints_statement is None:
+        return None
+    rebuilt = [
+        operation.after.name
+        for operation in plan
+        if isinstance(operation, RebuildTable)
+    ]
+    if not rebuilt:
+        return None
+    message = str(error).lower()
+    if "error in view" in message:
+        return SnakeMigrationError(
+            f"The rebuild of {', '.join(sorted(set(rebuilt)))} could not be applied: this engine "
+            f"has to DROP the table to change a constraint on it and RENAME the replacement into "
+            f"place, and a RENAME reparses the WHOLE schema — every view in it. A view whose SELECT "
+            f"names the table is unparseable at that instant, so the RENAME is what failed, not the "
+            f"drop, and the engine's own words ({error}) name a table that does exist. Nothing was "
+            f"applied: the migration rolled back whole. Surround the rebuild with the two "
+            f"operations that say it out loud — a DropView of that view BEFORE it and a CreateView "
+            f"of the same view AFTER it — and the rename has nothing left to reparse. The "
+            f"generator does not write them for you, and cannot: nothing in the metadata says "
+            f"which TABLES a view reads (a `sql=` view is raw text, and `depends_on` only names "
+            f"other views), so which view has to come down is a decision only you can make."
+        )
+    if "foreign key" not in message:
+        return None
+    return SnakeMigrationError(
+        f"The rebuild of {', '.join(sorted(set(rebuilt)))} could not be committed: this engine has "
+        f"to DROP the table to change a constraint on it, and a foreign key from another table "
+        f"still names it. The keys were deferred, so the drop went through and the COMMIT is what "
+        f"refused — and `PRAGMA foreign_key_check` will tell you the database is clean, because "
+        f"deferred violations are COUNTED at the moment they happen and not re-checked at the end. "
+        f"Nothing was applied: the migration rolled back whole. To let it through, the foreign keys "
+        f"have to be off, and `PRAGMA foreign_keys = OFF` is a no-op inside a transaction — it has "
+        f"to be issued on the connection BEFORE the migration opens one."
+    )
+
+
+_VERSION_MAX_LENGTH = 255
+"""Length of the tracking table's `version` column.
+
+Not a random number: it is the classic one that fits a MySQL index under any collation, and this
+column IS the table's primary key. A migration name does not come anywhere close to it.
+"""
+
+
+def tracking_table_ddl(dialect: SnakeDialect) -> str:
+    """The `CREATE TABLE IF NOT EXISTS` for `snake_migrations`, for either runner.
+
+    A loose function, like `squash_already_done`, and for the same reason made concrete: the two
+    runners must not be able to answer this differently. They already did. The synchronous one
+    learned the hard way that a hard-wired `TEXT` makes MySQL reject the entire table — "BLOB/TEXT
+    column used in key specification without a key length", error 1170, because this column IS the
+    primary key — and asked the dialect for the type instead, with the reason written down. The
+    async runner was written later, copied the shape rather than the lesson, and carried the bug on
+    the FIRST statement of its `apply()`: on MySQL the async migration system never started.
+
+    Nothing caught it. The parity test between the runners compared method NAMES, and both are
+    called `ensure_tracking_table`.
+
+    With a declared length each engine emits its own: `VARCHAR(255)` on Postgres and MySQL, `TEXT`
+    on SQLite, which does not distinguish.
+    """
+    table = qualified(_SCHEMA, _TRACKING_TABLE, dialect)
+    version = dialect.quote_ident("version")
+    applied_at = dialect.quote_ident("applied_at")
+    version_type = dialect.map_type(
+        str, params=SnakeStrParams(max_length=_VERSION_MAX_LENGTH)
+    )
+    return (
+        f"CREATE TABLE IF NOT EXISTS {table} "
+        f"({version} {version_type} NOT NULL, "
+        f"{applied_at} TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, "
+        f"PRIMARY KEY ({version}))"
+    )
+
+
+class MigrationRunner:
+    """Applies/reverts migrations and records the applied ones in `snake_migrations`."""
+
+    def __init__(self, driver: SnakeDriver, dialect: SnakeDialect) -> None:
+        self._driver = driver
+        self._dialect = dialect
+        # A session over the SAME driver/dialect: the `RunPython`s run the ORM inside the
+        # migration's transaction, atomic alongside the schema operations.
+        self._session = SnakeSession(driver, dialect)
+
+    def ensure_tracking_table(self) -> None:
+        """Creates the tracking table if it does not exist (idempotent).
+
+        The DDL itself is `tracking_table_ddl`, shared with the async runner. It used to live here,
+        and the async one carried its own copy with the MySQL bug this one had already fixed — which
+        is the reason it is a loose function now and not a method on each.
+        """
+        self._driver.execute(tracking_table_ddl(self._dialect), ())
+        self._driver.commit()
+
+    def applied_versions(self) -> set[str]:
+        """Returns the set of versions already applied."""
+        version = self._dialect.quote_ident("version")
+        rows = self._driver.fetch_all(f"SELECT {version} FROM {self._table_ref()}", ())
+        return {str(row[0]) for row in rows}
+
+    def apply(self, migrations: list[Migration]) -> list[str]:
+        """Applies the pending migrations in order. Returns the versions applied just now.
+
+        Every migration is ATOMIC: its operations and the version record go together. With
+        transactional DDL a failure halfway does a `rollback()`; without it, how many were applied is
+        reported.
+        """
+        self.ensure_tracking_table()
+        already = self.applied_versions()
+        replaced = {
+            version for migration in migrations for version in migration.replaces
+        }
+        newly: list[str] = []
+        for migration in migrations:
+            if migration.version in already:
+                continue
+            # A migration replaced by a squash in this batch is not applied: the squash does it.
+            if migration.version in replaced:
+                continue
+            if migration.replaces and squash_already_done(migration, already):
+                self._record(migration.version)
+                self._driver.commit()
+                newly.append(migration.version)
+                continue
+            if self._dialect.supports_transactional_ddl:
+                self._apply_atomic(migration)
+            else:
+                self._apply_stepwise(migration)
+            newly.append(migration.version)
+        return newly
+
+    def _apply_atomic(self, migration: Migration) -> None:
+        """Applies a migration wrapped in the engine's transaction: all or nothing."""
+        plan = realize(migration.operations, self._dialect)
+        try:
+            for operation in plan:
+                self._forward(operation)
+            self._record(migration.version)
+            self._driver.commit()
+        except Exception as error:
+            self._driver.rollback()  # undoes the operations already emitted for THIS migration
+            explained = explain_rebuild_failure(plan, self._dialect, error)
+            if explained is not None:
+                raise explained from error
+            raise
+
+    def _apply_stepwise(self, migration: Migration) -> None:
+        """Applies operation by operation (engine without transactional DDL); on error, reports how many."""
+        applied = 0
+        plan = realize(migration.operations, self._dialect)
+        try:
+            for operation in plan:
+                self._forward(operation)
+                applied += 1
+            self._record(migration.version)
+            self._driver.commit()
+        except Exception as error:
+            raise SnakeMigrationError(
+                f"Migration '{migration.version}' failed after applying {applied} of "
+                f"{len(plan)} operation(s): {error}. The engine does not support "
+                f"transactional DDL, so the database was left half-way: review it and "
+                f"fix it by hand."
+            ) from error
+
+    def rollback(self, migration: Migration) -> None:
+        """Reverts a migration (operations in reverse order) and deletes its record."""
+        for operation in reversed(realize(migration.operations, self._dialect)):
+            self._backward(operation)
+        self._unrecord(migration.version)
+        self._driver.commit()
+
+    def _forward(self, operation: SnakeMigrationOperation) -> None:
+        """Runs an operation forwards, dispatching by STRUCTURE.
+
+        Data (`SnakeDataOperation`) has `run` and runs with the session; schema (`SnakeOperation`) has
+        `up_sql` and executes its DDL. Both in the same transaction (a mixed migration is still
+        all-or-nothing).
+        """
+        if isinstance(operation, SnakeDataOperation):
+            operation.run(self._session)
+        elif isinstance(operation, SnakeOperation):
+            for sql in operation.up_sql(self._dialect):
+                self._driver.execute(sql, ())
+
+    def _backward(self, operation: SnakeMigrationOperation) -> None:
+        """Reverts an operation: the DATA one runs its `unrun`; the SCHEMA one emits its reverse DDL."""
+        if isinstance(operation, SnakeDataOperation):
+            operation.unrun(self._session)
+        elif isinstance(operation, SnakeOperation):
+            for sql in operation.down_sql(self._dialect):
+                self._driver.execute(sql, ())
+
+    def _table_ref(self) -> str:
+        """Reference to the tracking table, qualified ONLY if the engine has schemas.
+
+        Qualifying `"public"."snake_migrations"` by hand broke on SQLite (`unknown database
+        "public"`); `qualified()` exists for exactly this.
+        """
+        return qualified(_SCHEMA, _TRACKING_TABLE, self._dialect)
+
+    def _record(self, version: str) -> None:
+        column = self._dialect.quote_ident("version")
+        self._driver.execute(
+            f"INSERT INTO {self._table_ref()} ({column}) "
+            f"VALUES ({self._dialect.placeholder(1)})",
+            (version,),
+        )
+
+    def _unrecord(self, version: str) -> None:
+        column = self._dialect.quote_ident("version")
+        self._driver.execute(
+            f"DELETE FROM {self._table_ref()} WHERE {column} = {self._dialect.placeholder(1)}",
+            (version,),
+        )

snakeorm/migration/squash.py

@@ -0,0 +1,60 @@
+"""Collapsing N migrations into a single one, declaring which ones it replaces.
+
+The collapse is a replay up to the final state. The delicate part is the DB where the originals have
+ALREADY been applied: there the squash must not run (its `CREATE TABLE` would die against tables
+that exist), hence the `replaces` the runner uses to decide (see `MigrationRunner.apply`). It is a
+DESKTOP operation (it does not touch the DB), and that is why it cannot merge DATA operations.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from snakeorm.core.exceptions import SnakeMigrationError
+from snakeorm.migration.autodetect import replay
+from snakeorm.migration.diff import diff_routines, diff_schema, diff_triggers
+from snakeorm.migration.operations import RunPython, RunSQL, SnakeOperation
+from snakeorm.migration.runner import Migration
+
+
+def squash(migrations: Sequence[Migration], *, version: str) -> Migration:
+    """Collapses `migrations` into ONE producing the same final state.
+
+    It emits the state they lead to, not the steps (a column added and then dropped does not show
+    up). Crossing a DATA operation (`RunPython`, `RunSQL`) is rejected: its `apply_to_state` is a
+    no-op, so merging them would demand EXECUTING them, and the collapse does not touch the DB
+    (losing them would silently leave data unmigrated).
+    """
+    if not migrations:
+        raise SnakeMigrationError("A squash needs at least one migration to collapse.")
+
+    for migration in migrations:
+        for operation in migration.operations:
+            if isinstance(operation, (RunPython, RunSQL)):
+                raise SnakeMigrationError(
+                    f"Migration '{migration.version}' contains a DATA operation "
+                    f"({type(operation).__name__}), which cannot be collapsed: mutating rows "
+                    f"demands running it, and a squash does not touch the database. Collapse the "
+                    f"stretch that reaches UP TO it and leave the rest of the history as it is."
+                )
+
+    # The replayed final state, diffed against nothing: that IS the squash. EVERY collection the
+    # state holds has to be re-emitted, and in `autodetect`'s order — tables first, then the
+    # routines and triggers that may reference them. Anything not re-emitted here is dropped from
+    # the collapsed history in silence, and a fresh install comes up without it.
+    #
+    # That is not hypothetical: it happened to the routines, was fixed by adding their line, and the
+    # triggers stayed missing for exactly as long, because the test written that day knew only about
+    # routines. The two callers are compared in `test_squash.py` now, so the next collection added
+    # to `SchemaState` cannot be forgotten the same way.
+    state = replay(migrations)
+    operations: list[SnakeOperation] = [
+        *diff_schema([], state.tables()),
+        *diff_routines([], state.routines()),
+        *diff_triggers([], state.triggers()),
+    ]
+    return Migration(
+        version=version,
+        operations=tuple(operations),
+        replaces=tuple(migration.version for migration in migrations),
+    )

snakeorm/migration/state.py

@@ -0,0 +1,107 @@
+"""SchemaState: the schema's mutable state, rebuilt by replaying migrations.
+
+It is the equivalent of Django's `ProjectState`. Every operation knows how to mutate it
+(`apply_to_state`), just as it knows how to emit its SQL. Autogen replays the migrations'
+operations onto an empty SchemaState to obtain the "previous state", and diffs that against the
+current metadata.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from snakeorm.core.placement import DEFAULT_SCHEMA
+from snakeorm.metadata import SnakeRoutineInfo, SnakeTableInfo, SnakeTriggerInfo
+
+
+class SchemaState:
+    """A mutable collection of tables (and routines), indexed by name."""
+
+    def __init__(
+        self,
+        tables: Iterable[SnakeTableInfo] = (),
+        routines: Iterable[SnakeRoutineInfo] = (),
+        triggers: Iterable[SnakeTriggerInfo] = (),
+    ) -> None:
+        self._tables: dict[str, SnakeTableInfo] = {
+            table.name: table for table in tables
+        }
+        self._routines: dict[str, SnakeRoutineInfo] = {
+            routine.name: routine for routine in routines
+        }
+        # A trigger's key is (table, name): in Postgres the name is not unique, two tables can
+        # each have one of the same name, and indexing by name alone would overwrite one silently.
+        self._triggers: dict[tuple[str, str], SnakeTriggerInfo] = {
+            (trigger.table, trigger.name): trigger for trigger in triggers
+        }
+        # `public` always exists in Postgres: nobody creates it and nobody should drop it.
+        self._schemas: set[str] = {DEFAULT_SCHEMA}
+
+    def add_table(self, table: SnakeTableInfo) -> None:
+        """Adds (or replaces) a table in the state."""
+        self._tables[table.name] = table
+
+    def remove_table(self, name: str) -> None:
+        """Removes a table from the state AND the triggers that hung off it.
+
+        A trigger belongs to its table on all three engines: a `DROP TABLE` takes it along, and
+        nothing is left to drop afterwards. The state used to keep it, and it was the only thing in
+        the system still believing in it — `squash`, which re-emits everything the state holds, put
+        a `CreateTrigger` in the collapsed migration for a table that migration never creates, and a
+        fresh install died on that statement.
+
+        A rename goes through here too, and there the trigger does NOT disappear: it follows the
+        table. `RenameTable.apply_to_state` puts it back under the new name, for the same reason it
+        already re-points the foreign keys.
+        """
+        self._tables.pop(name, None)
+        for key in [key for key in self._triggers if key[0] == name]:
+            del self._triggers[key]
+
+    def get_table(self, name: str) -> SnakeTableInfo | None:
+        """Returns the table by name, or None if it is not in the state."""
+        return self._tables.get(name)
+
+    def tables(self) -> tuple[SnakeTableInfo, ...]:
+        """The tables of the current state."""
+        return tuple(self._tables.values())
+
+    def add_schema(self, schema: str) -> None:
+        """Records a schema as existing."""
+        self._schemas.add(schema)
+
+    def remove_schema(self, schema: str) -> None:
+        """Removes a schema from the state (idempotent if it was not there)."""
+        self._schemas.discard(schema)
+
+    def schemas(self) -> frozenset[str]:
+        """Schemas the state takes to exist."""
+        return frozenset(self._schemas)
+
+    def add_routine(self, routine: SnakeRoutineInfo) -> None:
+        """Adds (or replaces) a routine (function/procedure) in the state."""
+        self._routines[routine.name] = routine
+
+    def remove_routine(self, name: str) -> None:
+        """Removes a routine from the state (idempotent if it is not there)."""
+        self._routines.pop(name, None)
+
+    def get_routine(self, name: str) -> SnakeRoutineInfo | None:
+        """Returns the routine by name, or None if it is not in the state."""
+        return self._routines.get(name)
+
+    def routines(self) -> tuple[SnakeRoutineInfo, ...]:
+        """The routines of the current state."""
+        return tuple(self._routines.values())
+
+    def add_trigger(self, trigger: SnakeTriggerInfo) -> None:
+        """Adds (or replaces) a trigger. The key is (table, name), not the name alone."""
+        self._triggers[(trigger.table, trigger.name)] = trigger
+
+    def remove_trigger(self, table: str, name: str) -> None:
+        """Removes a trigger from the state (idempotent if it is not there)."""
+        self._triggers.pop((table, name), None)
+
+    def triggers(self) -> tuple[SnakeTriggerInfo, ...]:
+        """The triggers of the current state."""
+        return tuple(self._triggers.values())

snakeorm/model.py

@@ -0,0 +1,162 @@
+"""Base class of the SnakeORM models."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import ClassVar, dataclass_transform
+
+from snakeorm.core.exceptions import SnakeAggregateNotLoaded
+from snakeorm.fields import (
+    SnakeIndex,
+    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.metadata import SnakeCheckInfo
+
+# Key (with a trailing double underscore: it does NOT get name-mangled) holding, per instance, the
+# dict of aggregates `session.annotate(...)` fills in. Absent = the instance was not annotated.
+_AGGREGATES_KEY = "__snake_aggregates__"
+
+
+class _AggregateNamespace:
+    """EMERGENCY EXIT for reading annotated aggregates by dynamic name.
+
+    `obj.aggregate.<name>` returns `object` (NEVER `Any`): the name is dynamic, so the checker cannot
+    type it and FORCES a `cast()` at the point of use. No IntelliSense and no typo-safety: it is the
+    hatch, not the road. The genuinely typed road is `@snake_result` + `session.annotate(...)`, which
+    hands you a class with genuinely typed fields.
+    """
+
+    __slots__ = ("_values",)
+
+    def __init__(self, values: Mapping[str, object] | None) -> None:
+        self._values = values
+
+    def __getattr__(self, name: str) -> object:
+        """Returns the aggregate's annotated value, or explains why it is not available."""
+        values = self._values
+        if values is None:
+            raise SnakeAggregateNotLoaded(
+                f"This instance was not annotated: '{name}' only exists after "
+                f"session.annotate(query, Result, {name}=<aggregate>). The typed path is "
+                f"@snake_result; this is the emergency exit (returns object, demands a cast)."
+            )
+        if name not in values:
+            available = ", ".join(sorted(values)) or "(none)"
+            raise SnakeAggregateNotLoaded(
+                f"There is no '{name}' aggregate on this instance. Annotations available: "
+                f"{available}. Ask for it with session.annotate(query, Result, {name}=<aggregate>)."
+            )
+        return values[name]
+
+
+# The tuple is LITERAL: PEP 681 does not accept a constant here (see SNAKE_FIELD_SPECIFIERS in
+# `fields/__init__.py`, the canonical reference, which a test ties this literal to).
+@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,
+    ),
+)
+class SnakeModel:
+    """Model base: provides the table config at class level, TYPED.
+
+    The settings that reference columns or are documentation (table comment,
+    indexes, checks) are declared here and NOT in the decorator. They are annotated
+    as `ClassVar` so `dataclass_transform` does not mistake them for model columns.
+    """
+
+    SnakeComment: ClassVar[str | None] = None
+    SnakeIndexes: ClassVar[list[SnakeIndex]] = []
+    # Domain rules the DB enforces. Declared with `snake_check(User.age >= 18)`: the condition is
+    # the SAME one `.filter()` uses, so the checker validates it and renaming a column breaks the
+    # rule at type-check time, not in production.
+    SnakeChecks: ClassVar[list[SnakeCheckInfo]] = []
+
+    @property
+    def aggregate(self) -> _AggregateNamespace:
+        """EMERGENCY EXIT to the annotated aggregates by dynamic name (`object`, demands a cast).
+
+        Returns a per-instance namespace whose `__getattr__` gives `object` (NEVER `Any`): the checker
+        forces a `cast()` on you and gives you no IntelliSense. The typed road is `@snake_result`. If
+        the instance was not annotated, or the name does not exist, `SnakeAggregateNotLoaded` is raised.
+        """
+        values: Mapping[str, object] | None = getattr(self, _AGGREGATES_KEY, None)
+        return _AggregateNamespace(values)
+
+
+# The tuple is LITERAL: PEP 681 does not accept a constant here (see SNAKE_FIELD_SPECIFIERS in
+# `fields/__init__.py`, the canonical reference, which a test ties this literal to).
+@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,
+    ),
+)
+class SnakeView:
+    """VIEW base: like `SnakeModel`, but it marks the model as READ-ONLY.
+
+    A database view (`@snake_view`) is queried and NAVIGATED exactly like a model, but it is NOT
+    written: `session.add/update/delete/...` do not accept it. The lock is one of TYPES — those
+    methods ask for a `SnakeModel`, and a `SnakeView` does NOT inherit from `SnakeModel`, so it does
+    not fit — backed by a reinforcing runtime guard in the session.
+
+    It carries its own `@dataclass_transform` (independent of `SnakeModel`'s) because it is also
+    INSTANTIATED: the user does not build it by hand, but the session does when HYDRATING each row of
+    the view. That way its generated `__init__` ends up typed just like a model's.
+    """
+
+    SnakeComment: ClassVar[str | None] = None
+
+
+def attach_aggregates(instance: object, values: Mapping[str, object]) -> None:
+    """Stores on the instance the dict of aggregates the `aggregate` escape hatch exposes.
+
+    `session.annotate(...)` calls it after hydrating the base row. It uses `object.__setattr__`
+    because models keep their state per attribute (there are no `__slots__`), as descriptors do.
+    """
+    object.__setattr__(instance, _AGGREGATES_KEY, dict(values))

snakeorm/query/__init__.py

@@ -0,0 +1,9 @@
+"""SnakeORM's query layer: the SnakeQuery builder and the explicit JOIN SnakeJoinedQuery."""
+
+from snakeorm.query.compound import SnakeCompound as SnakeCompound
+from snakeorm.query.compound import SnakeCompoundBranch as SnakeCompoundBranch
+from snakeorm.query.compound import SnakeSetOp as SnakeSetOp
+from snakeorm.query.join_kind import SnakeJoin as SnakeJoin
+from snakeorm.query.joined import SnakeJoinedQuery as SnakeJoinedQuery
+from snakeorm.query.query import SnakeQuery as SnakeQuery
+from snakeorm.query.recursive import SnakeRecursive as SnakeRecursive