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

sqlmodel_ext/__init__.py

@@ -20,10 +20,13 @@ Quick start::
     user = await user.save(session)
     users = await User.get(session, fetch_mode="all")
 """
-__version__ = "0.3.5"
+__version__ = "0.4.1"
 
 # Base
-from sqlmodel_ext.base import SQLModelBase, ExtraIgnoreModelBase
+from sqlmodel_ext.base import SQLModelBase, ExtraIgnoreModelBase, CustomTableArg
+
+# Enhanced session (cache-aware commit/reset/refresh/execute)
+from sqlmodel_ext.session import AsyncSession
 
 # Exceptions
 from sqlmodel_ext._exceptions import RecordNotFoundError
@@ -44,10 +47,10 @@ from sqlmodel_ext.mixins import (
     UUIDTableBaseMixin,
     rel,
     cond,
-    safe_reset,
     # Polymorphic
     PolymorphicBaseMixin,
     AutoPolymorphicIdentityMixin,
+    DeferredIndex,
     create_subclass_id_mixin,
     register_sti_columns_for_all_subclasses,
     register_sti_column_properties_for_all_subclasses,
@@ -93,14 +96,24 @@ from sqlmodel_ext.field_types import (
     Text2500,
     Text3K,
     Text5K,
+    Text8K,
     Text10K,
     Text16K,
     Text32K,
+    Text48K,
     Text60K,
     Text64K,
     Text100K,
     Text128K,
     Text1M,
+    NonEmptyStr64,
+    NonEmptyStr128,
+    NonEmptyStr256,
+    NonEmptyStrippedStr64,
+    NonEmptyStrippedStr128,
+    NonEmptyStrippedStr256,
+    Sha256Hex,
+    BCP47LanguageCode,
     # Numeric constraints
     INT32_MAX,
     INT64_MAX,
@@ -113,6 +126,32 @@ from sqlmodel_ext.field_types import (
     NonNegativeBigInt,
     PositiveFloat,
     NonNegativeFloat,
+    # Decimal constraints (NUMERIC(p, s) + sign + JSON-string serialization)
+    SignedDecimal38_18,
+    NonNegativeDecimal38_18,
+    PositiveDecimal38_18,
+    OptionalNonNegativeDecimal38_18,
+    SignedDecimal20_10,
+    NonNegativeDecimal20_10,
+    OptionalNonNegativeDecimal20_10,
+    # Bounded-length list aliases
+    List,
+    List1,
+    List2,
+    List3,
+    List7,
+    List10,
+    List16,
+    List20,
+    List32,
+    List40,
+    List50,
+    List64,
+    List100,
+    List128,
+    List200,
+    List256,
+    List1024,
     # Custom types
     IPAddress,
     Url,

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
@@ -17,11 +18,12 @@ import types
 import typing
 from typing import Any, Self, Sequence, get_args, get_origin
 
+import annotated_types as at
 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,
@@ -32,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.
@@ -192,27 +202,133 @@ def _durably_set_sa_type(field_info: Any, sa_type: Any) -> None:
             pass
 
 
+_FIELDINFO_NON_CONSTRAINT_ATTRS = (
+    'default', 'default_factory', 'alias', 'serialization_alias', 'validation_alias',
+    'title', 'description', 'examples', 'json_schema_extra',
+    'exclude', 'repr', 'init', 'init_var', 'kw_only', 'discriminator',
+    'frozen', 'validate_default',
+    'primary_key', 'foreign_key', 'unique', 'nullable', 'index',
+    'sa_type', 'sa_column', 'sa_column_args', 'sa_column_kwargs',
+    'ondelete', 'schema_extra',
+)
+"""Non-constraint attributes on FieldInfo -- sa/orm/default/alias/docs, safe to keep in the outer Annotated.
+
+See the ``_split_metadata_for_optional`` docstring for semantics.
+Constraint-related attributes (ge/le/gt/lt/multiple_of/max_digits/decimal_places/
+min_length/max_length/pattern/strict) have already been expanded by Pydantic into
+``Ge/Le/Gt/Lt/MultipleOf/_PydanticGeneralMetadata/MinLen/MaxLen/Predicate`` markers
+inside ``FieldInfo.metadata``, so they need no re-detection on the FieldInfo attrs."""
+
+
+def _split_metadata_for_optional(
+        metadata: tuple[typing.Any, ...],
+) -> tuple[list[typing.Any], list[typing.Any]]:
+    """Split the metadata of ``Annotated[T, *metadata]`` into (inner_constraints, outer_safe).
+
+    **Why**: Pydantic constraint markers (``Ge/Le/MultipleOf/_PydanticGeneralMetadata``
+    etc.) raise ``TypeError: Unable to apply constraint ... to supplied value None`` on
+    None -- so the constraint markers of a ``T | None`` field must be wrapped inside the
+    inner ``Annotated[T, ...]`` so Pydantic only applies them when the value is not
+    None. Schema markers (``PlainSerializer/BeforeValidator`` etc.) and ORM markers
+    (``sa_type``/``default`` etc.) are None-safe and may stay in the outer layer. This
+    is the essence behind the hand-written nested-Annotated form of optional
+    constrained aliases like ``OptionalNonNegativeDecimal38_18``.
+
+    Classification rules:
+
+    - ``annotated_types.BaseMetadata`` subclasses (``Ge/Le/Gt/Lt/MultipleOf/MinLen/
+      MaxLen/Predicate`` etc.) -> inner (all constraint validators, crash on None)
+    - Pydantic ``FieldInfo`` -> split: ``fi.metadata`` (the constraint marker sequence
+      Pydantic already expanded) -> inner; the remaining schema/orm attrs are rebuilt
+      into a fresh FieldInfo -> outer
+    - objects with ``max_digits`` / ``decimal_places`` / ``pattern`` attributes that are
+      not FieldInfo (i.e. ``_PydanticGeneralMetadata``) -> inner
+    - everything else (``PlainSerializer/WrapSerializer/BeforeValidator/AfterValidator/
+      PlainValidator/WrapValidator`` etc.) -> outer (validators are expected to be
+      None-safe, like a reject-float BeforeValidator)
+    """
+    inner: list[typing.Any] = []
+    outer: list[typing.Any] = []
+    for m in metadata:
+        if isinstance(m, at.BaseMetadata):
+            inner.append(m)
+        elif isinstance(m, FieldInfo):
+            inner.extend(m.metadata)
+            outer_fi = _strip_constraint_metadata_from_field_info(m)
+            if outer_fi is not None:
+                outer.append(outer_fi)
+        elif isinstance(m, at.GroupedMetadata):
+            # GroupedMetadata protocol (``pydantic.StringConstraints`` etc.):
+            # iterating yields a sequence of _PydanticGeneralMetadata /
+            # annotated_types markers; all go inner.
+            inner.extend(list(m))
+        elif hasattr(m, 'max_digits') or hasattr(m, 'decimal_places') or hasattr(m, 'pattern'):
+            # _PydanticGeneralMetadata (private, duck-typed): max_digits/decimal_places/pattern
+            inner.append(m)
+        else:
+            outer.append(m)
+    return inner, outer
+
+
+def _strip_constraint_metadata_from_field_info(fi: FieldInfo) -> FieldInfo | None:
+    """Copy an outer-layer version of a FieldInfo: drop ``fi.metadata`` (constraint markers,
+    moved inner), keep sa_type/default/alias/description and other schema/orm attrs.
+    Returns None when no non-constraint attrs remain."""
+    new_kwargs: dict[str, typing.Any] = {}
+    for attr in _FIELDINFO_NON_CONSTRAINT_ATTRS:
+        v = getattr(fi, attr, Undefined)
+        if v is None or v is Undefined:
+            continue
+        new_kwargs[attr] = v
+    if not new_kwargs:
+        return None
+    return Field(**new_kwargs)
+
+
 def _make_annotation_optional(annotation: typing.Any) -> typing.Any:
     """
     Convert type annotation to optional: ``T → T | None``
 
     Places ``| None`` inside ``Annotated[]`` to preserve Field metadata.
 
+    **Key constraint** (isomorphic to ``OptionalNonNegativeDecimal38_18``): when ``T``
+    carries constraint validators (``Ge/Le/MultipleOf/MaxDigits/DecimalPlaces`` etc.),
+    the constraints **must** be nested into the inner ``Annotated[T, *constraints]``,
+    otherwise Pydantic crashes parsing JSON ``null`` with
+    ``TypeError: Unable to apply constraint 'ge' to supplied value None``.
+    Schema/serializer/ORM markers (``PlainSerializer/sa_type/default`` etc.) are
+    None-safe and stay outer.
+
     Examples::
 
         str → str | None
-        Annotated[float, Field(ge=0.0)] → Annotated[float | None, Field(ge=0.0)]
+        Annotated[float, Ge(0)] → Annotated[Annotated[float, Ge(0)] | None]
+        Annotated[Decimal, Field(ge=0, sa_type=...), PlainSerializer(...)]
+            → Annotated[Annotated[Decimal, Ge(0)] | None, Field(sa_type=...), PlainSerializer(...)]
         str | None → str | None  (already optional, unchanged)
     """
     origin = get_origin(annotation)
 
-    # Annotated[T, metadata...] → Annotated[T | None, metadata...]
+    # Annotated[T, metadata...]: split constraint/schema metadata, then build
+    # the nested optional annotation.
     if origin is typing.Annotated:
         args = get_args(annotation)
         inner_type = args[0]
         metadata = args[1:]
-        optional_inner = _make_annotation_optional(inner_type)
-        return typing.Annotated[tuple([optional_inner, *metadata])]
+        inner_meta, outer_meta = _split_metadata_for_optional(metadata)
+        # Recurse into inner_type: it may itself be Annotated (nested aliases).
+        recursed_inner_type = _maybe_recurse_into_annotated(inner_type)
+        if inner_meta:
+            inner_annotated = typing.Annotated[tuple([recursed_inner_type, *inner_meta])]
+        else:
+            inner_annotated = recursed_inner_type
+        # ``typing.Union[X, None]`` is equivalent to PEP 604 ``X | None``, but type
+        # checkers can correctly infer ``inner_annotated`` is ``Annotated[...]``
+        # (a dynamic type without static ``__or__`` support).
+        optional_inner = typing.Union[inner_annotated, type(None)]  # pyright: ignore[reportGeneralTypeIssues]
+        if outer_meta:
+            return typing.Annotated[tuple([optional_inner, *outer_meta])]
+        return optional_inner
 
     # Union / UnionType already contains None → unchanged
     if origin is typing.Union or isinstance(annotation, types.UnionType):
@@ -224,6 +340,25 @@ def _make_annotation_optional(annotation: typing.Any) -> typing.Any:
     return annotation | None
 
 
+def _maybe_recurse_into_annotated(annotation: typing.Any) -> typing.Any:
+    """For nested Annotated (``Annotated[Annotated[T, ...], ...]``), split the inner
+    layer's constraints too. Non-Annotated values are returned unchanged."""
+    if get_origin(annotation) is typing.Annotated:
+        args = get_args(annotation)
+        inner_type = args[0]
+        metadata = args[1:]
+        inner_meta, outer_meta = _split_metadata_for_optional(metadata)
+        # This layer is already at the outer position or wrapped as inner --
+        # keep its structure: the constraints are in inner_meta, reassemble
+        # into Annotated without appending | None (the parent caller does that).
+        recursed = _maybe_recurse_into_annotated(inner_type)
+        all_meta = list(inner_meta) + list(outer_meta)
+        if all_meta:
+            return typing.Annotated[tuple([recursed, *all_meta])]
+        return recursed
+    return annotation
+
+
 def _apply_all_fields_optional(
         annotations: dict[str, typing.Any],
         attrs: dict[str, typing.Any],
@@ -467,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,
@@ -520,6 +748,52 @@ def _make_sti_fk_resolver(
     return _resolve
 
 
+# ==================== Custom table_args element interception ====================
+#
+# SQLAlchemy's ``Table.__init__`` consumes every ``__table_args__`` element
+# **immediately**; an ``Index`` referencing a column that does not exist yet
+# raises ``ConstraintColumnNotFoundError`` on the spot.
+#
+# ``CustomTableArg`` is a generic base class that lets users place
+# **non-SQLAlchemy-native** marker objects into ``table_args`` -- the
+# metaclass (``__DeclarativeMeta.__new__``) **intercepts** these markers,
+# removes them from ``table_args`` (never handing them to SQLAlchemy), and
+# pushes (target class, markers) onto the module-level queue
+# ``_classes_with_custom_table_args`` for downstream infrastructure (e.g. the
+# STI deferred index in ``mixins.polymorphic``) to scan and consume at the
+# right moment.
+#
+# The base layer only knows the generic "defer processing" mechanism and
+# **not** the concrete semantics (STI, JTI, ...) -- concrete types (e.g.
+# ``DeferredIndex``) are defined by their own submodules as ``CustomTableArg``
+# subclasses.
+
+
+class CustomTableArg:
+    """
+    Generic base class for non-SQLAlchemy-native ``table_args`` elements.
+
+    Objects inheriting this class, when placed in ``table_args``, are
+    **intercepted** by the SQLModel metaclass -- never passed to SQLAlchemy
+    ``Table.__init__`` (avoiding immediate-evaluation failures) and instead
+    stashed on the ``_classes_with_custom_table_args`` queue for downstream
+    infrastructure to consume.
+
+    Concrete subclass example: ``mixins.polymorphic.DeferredIndex``
+    (deferred indexes over STI subclass columns).
+    """
+
+
+_classes_with_custom_table_args: list[tuple[type, list[CustomTableArg]]] = []
+"""
+Queue of classes carrying custom ``table_args`` elements: ``(class, [CustomTableArg, ...])``.
+
+Appended by ``__DeclarativeMeta.__new__`` after class creation completes.
+Downstream infrastructure (e.g. ``mixins.polymorphic._create_sti_deferred_indexes()``)
+scans this queue and consumes entries as needed (dispatching on ``isinstance``).
+"""
+
+
 class __DeclarativeMeta(SQLModelMetaclass):
     """
     A smart hybrid metaclass providing flexibility and clarity:
@@ -593,9 +867,49 @@ 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:
-            attrs['__table_args__'] = kwargs.pop('table_args')
+            raw_table_args = kwargs.pop('table_args')
+            # Split out CustomTableArg markers -- never handed to SQLAlchemy
+            # (avoiding immediate evaluation against not-yet-existing
+            # columns); stashed on the module-level
+            # ``_classes_with_custom_table_args`` queue for downstream
+            # infrastructure (e.g. STI deferred indexes) to consume.
+            real_table_args: list[Any] = []
+            custom_table_args: list[CustomTableArg] = []
+            for arg in raw_table_args:
+                if isinstance(arg, CustomTableArg):
+                    custom_table_args.append(arg)
+                else:
+                    real_table_args.append(arg)
+            attrs['__table_args__'] = tuple(real_table_args) if real_table_args else ()
+            if custom_table_args:
+                # Temporarily hung on attrs; appended to the module-level
+                # queue after super().__new__ (the result class is fully
+                # constructed then, so downstream can read __table__ etc.).
+                attrs['__custom_table_args__'] = custom_table_args
         if 'table_name' in kwargs:
             attrs['__tablename__'] = kwargs.pop('table_name')
         if 'abstract' in kwargs:
@@ -675,6 +989,13 @@ class __DeclarativeMeta(SQLModelMetaclass):
         # 6. Call parent __new__
         result = super().__new__(cls, name, bases, attrs, **kwargs)
 
+        # 6.5. Append intercepted CustomTableArg markers to the module-level
+        # queue for downstream infrastructure. The result class is fully
+        # constructed at this point, so consumers can access __table__ etc.
+        _custom_args = attrs.get('__custom_table_args__')
+        if _custom_args:
+            _classes_with_custom_table_args.append((result, _custom_args))
+
         # 7. Restore SQLModel FieldInfo attributes discarded by Pydantic and rebuild Columns.
         # Pydantic FieldInfo uses __slots__, so setattr for SQLModel extensions is silently
         # ignored. We replace the Pydantic FieldInfo with our saved SQLModelFieldInfo and
@@ -975,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] = {}
@@ -1070,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] = {}