sqlmodel-ext 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

sqlmodel_ext/__init__.py

@@ -20,7 +20,7 @@ Quick start::
     user = await user.save(session)
     users = await User.get(session, fetch_mode="all")
 """
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 
 # Base
 from sqlmodel_ext.base import SQLModelBase, ExtraIgnoreModelBase, CustomTableArg

sqlmodel_ext/base.py

@@ -9,6 +9,7 @@ Provides a smart metaclass that handles:
 - Annotated sa_type extraction and injection
 - Python 3.14 (PEP 649) compatibility
 """
+import ast
 import copy
 import logging
 import re
@@ -22,7 +23,7 @@ from pydantic import ConfigDict, model_validator
 from pydantic.fields import FieldInfo
 from pydantic_core import PydanticUndefined as Undefined
 from sqlalchemy import inspect as sa_inspect
-from sqlalchemy.orm import Mapped, relationship as sa_relationship
+from sqlalchemy.orm import Mapped, declared_attr, relationship as sa_relationship
 from sqlmodel import Field, SQLModel
 from sqlmodel.main import (
     SQLModelMetaclass,
@@ -33,6 +34,14 @@ from sqlmodel.main import (
     get_column_from_field,  # Internal API: stable since sqlmodel 0.0.22
 )
 
+# sqlmodel 0.0.32+ FieldInfoMetadata is a @dataclass whose auto-generated
+# __eq__ causes __hash__ = None.  Annotated[T, FieldInfoMetadata(...)] then
+# becomes unhashable, breaking FastAPI's OpenAPI set-based dedup in
+# get_definitions().  Restore identity-based hashing until upstream fixes it.
+# Ref: https://github.com/fastapi/sqlmodel/pull/1889
+if getattr(FieldInfoMetadata, '__hash__') is None:
+    FieldInfoMetadata.__hash__ = object.__hash__  # type: ignore[assignment]
+
 # sqlmodel's FieldInfoMetadata fields default to sqlmodel's own Undefined
 # sentinel (distinct from pydantic_core PydanticUndefined imported above);
 # capture it to detect "sa_type not yet set" without importing sqlmodel internals.
@@ -593,6 +602,99 @@ def _recover_annotated_sqlmodel_fields(
             annotations[field_name] = new_inner
 
 
+def _is_none_node(node: ast.expr) -> bool:
+    """Whether a type-expression AST node denotes ``None`` / ``NoneType``."""
+    if isinstance(node, ast.Constant) and node.value is None:
+        return True
+    return isinstance(node, ast.Name) and node.id in ('None', 'NoneType')
+
+
+def _relationship_target_node(node: ast.expr) -> ast.expr | None:
+    """
+    Extract the single non-``None`` target node from a type-expression AST.
+
+    Covers every shape a relationship annotation can take: ``Foo`` / ``pkg.Foo`` /
+    ``Foo | None`` / ``None | Foo`` / ``Optional[Foo]`` / ``Union[Foo, None]``, plus
+    an inner requoted form (``Optional['Foo']``). When the expression cannot be
+    reduced to a single target (e.g. a multi-member union ``Foo | Bar``), returns
+    ``None`` so the caller hands the annotation back to SQLModel's native parser
+    untouched, letting it raise its own clear error.
+    """
+    # Bare class name / dotted (module-qualified) class name.
+    if isinstance(node, (ast.Name, ast.Attribute)):
+        return node
+    # Inner requoted string constant (e.g. ``Optional['Foo']``): recurse into it.
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        try:
+            return _relationship_target_node(ast.parse(node.value.strip(), mode='eval').body)
+        except SyntaxError:
+            return None
+    # ``A | None`` / ``None | A``.
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+        left_none, right_none = _is_none_node(node.left), _is_none_node(node.right)
+        if left_none ^ right_none:  # exactly one side is None
+            return _relationship_target_node(node.right if left_none else node.left)
+        return None
+    # ``Optional[A]`` / ``Union[A, None]``.
+    if isinstance(node, ast.Subscript):
+        base = node.value
+        base_name = (
+            base.id if isinstance(base, ast.Name)
+            else base.attr if isinstance(base, ast.Attribute)
+            else None
+        )
+        if base_name == 'Optional':
+            return _relationship_target_node(node.slice)
+        if base_name == 'Union':
+            elts = node.slice.elts if isinstance(node.slice, ast.Tuple) else [node.slice]
+            non_none = [e for e in elts if not _is_none_node(e)]
+            if len(non_none) == 1:
+                return _relationship_target_node(non_none[0])
+    return None
+
+
+def _resolve_relationship_target(
+    name: str,
+    rel_info: typing.Any,
+    annotation: typing.Any,
+) -> typing.Any:
+    """
+    Wrapper around SQLModel's ``get_relationship_to`` that first normalizes a
+    flat-string / ``ForwardRef`` nullable relationship annotation (e.g.
+    ``'UserFolder | None'``) into a structured ``ForwardRef('UserFolder')`` via
+    ``ast``, then delegates to upstream.
+
+    Root cause: ``get_relationship_to`` can only strip ``None`` from an
+    **already-evaluated** ``typing.Union``; it cannot parse a whole-string PEP 604
+    annotation -- it would treat the entire ``'UserFolder | None'`` string as the
+    class name and hand it to SQLAlchemy. ``Optional['T']`` works only because
+    ``Optional[...]`` is evaluated at class-definition time into
+    ``Union[ForwardRef('T'), None]``, leaving just the inner ``'T'`` as a ForwardRef.
+
+    This wrapper lets relationship fields be annotated with the PEP 604
+    ``'X | None'`` form (pyright-friendly, no ``reportDeprecated`` from
+    ``Optional[...]``) and converts it back at runtime into a form
+    ``get_relationship_to`` recognizes. Already-evaluated typing objects
+    (``list[...]`` / ``Optional[...]`` / concrete classes) pass through unchanged;
+    unrecognized expressions are likewise passed through to upstream, preserving
+    its original error semantics. Note: only a temporary local value is produced
+    for resolution -- ``cls.__annotations__`` is left intact.
+    """
+    if isinstance(annotation, (str, typing.ForwardRef)):
+        expr = (
+            annotation.__forward_arg__
+            if isinstance(annotation, typing.ForwardRef)
+            else annotation
+        )
+        try:
+            target = _relationship_target_node(ast.parse(expr.strip(), mode='eval').body)
+        except SyntaxError:
+            target = None
+        if target is not None:
+            annotation = typing.ForwardRef(ast.unparse(target))
+    return get_relationship_to(name=name, rel_info=rel_info, annotation=annotation)
+
+
 def _make_sti_fk_resolver(
     fk_string: str,
     sa_registry: typing.Any,
@@ -765,6 +867,28 @@ class __DeclarativeMeta(SQLModelMetaclass):
             existing.update(collected_mapper_args)
             attrs['__mapper_args__'] = existing
 
+        # 3.5. OptimisticLockMixin wiring: register the mixin's ``version``
+        # column as SQLAlchemy's ``version_id_col`` so every UPDATE emits
+        # ``SET version = version + 1 WHERE ... AND version = :current`` and a
+        # lost update surfaces as StaleDataError. The Column object only exists
+        # after the Table is built, so this must be a ``declared_attr`` that
+        # declarative evaluates late. Only applied to the root table class --
+        # STI/JTI children inherit version_id_col from the root mapper.
+        if will_be_table and any(getattr(b, '_has_optimistic_lock', False) for b in bases):
+            _is_inheriting_table = parent_tablename is not None
+            if not _is_inheriting_table and 'version_id_col' not in attrs.get('__mapper_args__', {}):
+                _static_mapper_args = dict(attrs.get('__mapper_args__', {}))
+
+                def _mapper_args_with_version_col(target_cls, _static=_static_mapper_args):
+                    merged = dict(_static)
+                    merged['version_id_col'] = target_cls.__table__.c.version
+                    return merged
+
+                # ``.directive`` is SQLAlchemy 2.0's spelling for declarative
+                # dunder directives like __mapper_args__ (plain declared_attr
+                # on a dunder emits a usage warning).
+                attrs['__mapper_args__'] = declared_attr.directive(_mapper_args_with_version_col)
+
         # Process other explicit args
         if 'table_args' in kwargs:
             raw_table_args = kwargs.pop('table_args')
@@ -1172,7 +1296,7 @@ class __DeclarativeMeta(SQLModelMetaclass):
                                         ann = raw_ann.__args__[0]
                                     else:
                                         ann = raw_ann
-                                    relationship_to = get_relationship_to(
+                                    relationship_to = _resolve_relationship_target(
                                         name=rel_name, rel_info=rel_info, annotation=ann
                                     )
                                     rel_kwargs: dict[str, typing.Any] = {}
@@ -1267,7 +1391,7 @@ class __DeclarativeMeta(SQLModelMetaclass):
             else:
                 ann = raw_ann
 
-            relationship_to = get_relationship_to(
+            relationship_to = _resolve_relationship_target(
                 name=rel_name, rel_info=rel_info, annotation=ann
             )
             rel_kwargs: dict[str, typing.Any] = {}

sqlmodel_ext/field_types/__init__.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from typing import Annotated, Any, Generic, TypeAlias, TypeVar
 
 from annotated_types import Ge, Gt
-from pydantic import BeforeValidator, PlainSerializer, StringConstraints
+from pydantic import BeforeValidator, PlainSerializer, StringConstraints, WithJsonSchema
 from sqlalchemy import BigInteger, Numeric
 from sqlmodel import Field
 
@@ -373,6 +373,51 @@ This promotes "string at the boundary" from a documentation convention into a
 hard type-system contract.
 """
 
+# ---------------------------------------------------------------------------
+#  Decimal OpenAPI validation-schema fix (drop ``number``, keep ``string`` only)
+#
+#  Pydantic maps ``Decimal`` to ``anyOf: [number, string]`` in JSON Schema, but
+#  ``_reject_float_decimal_input`` rejects float at runtime (a JSON number with a
+#  decimal point *is* a float). So the docs would advertise ``0.00001005`` as a
+#  valid request value while the server returns 422 — a contract mismatch.
+#  ``WithJsonSchema(mode='validation')`` overrides the request-body schema only;
+#  response-body schemas are unaffected.
+# ---------------------------------------------------------------------------
+
+_DECIMAL_38_18_STR_PATTERN = (
+    r'^(?!^[-+.]*$)[+-]?0*(?:\d{0,20}|(?=[\d.]{1,39}0*$)\d{0,20}\.\d{0,18}0*$)'
+)
+_DECIMAL_20_10_STR_PATTERN = (
+    r'^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,21}0*$)\d{0,10}\.\d{0,10}0*$)'
+)
+
+_DECIMAL_38_18_STR_SCHEMA: WithJsonSchema = WithJsonSchema(
+    {'type': 'string', 'pattern': _DECIMAL_38_18_STR_PATTERN},
+    mode='validation',
+)
+_DECIMAL_20_10_STR_SCHEMA: WithJsonSchema = WithJsonSchema(
+    {'type': 'string', 'pattern': _DECIMAL_20_10_STR_PATTERN},
+    mode='validation',
+)
+_OPTIONAL_DECIMAL_38_18_STR_SCHEMA: WithJsonSchema = WithJsonSchema(
+    {
+        'anyOf': [
+            {'type': 'string', 'pattern': _DECIMAL_38_18_STR_PATTERN},
+            {'type': 'null'},
+        ]
+    },
+    mode='validation',
+)
+_OPTIONAL_DECIMAL_20_10_STR_SCHEMA: WithJsonSchema = WithJsonSchema(
+    {
+        'anyOf': [
+            {'type': 'string', 'pattern': _DECIMAL_20_10_STR_PATTERN},
+            {'type': 'null'},
+        ]
+    },
+    mode='validation',
+)
+
 # NUMERIC(38, 18) — 20 integer digits + 18 fractional digits (matches the EVM
 # wei = 1e-18 ether de-facto standard for high-precision amounts)
 
@@ -381,6 +426,7 @@ SignedDecimal38_18: TypeAlias = Annotated[
     _REJECT_FLOAT,
     Field(max_digits=38, decimal_places=18, sa_type=Numeric(38, 18)),  # pyright: ignore[reportArgumentType]
     _DECIMAL_TO_JSON_STR,
+    _DECIMAL_38_18_STR_SCHEMA,
 ]
 """NUMERIC(38, 18) Decimal, positive or negative"""
 
@@ -394,6 +440,7 @@ NonNegativeDecimal38_18: TypeAlias = Annotated[
     # annotated_types so the ignore scope stays minimal.
     Field(max_digits=38, decimal_places=18, sa_type=Numeric(38, 18)),  # pyright: ignore[reportArgumentType]
     _DECIMAL_TO_JSON_STR,
+    _DECIMAL_38_18_STR_SCHEMA,
 ]
 """NUMERIC(38, 18) Decimal, >= 0"""
 
@@ -404,6 +451,7 @@ PositiveDecimal38_18: TypeAlias = Annotated[
     # pyright ignore targets ``sa_type`` only (see NonNegativeDecimal38_18)
     Field(max_digits=38, decimal_places=18, sa_type=Numeric(38, 18)),  # pyright: ignore[reportArgumentType]
     _DECIMAL_TO_JSON_STR,
+    _DECIMAL_38_18_STR_SCHEMA,
 ]
 """NUMERIC(38, 18) Decimal, > 0"""
 
@@ -418,6 +466,7 @@ OptionalNonNegativeDecimal38_18: TypeAlias = Annotated[
     # pyright ignore targets ``sa_type`` only (see NonNegativeDecimal38_18)
     Field(default=None, sa_type=Numeric(38, 18)),  # pyright: ignore[reportArgumentType]
     _DECIMAL_TO_JSON_STR,
+    _OPTIONAL_DECIMAL_38_18_STR_SCHEMA,
 ]
 """NUMERIC(38, 18) Decimal, >= 0 or None"""
 
@@ -429,6 +478,7 @@ SignedDecimal20_10: TypeAlias = Annotated[
     _REJECT_FLOAT,
     Field(max_digits=20, decimal_places=10, sa_type=Numeric(20, 10)),  # pyright: ignore[reportArgumentType]
     _DECIMAL_TO_JSON_STR,
+    _DECIMAL_20_10_STR_SCHEMA,
 ]
 """NUMERIC(20, 10) Decimal, positive or negative"""
 
@@ -439,6 +489,7 @@ NonNegativeDecimal20_10: TypeAlias = Annotated[
     # pyright ignore targets ``sa_type`` only (see NonNegativeDecimal38_18)
     Field(max_digits=20, decimal_places=10, sa_type=Numeric(20, 10)),  # pyright: ignore[reportArgumentType]
     _DECIMAL_TO_JSON_STR,
+    _DECIMAL_20_10_STR_SCHEMA,
 ]
 """NUMERIC(20, 10) Decimal, >= 0"""
 
@@ -449,6 +500,7 @@ OptionalNonNegativeDecimal20_10: TypeAlias = Annotated[
     # pyright ignore targets ``sa_type`` only (see NonNegativeDecimal38_18)
     Field(default=None, sa_type=Numeric(20, 10)),  # pyright: ignore[reportArgumentType]
     _DECIMAL_TO_JSON_STR,
+    _OPTIONAL_DECIMAL_20_10_STR_SCHEMA,
 ]
 """NUMERIC(20, 10) Decimal, >= 0 or None"""
 

sqlmodel_ext/field_types/dialects/postgresql/array.py

@@ -12,8 +12,9 @@ Usage::
     # Limit to 20 elements
     version_vector: Array[dict, 20] = Field(default_factory=list)
 """
+import logging
 from enum import Enum
-from typing import TYPE_CHECKING, Annotated, Generic, TypeVar, final, get_origin
+from typing import TYPE_CHECKING, Annotated, Any, Callable, Generic, TypeVar, final, get_origin
 from uuid import UUID
 
 import sqlalchemy as sa
@@ -21,11 +22,107 @@ from pydantic import GetCoreSchemaHandler
 from pydantic_core import CoreSchema, core_schema
 from sqlalchemy import Integer, String
 from sqlalchemy.dialects.postgresql import ARRAY, JSONB, UUID as PG_UUID
+from sqlalchemy.engine.interfaces import Dialect
+
+logger = logging.getLogger(__name__)
 
 # --- Generic Type Definitions ---
 T = TypeVar('T')
 
 
+_UNKNOWN_ENUM_ELEM = object()
+"""Internal sentinel yielded by ``_TolerantEnum`` when it reads an unknown DB
+value; filtered out at the array level by ``_TolerantEnumArray``. A dedicated
+sentinel (rather than None) is used so it stays distinct from a genuine NULL
+element inside the array."""
+
+
+class _TolerantEnum(sa.TypeDecorator[Any]):
+    """Read-tolerant enum (a ``TypeDecorator`` wrapping ``sa.Enum``): when the
+    value returned by the database is not a member of the Python enum, it is
+    downgraded to a sentinel instead of raising ``LookupError``.
+
+    Motivation: during a rolling deployment's version-skew window, a newer pod
+    may run a migration that backfills a new enum value into an ``ARRAY(enum)``
+    column while an older pod -- still serving traffic with a Python enum that
+    lacks that value -- reads the row. ``sa.Enum`` raises ``LookupError`` on an
+    unknown value by default, so **every** request on the old pod that loads
+    such a row would 500 until the rollout completes.
+
+    Why a ``TypeDecorator`` rather than subclassing ``sa.Enum`` directly:
+    dialect adaptation (``dialect.colspecs`` -> ``type.adapt(impltype)``) copies
+    a ``sa.Enum`` subclass instance into a ``postgresql.ENUM`` / asyncpg
+    ``AsyncPgEnum`` instance, discarding the subclass overrides. ``TypeDecorator``
+    is SQLAlchemy's official mechanism for "behavior wrapping that must survive
+    dialect adaptation": the decorator itself stays as the column type, its impl
+    is adapted internally, and the ``result_processor`` hook is guaranteed to be
+    called.
+
+    Semantics: unknown values are dropped on the **read path only** (with a
+    warning); the write path still goes through Pydantic / PG enum strict
+    validation, so no dirty writes are introduced. Dropped values remain in the
+    database and become visible again once code that knows them is deployed (the
+    DB is the superset source of truth; each code version consumes the subset it
+    recognizes -- consistent with Pydantic's ``extra='ignore'`` handling of
+    unknown fields).
+    """
+
+    impl = sa.Enum
+    cache_ok = True
+
+    def __init__(self, enum_class: type[Enum], name: str):
+        super().__init__(
+            enum_class,
+            name=name,
+            values_callable=lambda e: [m.value for m in e],
+        )
+        self._enum_name = name
+
+    def result_processor(
+            self, dialect: Dialect, coltype: object,
+    ) -> 'Callable[[Any], Any]':
+        impl_processor = self.impl_instance.result_processor(dialect, coltype)
+
+        def process(value: Any) -> Any:
+            if value is None:
+                return None
+            try:
+                return impl_processor(value) if impl_processor is not None else value
+            except LookupError:
+                logger.warning(
+                    "Enum column read an unknown value %r (enum %s); ignored -- "
+                    "likely a rolling-deployment version-skew window (the DB holds "
+                    "a newer enum value that this process's code does not yet know).",
+                    value, self._enum_name,
+                )
+                return _UNKNOWN_ENUM_ELEM
+
+        return process
+
+
+class _TolerantEnumArray(sa.TypeDecorator[Any]):
+    """ARRAY companion to ``_TolerantEnum`` (a ``TypeDecorator`` wrapping
+    ``ARRAY``): filters out the unknown-enum sentinel elements while processing
+    results.
+
+    The sentinel is matched by identity (``is``) so genuine NULL elements
+    (``None``) inside the array are unaffected.
+    """
+
+    impl = ARRAY
+    cache_ok = True
+
+    def __init__(self, item_type: '_TolerantEnum'):
+        super().__init__(item_type)
+
+    def process_result_value(
+            self, value: 'list[Any] | None', dialect: Dialect,
+    ) -> 'list[Any] | None':
+        if value is None:
+            return None
+        return [elem for elem in value if elem is not _UNKNOWN_ENUM_ELEM]
+
+
 # --- Pydantic/SQLModel Integration Layer ---
 @final
 class _ArrayTypeHandler:
@@ -41,14 +138,16 @@ class _ArrayTypeHandler:
             self.item_schema = core_schema.literal_schema(
                 [member.value for member in origin_type]  # pyright: ignore[reportAny]
             )
-            # values_callable ensures the PG ENUM is populated with the member
-            # string values (StrEnum.value) rather than the Python identifiers
-            # (Enum.name). Required so StrEnum subclasses serialize as their
-            # user-facing strings (e.g. 'read:own' instead of 'READ_OWN').
-            self.sa_array_type = ARRAY(sa.Enum(
+            # _TolerantEnum carries values_callable so the PG ENUM is populated
+            # with the member string values (StrEnum.value) rather than the
+            # Python identifiers (Enum.name). Required so StrEnum subclasses
+            # serialize as their user-facing strings (e.g. 'read:own' instead of
+            # 'READ_OWN'). The _TolerantEnumArray/_TolerantEnum pair also makes
+            # the read path tolerant of unknown DB enum values (see their
+            # docstrings) instead of raising LookupError during version skew.
+            self.sa_array_type = _TolerantEnumArray(_TolerantEnum(
                 origin_type,
                 name=origin_type.__name__.lower(),
-                values_callable=lambda e: [m.value for m in e],
             ))
             return
 

sqlmodel_ext/mixins/table.py

@@ -384,6 +384,30 @@ class TableBaseMixin(AsyncAttrs):
         current_data: dict[str, Any] | None = None
 
         while True:
+            # Snapshot scalar state BEFORE attempting the flush: a failed
+            # versioned UPDATE rolls back the inner transaction, which expires
+            # every attribute -- inside the except block any attribute read
+            # would emit SQL and raise PendingRollbackError/MissingGreenlet.
+            # Read via identity/__dict__ only: the instance itself may already
+            # be expired by an earlier commit, so plain getattr could emit SQL.
+            _pre_insp = cast(InstanceState[Any], inspect(instance))
+            instance_id = _pre_insp.identity[0] if _pre_insp.identity else instance.__dict__.get('id')
+            instance_version = instance.__dict__.get('version')
+            if optimistic_retry_count > 0 and current_data is None:
+                # Capture only the columns the caller actually modified (via
+                # SQLAlchemy attribute history). Re-applying a full model_dump
+                # on retry would overwrite the other transaction's committed
+                # values with our stale ones -- the exact lost update the
+                # optimistic lock exists to prevent. For a transient instance
+                # every set attribute has history, so this also covers INSERTs.
+                _hist_insp = cast(InstanceState[Any], inspect(instance))
+                current_data = {}
+                for _col_attr in _hist_insp.mapper.column_attrs:
+                    if _col_attr.key in ('id', 'version', 'created_at', 'updated_at'):
+                        continue
+                    if _hist_insp.attrs[_col_attr.key].history.has_changes():
+                        current_data[_col_attr.key] = _hist_insp.attrs[_col_attr.key].value
+
             session.add(instance)
             try:
                 if commit:
@@ -397,22 +421,18 @@ class TableBaseMixin(AsyncAttrs):
                     raise OptimisticLockError(
                         message=f"{cls.__name__} optimistic lock conflict: record modified by another transaction",
                         model_class=cls.__name__,
-                        record_id=str(getattr(instance, 'id', None)),
-                        expected_version=getattr(instance, 'version', None),
+                        record_id=str(instance_id),
+                        expected_version=instance_version,
                         original_error=e,
                     ) from e
 
                 retries_remaining -= 1
-                if current_data is None:
-                    # TableBaseMixin is always used with SQLModelBase; model_dump provided by Pydantic
-                    current_data = cast(SQLModelBase, self).model_dump(exclude={'id', 'version', 'created_at', 'updated_at'})
-
-                fresh = await cls.get(session, cls.id == self.id)
+                fresh = await cls.get(session, cls.id == instance_id)
                 if fresh is None:
                     raise OptimisticLockError(
                         message=f"{cls.__name__} retry failed: record has been deleted",
                         model_class=cls.__name__,
-                        record_id=str(getattr(self, 'id', None)),
+                        record_id=str(instance_id),
                         original_error=e,
                     ) from e
 
@@ -472,6 +492,16 @@ class TableBaseMixin(AsyncAttrs):
         retries_remaining = optimistic_retry_count
 
         while True:
+            # Snapshot scalar state BEFORE attempting the flush: a failed
+            # versioned UPDATE rolls back the inner transaction, which expires
+            # every attribute -- inside the except block any attribute read
+            # would emit SQL and raise PendingRollbackError/MissingGreenlet.
+            # Read via identity/__dict__ only: the instance itself may already
+            # be expired by an earlier commit, so plain getattr could emit SQL.
+            _pre_insp = cast(InstanceState[Any], inspect(instance))
+            instance_id = _pre_insp.identity[0] if _pre_insp.identity else instance.__dict__.get('id')
+            instance_version = instance.__dict__.get('version')
+
             # TableBaseMixin is always used with SQLModelBase; sqlmodel_update provided by SQLModel
             _ = cast(SQLModelBase, instance).sqlmodel_update(update_data, update=extra_data)
             session.add(instance)
@@ -488,18 +518,18 @@ class TableBaseMixin(AsyncAttrs):
                     raise OptimisticLockError(
                         message=f"{cls.__name__} optimistic lock conflict: record modified by another transaction",
                         model_class=cls.__name__,
-                        record_id=str(getattr(instance, 'id', None)),
-                        expected_version=getattr(instance, 'version', None),
+                        record_id=str(instance_id),
+                        expected_version=instance_version,
                         original_error=e,
                     ) from e
 
                 retries_remaining -= 1
-                fresh = await cls.get(session, cls.id == self.id)
+                fresh = await cls.get(session, cls.id == instance_id)
                 if fresh is None:
                     raise OptimisticLockError(
                         message=f"{cls.__name__} retry failed: record has been deleted",
                         model_class=cls.__name__,
-                        record_id=str(getattr(self, 'id', None)),
+                        record_id=str(instance_id),
                         original_error=e,
                     ) from e
                 instance = fresh
@@ -575,6 +605,21 @@ class TableBaseMixin(AsyncAttrs):
         if condition is not None:
             # cast to ColumnElement[bool]: at runtime condition is always a column expression
             stmt = sql_delete(cls).where(cast(ColumnElement[bool], condition))
+            # STI auto-filter: a Core DELETE built from an STI subclass targets the
+            # shared table with no discriminator criteria, so without this filter a
+            # subclass-level conditional delete would also remove sibling-subclass
+            # rows. Mirrors the WHERE discriminator IN (...) logic used by get()/count().
+            if issubclass(cls, PolymorphicBaseMixin) and not cls._is_joined_table_inheritance():
+                mapper = cast(Mapper[Any], inspect(cls))
+                poly_on = mapper.polymorphic_on
+                if poly_on is not None:
+                    descendant_identities = [
+                        m.polymorphic_identity
+                        for m in mapper.self_and_descendants
+                        if m.polymorphic_identity is not None
+                    ]
+                    if descendant_identities:
+                        stmt = stmt.where(poly_on.in_(descendant_identities))
             result = cast(CursorResult[Any], await session.execute(stmt))
             deleted_count = result.rowcount
         else:
@@ -950,7 +995,7 @@ class TableBaseMixin(AsyncAttrs):
         chains: list[list[QueryableAttribute[Any]]] = []
         used: set[QueryableAttribute[Any]] = set()
 
-        for root in roots:
+        def _walk_chain(root: QueryableAttribute[Any]) -> None:
             chain = [root]
             used.add(root)
             current = root
@@ -968,6 +1013,18 @@ class TableBaseMixin(AsyncAttrs):
                 current = next_rel
             chains.append(chain)
 
+        for root in roots:
+            _walk_chain(root)
+
+        # Cycle guard: a bidirectional pair (A.b + B.a) makes every
+        # relationship someone's successor, so it never appears under any
+        # root and the requested loads would be silently dropped. Break each
+        # remaining cycle at its first-listed member -- list order expresses
+        # the caller's intended chain direction.
+        for r in load_list:
+            if r not in used:
+                _walk_chain(r)
+
         return chains
 
     @classmethod

{sqlmodel_ext-0.4.0.dist-info → sqlmodel_ext-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.4.0
+Version: 0.4.1
 Summary: Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types.
 Project-URL: Homepage, https://github.com/Foxerine/sqlmodel-ext
 Project-URL: Repository, https://github.com/Foxerine/sqlmodel-ext
@@ -24,7 +24,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: pydantic>=2.0
 Requires-Dist: sqlalchemy>=2.0
-Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: sqlmodel>=0.0.32
 Provides-Extra: cache
 Requires-Dist: orjson>=3.0; extra == 'cache'
 Requires-Dist: redis>=5.0; extra == 'cache'
@@ -70,7 +70,7 @@ Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphi
 | **RelationPreloadMixin** | Decorator-based automatic relationship preloading (prevents `MissingGreenlet` errors) |
 | **ListResponse[T]** | Generic paginated response model for list endpoints |
 | **Field Types** | Reusable constrained types: `Str64`, `Port`, `IPAddress`, `HttpUrl`, `SafeHttpUrl`, and more |
-| **PostgreSQL Types** | `Array[T]` for native ARRAY, `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
+| **PostgreSQL Types** | `Array[T]` for native ARRAY (read-tolerant for enum arrays during rolling-deploy version skew), `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
 | **Info Response DTOs** | Pre-built mixins for API response models with id/timestamp fields |
 
 ## Installation
@@ -108,12 +108,13 @@ pip install sqlmodel-ext[pgvector]
 ### Define Models
 
 ```python
-from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, Str64
+from pydantic import EmailStr  # requires: pip install 'pydantic[email]'
+from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, NonEmptyStrippedStr64
 
 # Base class -- fields only, no database table
 class UserBase(SQLModelBase):
-    name: Str64
-    email: str
+    name: NonEmptyStrippedStr64   # user-visible name: rejects "" and whitespace-only
+    email: EmailStr
 
 # Table class -- inherits fields + gains async CRUD + UUID primary key
 class User(UserBase, UUIDTableBaseMixin, table=True):
@@ -438,17 +439,19 @@ async def delete_article(session: SessionDep, article_id: UUID) -> None:
 
 ```python
 from abc import ABC, abstractmethod
+from pydantic import EmailStr
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin,
     AutoPolymorphicIdentityMixin, create_subclass_id_mixin,
     ListResponse, TableViewRequest,
+    Str512, Text1K,
 )
 
 # ── Polymorphic models ────────────────────────────────────────────
 
 class NotificationBase(SQLModelBase):
     user_id: UUID = Field(foreign_key='user.id')
-    message: str
+    message: Text1K
 
 class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
     @abstractmethod
@@ -457,13 +460,13 @@ class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, A
 NotifSubclassId = create_subclass_id_mixin('notification')
 
 class EmailNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    email_to: str
+    email_to: EmailStr
 
     def summary(self) -> str:
         return f"Email to {self.email_to}: {self.message}"
 
 class PushNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    device_token: str
+    device_token: Str512
 
     def summary(self) -> str:
         return f"Push to {self.device_token}: {self.message}"
@@ -493,15 +496,15 @@ These mixins provide the async CRUD interface. `TableBaseMixin` uses an auto-inc
 Both mixins automatically add `id`, `created_at`, and `updated_at` fields.
 
 ```python
-from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin
+from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin, NonEmptyStrippedStr64, Text1K
 
 # Integer primary key
 class LogEntry(SQLModelBase, TableBaseMixin, table=True):
-    message: str
+    message: Text1K
 
 # UUID primary key (recommended for most use cases)
 class Project(SQLModelBase, UUIDTableBaseMixin, table=True):
-    name: str
+    name: NonEmptyStrippedStr64
 ```
 
 #### `add()` -- Batch Insert
@@ -529,7 +532,9 @@ user = await User.add(session, User(name="Alice", email="a@x.com"))
 user = await user.save(session)
 
 # Save with relationship preloading
-user = await user.save(session, load=User.profile)
+# (rel() casts the Relationship field for type checkers, which would
+#  otherwise infer User.profile as Profile instead of a loadable attribute)
+user = await user.save(session, load=rel(User.profile))
 
 # Save with optimistic lock retry
 user = await user.save(session, optimistic_retry_count=3)
@@ -562,9 +567,10 @@ user3 = await user3.save(session)        # commits all three
 #### `update()` -- Partial Update from a Model
 
 ```python
-class UserUpdate(SQLModelBase):
-    name: str | None = None
-    email: str | None = None
+# all_fields_optional auto-converts every inherited field to ``T | None = None``
+# while preserving constraints -- no hand-written Optional boilerplate
+class UserUpdate(UserBase, all_fields_optional=True):
+    pass
 
 # Only updates fields that were explicitly set
 user = await user.update(session, UserUpdate(name="Charlie"))
@@ -643,7 +649,7 @@ users = await User.get(session, fetch_mode="all")
 user = await User.get(
     session,
     User.id == user_id,
-    load=[User.profile, User.orders],
+    load=[rel(User.profile), rel(User.orders)],
 )
 
 # With JOIN
@@ -767,11 +773,12 @@ from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     create_subclass_id_mixin,
+    HttpUrl, NonEmptyStrippedStr64, NonNegativeInt,
 )
 
 # 1. Base class (fields only, no table)
 class ToolBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
 
 # 2. Abstract parent (creates the parent table)
 class Tool(ToolBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
@@ -783,13 +790,13 @@ ToolSubclassIdMixin = create_subclass_id_mixin('tool')
 
 # 4. Concrete subclasses (each gets its own table)
 class WebSearchTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    search_url: str
+    search_url: HttpUrl
 
     async def execute(self) -> str:
         return f"Searching {self.search_url}"
 
 class CalculatorTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    precision: int = 2
+    precision: NonNegativeInt = 2
 
     async def execute(self) -> str:
         return "Calculating..."
@@ -823,16 +830,17 @@ from sqlmodel_ext import (
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     register_sti_columns_for_all_subclasses,
     register_sti_column_properties_for_all_subclasses,
+    NonNegativeBigInt, Str256,
 )
 
 class UserFile(SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin, table=True):
-    filename: str
+    filename: Str256
 
 class PendingFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
     upload_deadline: datetime | None = None  # Added to userfile table as nullable
 
 class CompletedFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
-    file_size: int | None = None  # Added to userfile table as nullable
+    file_size: NonNegativeBigInt | None = None  # Added to userfile table as nullable
 
 # After all models are defined, before configure_mappers():
 register_sti_columns_for_all_subclasses()
@@ -858,7 +866,7 @@ class ToolSet(SQLModelBase, UUIDTableBaseMixin, table=True):
 tool_set = await ToolSet.get(
     session,
     ToolSet.id == ts_id,
-    load=ToolSet.tools,
+    load=rel(ToolSet.tools),
     jti_subclasses='all',  # Loads all subclass-specific columns
 )
 ```
@@ -885,15 +893,22 @@ Tool._is_joined_table_inheritance()  # True for JTI, False for STI
 Prevents lost updates in concurrent environments using SQLAlchemy's `version_id_col` mechanism.
 
 ```python
+from enum import StrEnum
+
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     OptimisticLockMixin, OptimisticLockError,
+    NonNegativeDecimal38_18,
 )
 
+class OrderStatusEnum(StrEnum):
+    pending = 'pending'
+    paid = 'paid'
+
 # OptimisticLockMixin MUST come before TableBaseMixin in MRO
 class Order(OptimisticLockMixin, UUIDTableBaseMixin, table=True):
-    status: str
-    amount: int
+    status: OrderStatusEnum = OrderStatusEnum.pending
+    amount: NonNegativeDecimal38_18
 ```
 
 The mixin adds a `version` integer field (starting at 0). Every `UPDATE` generates SQL like:
@@ -945,11 +960,11 @@ The `RelationPreloadMixin` and `@requires_relations` decorator automatically loa
 
 ```python
 from sqlmodel import Relationship
-from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase
+from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase, NonNegativeDecimal38_18
 from sqlmodel_ext.mixins import RelationPreloadMixin, requires_relations
 
 class GeneratorConfig(SQLModelBase, UUIDTableBaseMixin, table=True):
-    price: int
+    price: NonNegativeDecimal38_18
 
 class Generator(SQLModelBase, UUIDTableBaseMixin, table=True):
     config: GeneratorConfig = Relationship()
@@ -1391,12 +1406,12 @@ When using Pydantic's `use_attribute_docstrings=True` (enabled by default in `SQ
 
 ```python
 class UserBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
     """User display name"""     # ← parsed by Pydantic
 
 class UserUpdateRequest(UserBase, all_fields_optional=True):
     pass
-    # name: str | None = None   — description "User display name" is automatically inherited
+    # name: NonEmptyStrippedStr64 | None = None — description "User display name" is inherited
     # Shows up correctly in OpenAPI/Swagger docs
 ```
 

{sqlmodel_ext-0.4.0.dist-info → sqlmodel_ext-0.4.1.dist-info}/RECORD

@@ -1,13 +1,13 @@
-sqlmodel_ext/__init__.py,sha256=e5IwbXgYXGE_lV1Fx9oCXnNKWgdZAgHRtFLCzH1xOos,3755
+sqlmodel_ext/__init__.py,sha256=xG-l39gVbrxx3WH7tH1MTKrQKBnpQ10_bd5QOB0NTFI,3755
 sqlmodel_ext/_compat.py,sha256=zia-2vSQqmzk6_4Y404IKzcip5n4fe7PrRAYntlY-Zg,12186
 sqlmodel_ext/_exceptions.py,sha256=2mC_BVvcreaFutR4UxIra238o1sr4zWv8vctBI6CL2o,413
 sqlmodel_ext/_sa_type.py,sha256=zDwXBR0O7dne3Y6j8V8CaMtfqZqcpvsPucZUxGh8dAk,4866
 sqlmodel_ext/_utils.py,sha256=cFrlQp1Uq-4ZAdvi_u79UbEI0IHZaAm5VkXadCXrBmI,174
-sqlmodel_ext/base.py,sha256=M1vkigsfoIx4M2iiWBPZ_X5WpA6XSYM-gWhJVyyunlA,65797
+sqlmodel_ext/base.py,sha256=0m6XkHsZBqLr9d2kpCMStZSDpHxua-UiBtRiL8R4dDk,72263
 sqlmodel_ext/pagination.py,sha256=1JOzt51KvIZTyjgYsQTP0v7KDytIkQKlYN4vGkq9RH8,4611
 sqlmodel_ext/relation_load_checker.py,sha256=1W2vSdk_PVTqBRRcSyIffw-ECysJRfg1bJYVTmx9Wxs,172457
 sqlmodel_ext/session.py,sha256=LNt9zZn5KUH8BA9evulKrh7233VYDtj9mn4j_uPkHjw,5570
-sqlmodel_ext/field_types/__init__.py,sha256=vOka_SrEi9q_iY0UeQC5fQmwP1m2f3k3r3q82kbEOu8,22020
+sqlmodel_ext/field_types/__init__.py,sha256=O7XYyX0lnu-Q6xaFMJlXKsuV5AO2tE7gU5v76BY-5nI,24002
 sqlmodel_ext/field_types/_ssrf.py,sha256=QdrtwWMFN6xZkllyHGwvJ0nwL3rSBn2FkEoxv3L8kvs,2627
 sqlmodel_ext/field_types/ip_address.py,sha256=OeyOAVgDV7aGk56z0LUqgYCinthYYusmZSCR1BLkET4,1589
 sqlmodel_ext/field_types/url.py,sha256=1iAdu3A9uyMR3XJMs0b3NJ2_VeBAEAfja-_xbdjph5I,5209
@@ -15,7 +15,7 @@ sqlmodel_ext/field_types/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQe
 sqlmodel_ext/field_types/_internal/path.py,sha256=bJhrGnidXbEFQyJBoMIKHo2p-a2T805BV4mMSZ8vmDE,2070
 sqlmodel_ext/field_types/dialects/__init__.py,sha256=ENJXbWbIZaU8eXNxAG2rjH_w7oQpb1f790ugCZsm1ro,267
 sqlmodel_ext/field_types/dialects/postgresql/__init__.py,sha256=3hvtu9Z0E4BfZ4VwYWbmDYDV_-NKoQJYA8mUWynCLCU,1291
-sqlmodel_ext/field_types/dialects/postgresql/array.py,sha256=NczdAXv3sdAN6nzs5y8wZzv-Ce4RXSx5De0LE70ByHM,4693
+sqlmodel_ext/field_types/dialects/postgresql/array.py,sha256=bj1wMjVE1Hsj_rxfFXa57U3FV_3a8vq1y-0-bmqdGRE,8913
 sqlmodel_ext/field_types/dialects/postgresql/exceptions.py,sha256=cLFO3bogpP-naidw31JRjh6lJu2eEfahKdz-EQebfMU,771
 sqlmodel_ext/field_types/dialects/postgresql/jsonb_types.py,sha256=Hunep_DyNVNt9v4JVPOn_AW2a8DAkvtcQsrq2_ahdDo,6107
 sqlmodel_ext/field_types/dialects/postgresql/numpy_vector.py,sha256=q9eOCcFyaw4djvmafd1ah_9epRfxE8X9iLRvkphOcyU,14992
@@ -27,8 +27,8 @@ sqlmodel_ext/mixins/info_response.py,sha256=Z8akOpN9wlhiq5_MbzEjwGpGDQ99jYvGQt9s
 sqlmodel_ext/mixins/optimistic_lock.py,sha256=XVjO6NgKYfpcsGlH1Yj8Ou9NkpCsqVN9AZyWxDBTb_k,2925
 sqlmodel_ext/mixins/polymorphic.py,sha256=tGg_V98hQu2L0WcI8oOr7hzO9MZ7QfqNVFaACuaD1Dc,33211
 sqlmodel_ext/mixins/relation_preload.py,sha256=SD9Nnc8zIbUqWqI85gr4XRpbPsmJwXQd7JPHj_EVrLs,15967
-sqlmodel_ext/mixins/table.py,sha256=QQ6_4ibzZfD9mdenh0uHpLEJLH-YO2RUflt1VlFrnRA,57251
-sqlmodel_ext-0.4.0.dist-info/METADATA,sha256=zWnO5eOAbw80LqqU-Gq_kWpu3kcJuLX-kbDlqXU1rY4,52081
-sqlmodel_ext-0.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-sqlmodel_ext-0.4.0.dist-info/licenses/LICENSE,sha256=8ek0ENxpcXcIhCC7MXetxiYLKflHqz2JbA-nwDqTsyI,1088
-sqlmodel_ext-0.4.0.dist-info/RECORD,,
+sqlmodel_ext/mixins/table.py,sha256=JbEhCkbhbYC0TyCSSfSz_3FFtcbvg2nNmh7F-Rtzg-E,60817
+sqlmodel_ext-0.4.1.dist-info/METADATA,sha256=XI34AHmMUOEQG8ib-MYblozJrvyqNHRJRD4bhvYSu0I,53102
+sqlmodel_ext-0.4.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+sqlmodel_ext-0.4.1.dist-info/licenses/LICENSE,sha256=8ek0ENxpcXcIhCC7MXetxiYLKflHqz2JbA-nwDqTsyI,1088
+sqlmodel_ext-0.4.1.dist-info/RECORD,,