snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/session/coercion.py

@@ -0,0 +1,306 @@
+"""Coercion of the driver's values to the declared python_type (the ORM is type-first: it guarantees the type).
+
+DBAPI drivers do not always return the exact type (psycopg2 hands UUIDs back as str). The converters
+are IDEMPOTENT, so they work for any driver without coupling to it. No converter for `int` on
+purpose: `Decimal` -> `int` would truncate in silence.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from datetime import UTC, date, datetime, time, timedelta
+from decimal import Decimal
+from enum import Enum
+from typing import get_origin
+from uuid import UUID
+
+from snakeorm.core.converters import from_db_for, mark_builtin
+from snakeorm.core.exceptions import SnakeValueError
+from snakeorm.times import SnakeUtc
+
+
+def _to_uuid(value: object) -> object:
+    """psycopg2 returns UUID columns as `str`; other drivers already hand back a `UUID`."""
+    return value if isinstance(value, UUID) else UUID(str(value))
+
+
+def _to_float(value: object) -> object:
+    """A Postgres `numeric` (AVG/SUM over numeric) arrives as a `Decimal`. It only converts
+    numerics; the rest passes through untouched instead of blowing up."""
+    if isinstance(value, float):
+        return value
+    if isinstance(value, (int, Decimal)):
+        return float(value)
+    return value
+
+
+def _to_bool(value: object) -> object:
+    """Converts to `bool` whatever the engine returns as 0/1 (SQLite stores integers; Postgres
+    already hands back a `bool`, idempotent)."""
+    return bool(value)
+
+
+def _to_json(value: object) -> object:
+    """Returns a `dict` out of whatever each engine hands over: Postgres already gives a `dict`
+    (jsonb), SQLite gives TEXT and it gets parsed. Idempotent."""
+    if isinstance(value, str):
+        return json.loads(value)
+    return value
+
+
+def _to_decimal(value: object) -> object:
+    """Rebuilds the `Decimal` out of whatever each engine returns (Postgres already gives a
+    `Decimal`, SQLite gives text). It is parsed from the TEXT, never from a `float`: going through
+    floating point would corrupt the precision (`1234.56` -> `1234.5599...`), exactly what a
+    `Decimal` avoids.
+    """
+    if isinstance(value, Decimal):
+        return value
+    if isinstance(value, (str, int)):
+        return Decimal(value)
+    return value
+
+
+def _to_list(value: object) -> object:
+    """Rebuilds the list out of whatever each engine returns.
+
+    Postgres has arrays and psycopg2 already hands over a `list`; SQLite and MySQL do not have them,
+    so the column is TEXT and what arrives is the JSON `adapt_param` wrote. Idempotent, and therein
+    lies the trick that lets the converter registry be engine-agnostic while the SQL type is not:
+    the same code swallows both shapes, so nobody has to ask which engine they are on.
+
+    A text that is NOT JSON passes through untouched instead of blowing up: in Postgres a text column
+    declared `list[str]` is an error of the model, and the error has to come out over there and not here.
+    """
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return value
+    return value
+
+
+def _to_bytes(value: object) -> object:
+    """A Postgres `bytea` arrives as a `memoryview`, not as `bytes`. The bug is invisible (it
+    compares equal with `==`) until somebody does `hashlib.sha256(row.blob)`."""
+    if isinstance(value, memoryview):
+        return value.tobytes()
+    return value
+
+
+def _to_snake_utc(value: object) -> object:
+    """Rebuilds a `SnakeUtc` out of whatever the driver returns.
+
+    Without this the column would promise an instant in UTC and hand back a bare `datetime`: the
+    declared type would stop being the type received, which is the central promise of the project.
+    """
+    read_back = _to_datetime(value)
+    assert isinstance(
+        read_back, datetime
+    )  # `_to_datetime` normalises already or raises
+    return (
+        SnakeUtc.of(read_back)
+        if read_back.tzinfo
+        else SnakeUtc.of(read_back.replace(tzinfo=UTC))
+    )
+
+
+def _to_datetime(value: object) -> object:
+    """Rebuilds the `datetime` from SQLite's ISO 8601 (Postgres already gives a `datetime`,
+    idempotent; SQLite gives text ever since Python 3.12 withdrew its default converters)."""
+    if isinstance(value, str):
+        return datetime.fromisoformat(value)
+    return value
+
+
+def _to_date(value: object) -> object:
+    """The same for `date`. A `datetime` is NOT truncated here: that would be inventing a conversion."""
+    if isinstance(value, str):
+        return date.fromisoformat(value)
+    return value
+
+
+def _to_time(value: object) -> object:
+    """Rebuilds the `time` from what each engine hands back. Idempotent on Postgres.
+
+    SQLite returns ISO text. **MySQL returns a `timedelta`**, and it is not a driver quirk: its
+    `TIME` is a DURATION (-838:59:59 to 838:59:59), so PyMySQL is right to hand one over. A column
+    declared `time` still has to come back as a `time`, which is this ORM's whole contract.
+
+    A duration that does not fit in a day is not a clock reading, and it RAISES instead of wrapping
+    round: `timedelta(hours=30)` quietly becoming `06:00` is a wrong answer wearing the face of a
+    right one.
+    """
+    if isinstance(value, str):
+        return time.fromisoformat(value)
+    if isinstance(value, timedelta):
+        if not timedelta(0) <= value < timedelta(days=1):
+            raise SnakeValueError(
+                f"a column declared `time` came back as {value!r}, which is not a time of day. "
+                f"MySQL's TIME stores a duration and reaches from -838:59:59 to 838:59:59; declare "
+                f"the column `timedelta` if that is what it holds."
+            )
+        hours, rest = divmod(value.seconds, 3600)
+        minutes, seconds = divmod(rest, 60)
+        return time(hours, minutes, seconds, value.microseconds)
+    return value
+
+
+_DURATION = re.compile(
+    r"^(?:(?P<days>-?\d+) days?, )?(?P<hours>-?\d+):(?P<minutes>\d{2}):"
+    r"(?P<seconds>\d{2})(?:\.(?P<micros>\d{1,6}))?$"
+)
+
+
+def _to_timedelta(value: object) -> object:
+    """Rebuilds the `timedelta` from the text of `str(timedelta)` (Postgres already gives a
+    `timedelta` via `interval`, idempotent; SQLite gives text). A text that does NOT match passes
+    through untouched instead of blowing up.
+    """
+    if not isinstance(value, str):
+        return value
+    parts = _DURATION.match(value)
+    if parts is None:
+        return value
+    days = int(parts["days"] or 0)
+    hours = int(parts["hours"])
+    sign = -1 if hours < 0 or (parts["hours"] or "").startswith("-") else 1
+    return timedelta(
+        days=days,
+        hours=hours,
+        minutes=sign * int(parts["minutes"]),
+        seconds=sign * int(parts["seconds"]),
+        microseconds=sign * int((parts["micros"] or "0").ljust(6, "0")),
+    )
+
+
+_CONVERTERS: dict[type, Callable[[object], object]] = {
+    SnakeUtc: _to_snake_utc,
+    UUID: _to_uuid,
+    dict: _to_json,
+    Decimal: _to_decimal,
+    bytes: _to_bytes,
+    datetime: _to_datetime,
+    date: _to_date,
+    time: _to_time,
+    timedelta: _to_timedelta,
+    float: _to_float,
+    bool: _to_bool,
+}
+
+
+# They are declared at import time, and not listed by hand in `core/`: the source is this very
+# registry, so adding an internal converter protects it on its own. `core/` cannot import from here
+# (it would be a cycle between layers), so the direction is this one: the upper layer registers
+# itself as it loads.
+mark_builtin(_CONVERTERS.keys())
+
+
+def _to_decimal_with_scale(scale: int) -> Callable[[object], object]:
+    """Converter for a `Decimal` column that DECLARES a scale: it pads the value out to it.
+
+    Adding zeros is safe; rounding is not, and this only ever adds. That is not a hope, it is
+    guaranteed by the other half: `_guard_declared_limits` refuses on WRITE any value carrying more
+    decimals than the scale, so nothing with more can be in the database to begin with. `quantize`
+    here can only ever go the padding direction.
+
+    It exists because the engines disagreed and the disagreement reached the screen. Postgres and
+    MySQL apply the declared scale in storage and hand back `Decimal('1.00')`; SQLite keeps the text
+    it was given and hands back `Decimal('1')`. The same NUMBER — `Decimal('1') == Decimal('1.00')`
+    — so arithmetic never noticed, and `str()` did: one price printed `1` on one engine and `1.00`
+    on another, out of one model.
+    """
+    exponent = Decimal(1).scaleb(-scale)
+
+    def convert(value: object) -> object:
+        """`Decimal('1')` -> `Decimal('1.00')`, from whatever each engine handed over."""
+        rebuilt = _to_decimal(value)
+        return rebuilt.quantize(exponent) if isinstance(rebuilt, Decimal) else rebuilt
+
+    return convert
+
+
+def converter_for(
+    python_type: object, scale: int | None = None
+) -> Callable[[object], object] | None:
+    """The converter of a type, resolved ONCE, or `None` if the value passes through as is.
+
+    It is resolved by TYPE (fixed per column), not per row, so as not to repeat the
+    `issubclass`/lookup on the hot path; `None` avoids paying for a call per column with no conversion.
+
+    Uniform CONTRACT: the converter does NOT handle the NULL — the caller guards it (`value is None`
+    BEFORE invoking). A NULL is of another type (`_to_bool(None)` would give `False`, `_to_uuid(None)`
+    would blow up); the inline guard in `hydrate` is free, and having NONE of them be None-safe stops
+    one from handling it while another does not."""
+    if python_type is Decimal and scale is not None:
+        # The DECLARED scale travels with the column, so the value comes back carrying it whichever
+        # engine stored it. See `_to_decimal_with_scale`: it only ever pads.
+        return _to_decimal_with_scale(scale)
+    if isinstance(python_type, type) and issubclass(python_type, Enum):
+        # An enum is built by calling it, and it is idempotent with an already-built member.
+        return _to_enum(python_type)
+    # `python_type` is accepted as `object` because a column may declare a generic alias
+    # (`list[str]`), which is NOT a class. Only `type`s can be in the registry.
+    registered = from_db_for(python_type)
+    if registered is not None:
+        # A domain type declared with `register_converter`. It is consulted BEFORE the internal
+        # registry so that a subclass of a handled type (of `str`, say) can declare its own way back;
+        # without this it would come back as its base and the declared type would stop being the one
+        # you receive, which is the silent failure this ORM does not commit.
+        return registered
+    if get_origin(python_type) is dict:
+        # The twin of the `list` case below, and it was missing for the same reason it went
+        # unnoticed: the compiler refused a parameterised dict before anybody could get here. With
+        # that refusal lifted, no converter means the attribute declared `dict[str, object]` holds
+        # the raw JSON string — and on an engine where the column is TEXT nothing complains at all.
+        return _CONVERTERS.get(dict)
+    if get_origin(python_type) is list:
+        # This used to return `None`, and on Postgres it got away with it because psycopg2 already
+        # hands over a list. On the engines without arrays the column is TEXT, so with no converter
+        # the attribute declared `list[str]` would have held the raw JSON.
+        return _to_list
+    if not isinstance(python_type, type):
+        return None
+    return _CONVERTERS.get(python_type)
+
+
+def _to_enum(enum_type: type[Enum]) -> Callable[[object], object]:
+    """Converter for a concrete enum, closed over its class. It does NOT handle the NULL (the
+    contract is in `converter_for`): the caller guards `value is None` beforehand."""
+
+    def convert(value: object) -> object:
+        """`Level("pro")` -> `Level.PRO`."""
+        return enum_type(value)
+
+    return convert
+
+
+def coerce(value: object, python_type: object, scale: int | None = None) -> object:
+    """Coerces `value` to the declared `python_type`. NULL and the types with no converter pass through untouched.
+
+    A DELEGATION and not a second implementation, and that is the whole point. This is the door the
+    write-back path comes through —the RETURNING of `add()`/`refresh()`, and `annotate`/prefetch—
+    while `hydrate` comes through `converter_for`. Two doors into the same wardrobe: a value that
+    went in one way and came out the other must not have changed TYPE on the trip. A subset here
+    drifts, and what it drops is the user's own registrations: `from_db_for` — what
+    `register_converter` fills — and the generic aliases. Measured,
+    `converter_for(list[str])('["a","b"]')` gives `['a', 'b']` while a hand-rolled subset gave back
+    the raw JSON string, so the same column read as a list through `all()` and as a `str` through
+    `add()`.
+
+    `python_type` is `object` and not `type` for the reason `converter_for` states: a column may
+    declare a generic alias (`list[str]`), which is not a class.
+
+    `scale` has to travel too, or the two doors disagree one parameter further down: without it the
+    same column comes back `Decimal('1.00')` through `all()` and `Decimal('1')` through
+    `add()`/`refresh()` — and `refresh()` is the sharp one, it takes an object that was already
+    right and makes it worse. That stays invisible because `Decimal('1') == Decimal('1.00')` is
+    True: every equality passes across the gap and arithmetic never notices. It shows up in
+    `str()`, on a screen.
+    """
+    if value is None:
+        return None
+    converter = converter_for(python_type, scale)
+    return converter(value) if converter is not None else value

snakeorm/session/factory.py

@@ -0,0 +1,29 @@
+"""Session factory keyed by connection NAME."""
+
+from __future__ import annotations
+
+from snakeorm.core.config import DEFAULT_DATABASE, backend_name_for, dsn_for
+from snakeorm.session.session import SnakeSession
+
+
+def snake_session(database: str = DEFAULT_DATABASE) -> SnakeSession:
+    """Opens a session against the connection with that name, resolving the DSN by configuration.
+
+    A single path for the common case (multi-DB). Whoever needs to decorate the driver (logging,
+    pool, timeout) still builds the session by hand: this is convenience, not a replacement for the
+    seam.
+
+    Pairing driver and dialect is delegated to `SnakeConnectionConfig`, which exists precisely so
+    that a driver cannot be put together with another engine's dialect. Two composition roots are
+    one too many: the one nobody reviews is the one that ends up lying. The engine is READ like the
+    DSN is (see `backend_name_for`); hardcoding it would reach only one of the three.
+    """
+    # Lazy, and not for performance: `connection.py` imports `session` so it can return a session,
+    # so importing it up top would close the cycle. That is the natural direction — the connection
+    # config sits ABOVE the session, not the other way around — and this function is the
+    # convenience exception that swims against it.
+    from snakeorm.connection import SnakeBackend, SnakeConnectionConfig
+
+    return SnakeConnectionConfig.from_dsn(
+        dsn_for(database), SnakeBackend(backend_name_for(database))
+    ).open()

snakeorm/session/guards.py

@@ -0,0 +1,269 @@
+"""The guards of a DECLARED limit: they are enforced in Python, before touching the database.
+
+`snake_str(max_length=5)`, `snake_int(size=SMALLINT)` and `snake_decimal(precision=, scale=)` are
+rules of the DOMAIN, not DDL ornaments. The ORM enforces them on write and does not delegate to the
+engine, for two reasons: SQLite ignores the declared parameter — so in dev nothing would fail and in
+prod it would — and when the engine does complain, it does so in its own jargon and halfway through
+a bulk write.
+
+They live here and not inside the session because they are not execution: they do not talk to the
+driver, know nothing of transactions and do not depend on whether anyone awaited. The SYNCHRONOUS
+session had them inside it, so the asynchronous one depended on it in order not to duplicate them —
+one layer importing its sibling to ask it for something that belongs to neither of them.
+
+None of them truncates or rounds. A `max_length` that cuts the string turns a rule into silent data
+loss; the ORM shouts and whoever is writing decides.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime
+from decimal import Decimal
+
+from snakeorm.core.exceptions import (
+    SnakeEmitError,
+    SnakeUnsupportedFeature,
+    SnakeValueError,
+)
+from snakeorm.dialects.base import SnakeDialect
+from snakeorm.dialects.capabilities import Cap, Nope
+from snakeorm.metadata import (
+    SnakeColumnInfo,
+    SnakeIntSize,
+    SnakeTableInfo,
+)
+from snakeorm.fields import MISSING
+from snakeorm.times import SnakeUtc
+
+
+# Range of a signed integer per declared width. It is what Postgres enforces and SQLite does not:
+# SQLite collapses every integer into its 64-bit INTEGER, so an overflowed SMALLINT gets in.
+_INT_RANGES: dict[SnakeIntSize, tuple[int, int]] = {
+    SnakeIntSize.SMALLINT: (-(2**15), 2**15 - 1),
+    SnakeIntSize.INTEGER: (-(2**31), 2**31 - 1),
+    SnakeIntSize.BIGINT: (-(2**63), 2**63 - 1),
+}
+
+
+def _guard_declared_limits(table: SnakeTableInfo, values: dict[str, object]) -> None:
+    """Rejects a value that falls outside its column's DECLARED limit, before touching the database.
+
+    A declared knob (`scale`, `max_length`, `int_size`) is a rule of the domain. If the ORM only
+    writes it into the DDL, the ENGINE is what enforces it — and then it means different things
+    depending on where you run: Postgres rejects (`value too long`, `smallint out of range`) and
+    SQLite accepts, because it ignores the VARCHAR's length and collapses the integers. Checking it
+    here makes it hold on BOTH.
+
+    This is no detail: the SQLite dialect exists so one can work without a server, so without this
+    the suite comes out green in development and the deployment to Postgres blows up.
+
+    It SHOUTS, it never trims: truncating the text or rounding the number would be converting behind
+    the developer's back. The value gets fixed by whoever wrote it.
+    """
+    for column in table.columns:
+        value = values.get(column.name)
+        if value is None or column.name not in values:
+            continue  # a NULL is not measured: nullability is decided by the annotation, not by these limits
+        _guard_scale(table, column, value)
+        _guard_length(table, column, value)
+        _guard_int_range(table, column, value)
+        _guard_timezone(table, column, value)
+
+
+def _guard_scale(table: SnakeTableInfo, column: SnakeColumnInfo, value: object) -> None:
+    """Decimal places of a `Decimal` against the declared `scale`.
+
+    NaN/Inf (a non-numeric exponent) pass through so the engine rejects them, with a more specific
+    message than could be given here.
+    """
+    if column.scale is None or not isinstance(value, Decimal):
+        return
+    exponent = value.as_tuple().exponent
+    if isinstance(exponent, int) and -exponent > column.scale:
+        raise SnakeValueError(
+            f"{table.name}.{column.name} declares scale={column.scale} but an attempt was made to "
+            f"write {value}, with {-exponent} decimal places. Quantize it yourself "
+            f"(value.quantize(...)) before saving it: the ORM does not round in silence."
+        )
+
+
+def _guard_length(
+    table: SnakeTableInfo, column: SnakeColumnInfo, value: object
+) -> None:
+    """Length of a text against the declared `max_length`. The limit is INCLUSIVE."""
+    if column.max_length is None or not isinstance(value, str):
+        return
+    if len(value) > column.max_length:
+        raise SnakeValueError(
+            f"{table.name}.{column.name} declares max_length={column.max_length} but an attempt was "
+            f"made to write a text of {len(value)} characters. Trim it yourself before saving it: "
+            f"the ORM does not truncate in silence."
+        )
+
+
+def _guard_timezone(
+    table: SnakeTableInfo, column: SnakeColumnInfo, value: object
+) -> None:
+    """Demands that a `datetime` say the same thing as its column about carrying a zone, and be UTC.
+
+    It is the runtime safety net: the type already prevents it in the editor (`SnakeUtc` cannot be
+    built outside UTC), but whoever skips the checker also deserves a clear message.
+
+    On a `SnakeUtc` column (`TIMESTAMPTZ`) ONLY UTC is admitted. The column stores the INSTANT, not
+    the offset: were `14:30+02:00` accepted, Postgres would return `12:30+00:00` and SQLite
+    `14:30+02:00`, that is, `.hour` would be 12 or 14 depending on the engine.
+
+    On a `datetime` column (`TIMESTAMP`, wall-clock time) the opposite is rejected: discarding a
+    `tzinfo` really does destroy the instant, silently and only sometimes.
+    """
+    if not isinstance(value, datetime):
+        return
+    offset = value.utcoffset()
+    if column.python_type is SnakeUtc:
+        if offset is None:
+            raise SnakeValueError(
+                f"{table.name}.{column.name} stores an instant (with a zone) but {value!r} does not "
+                f"carry one, so it identifies none: the same 14:30 is a different moment in "
+                f"Madrid and in Bogotá. Place it with utc_from_zone(value, 'Europe/Madrid') or "
+                f"use SnakeUtc.now(); if it really is a wall-clock time, declare it with "
+                f"snake_datetime() and SnakeColumn[datetime]."
+            )
+        if offset:
+            raise SnakeValueError(
+                f"{table.name}.{column.name} only accepts UTC and {value!r} comes with offset "
+                f"{offset}. The column stores the INSTANT, not the offset: Postgres would give "
+                f"it back to you in UTC and SQLite with the original offset, so `.hour` would "
+                f"change from engine to engine. Convert it yourself with to_utc(value): the ORM "
+                f"does not change zone in silence."
+            )
+        return
+    if column.python_type is not datetime:
+        return
+    if offset is not None:
+        raise SnakeValueError(
+            f"{table.name}.{column.name} is declared SnakeColumn[datetime], that is, a WALL-CLOCK "
+            f"TIME, and {value!r} carries a zone. Saving it would throw away the tzinfo and with "
+            f"it the instant, silently. If you meant to store the instant, declare the column "
+            f"SnakeColumn[SnakeUtc]; if it really is a wall-clock time, pass a datetime without "
+            f"a zone."
+        )
+
+
+def _guard_int_range(
+    table: SnakeTableInfo, column: SnakeColumnInfo, value: object
+) -> None:
+    """Value of an integer against the range of its declared width.
+
+    It dispatches on the column's DECLARED TYPE, not on the value's: in Python `bool` is a subclass
+    of `int`, so looking at the value would measure the width of a boolean column.
+    """
+    if column.python_type is not int or not isinstance(value, int):
+        return
+    minimum, maximum = _INT_RANGES[column.int_size]
+    if not minimum <= value <= maximum:
+        raise SnakeValueError(
+            f"{table.name}.{column.name} declares {column.int_size.name} (from {minimum} to {maximum}) "
+            f"but an attempt was made to write {value}. Postgres would reject it and SQLite would "
+            f"accept it: the ORM rejects it on both so that your model means the same on either."
+        )
+
+
+def _guard_required_values(
+    table: SnakeTableInfo, raw_values: Mapping[str, object]
+) -> None:
+    """Shouts if a MANDATORY column arrives carrying the `MISSING` sentinel instead of a value.
+
+    Leaving a `MISSING` out of the INSERT is the right thing almost always — an autoincrementing PK,
+    a column with a default, one the server fills in — and that is why the silence got mistaken for
+    the norm. What is separated out here is the case where omitting is exactly the opposite: NOT
+    NULL, with no default of any kind and no autoincrement. There the `MISSING` does not mean "let
+    the database put it in", it means nobody put it in, and taking it out of the INSERT turns a
+    program error into an engine problem.
+
+    Where a `MISSING` sneaking in as a value comes from: on an engine without `RETURNING`, an
+    `add_all()` leaves the PKs unfilled, and that id which never came back ends up being the foreign
+    key of the next row. Four steps in silence, and an `INSERT INTO bridge () VALUES ()` at the end
+    that points at none of them.
+    """
+    for column in table.columns:
+        if raw_values.get(column.name, None) is not MISSING:
+            continue
+        if _fills_itself(column):
+            continue
+        raise SnakeValueError(
+            f"'{table.name}.{column.name}' is mandatory (NOT NULL, without a default and without "
+            f"autoincrement) and an attempt was made to write it without a value. It usually means "
+            f"the value comes from another row whose id never came back: on an engine without "
+            f"RETURNING, `add_all()` does not fill in autoincrementing keys, so use `add()` for "
+            f"the rows whose id you need afterwards."
+        )
+
+
+def _fills_itself(column: SnakeColumnInfo) -> bool:
+    """Whether it is legitimate for the column to arrive with no value: somebody puts it in for it.
+
+    Four ways for that to be so, and all four count: it accepts NULL, the database generates it, it
+    carries a declared default, or the server puts it in. Missing one would turn this guard into a
+    false positive over perfectly correct models, which is how a guard dies.
+    """
+    return (
+        column.nullable
+        or column.autoincrement
+        or column.has_default
+        or column.default_factory is not None
+        or column.has_server_default
+    )
+
+
+def guard_uniform_bulk_columns(rows: list[dict[str, object]], model_name: str) -> None:
+    """Every instance of an `add_all` must carry the SAME columns. Refuses the batch if not.
+
+    The second half of a requirement stated three lines above the caller: `add_all` demands a single
+    MODEL. One model does not mean one shape — a column with a server default stays out of
+    `__init__`, so two instances of the same class can legitimately end up with different sets of
+    assigned values, and rows with different columns cannot share one multi-row INSERT. Without this
+    guard the POSITION of an element in the list decided between a loud error and a silent loss of
+    data: an empty first row emitted `DEFAULT VALUES` for EVERY instance, while the same two rows
+    the other way round raised. Same batch, opposite outcomes, decided by the order they were
+    appended in.
+
+    Refusing rather than splitting the batch into groups is the same answer the emitter already
+    gives, and it is the one this ORM's doctrine asks for: what cannot be done as asked gets said,
+    not quietly turned into something else. Grouping would also hand back rows in an order the
+    caller did not choose, which `add_all` promises it does not do.
+    """
+    if len(rows) < 2:
+        return
+    shapes = {tuple(sorted(row)) for row in rows}
+    if len(shapes) == 1:
+        return
+    spellings = sorted(
+        ", ".join(shape) if shape else "(no columns)" for shape in shapes
+    )
+    raise SnakeEmitError(
+        f"Every row of a bulk INSERT must have the same columns, and these {model_name} "
+        f"instances do not: {' / '.join(spellings)}. One model does not mean one shape — a column "
+        f"with a server default stays out of the constructor, so assigning it on some instances "
+        f"and not others splits the batch. Either assign it on all of them or on none, or call "
+        f"add() per instance."
+    )
+
+
+def guard_can_set_isolation(dialect: SnakeDialect) -> None:
+    """Refuses `SET TRANSACTION ISOLATION LEVEL` on an engine that declares it cannot.
+
+    It lives here, in one piece called by BOTH colours, and that is the whole point of moving it.
+    The synchronous session asked the catalogue and the asynchronous one handed the statement
+    straight to the driver, so SQLite answered `near "SET": syntax error` — the exact failure the
+    synchronous docstring says the check exists to prevent, reproduced in the other colour because
+    the fix had only been applied to one.
+
+    A session emitting engine SQL without asking is also what the dialect seam exists to stop, so
+    the drift was not only about wording: half the ORM was reaching past the seam.
+    """
+    support = dialect.capabilities.support_for(Cap.SET_ISOLATION)
+    if isinstance(support, Nope):
+        raise SnakeUnsupportedFeature(
+            f"{type(dialect).__name__} cannot set the isolation level: {support.reason}."
+        )

snakeorm/session/isolation.py

@@ -0,0 +1,23 @@
+"""Transaction isolation levels."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SnakeIsolation(Enum):
+    """What a transaction sees of what the others are doing while it is alive.
+
+    STANDARD SQL values (not engine jargon), the other half of concurrency control alongside
+    `for_update()`: the lock says which rows you reserve, the isolation what you see meanwhile.
+
+    - `READ_COMMITTED`: each statement sees what was committed at its instant (Postgres default).
+    - `REPEATABLE_READ`: a still photo of the whole transaction; a write conflict aborts it.
+    - `SERIALIZABLE`: as if they ran single file. The strongest guarantee and the one that aborts most.
+    - `READ_UNCOMMITTED`: for standard completeness; Postgres treats it as `READ COMMITTED`.
+    """
+
+    READ_UNCOMMITTED = "READ UNCOMMITTED"
+    READ_COMMITTED = "READ COMMITTED"
+    REPEATABLE_READ = "REPEATABLE READ"
+    SERIALIZABLE = "SERIALIZABLE"