sqlmodel-ext 0.3.0__py3-none-any.whl → 0.3.3__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.2.1"
+__version__ = "0.3.3"
 
 # Base
 from sqlmodel_ext.base import SQLModelBase, ExtraIgnoreModelBase

sqlmodel_ext/_compat.py

@@ -14,6 +14,7 @@ if sys.version_info >= (3, 14):
     from enum import StrEnum
     from typing import Literal, Union, get_args, get_origin
 
+    from pydantic_core import PydanticUndefined
     from sqlalchemy import String
     from sqlalchemy.orm.attributes import InstrumentedAttribute
 
@@ -27,6 +28,24 @@ if sys.version_info >= (3, 14):
     import sqlmodel.main
     _original_get_sqlalchemy_type = sqlmodel.main.get_sqlalchemy_type
 
+    def _get_explicit_sa_type(field):
+        """
+        Extract an explicit ``sa_type`` from a SQLModel/Pydantic FieldInfo.
+
+        Matches upstream ``sqlmodel.main._get_sqlmodel_field_value`` semantics:
+        prefers ``FieldInfoMetadata.sa_type`` then falls back to the direct
+        ``field.sa_type`` attribute. Returns ``PydanticUndefined`` when unset.
+        """
+        # Prefer FieldInfoMetadata.sa_type (set via Field(sa_type=...))
+        metadata = getattr(field, 'metadata', None)
+        if metadata:
+            for item in metadata:
+                sa_type = getattr(item, 'sa_type', PydanticUndefined)
+                if sa_type is not PydanticUndefined:
+                    return sa_type
+        # Fallback to direct attribute
+        return getattr(field, 'sa_type', PydanticUndefined)
+
     def _patched_get_sqlalchemy_type(field):
         """
         Fix SQLModel's get_sqlalchemy_type for Python 3.14 type issues.
@@ -34,13 +53,29 @@ if sys.version_info >= (3, 14):
         Handles ForwardRef, ClassVar, Literal, Mapped, and custom types
         that cause issubclass errors under PEP 649.
         """
+        # Respect explicit sa_type from Field(sa_type=...) — must take
+        # precedence over annotation-based auto-detection, matching upstream
+        # SQLModel behavior (sqlmodel/main.py::get_sqlalchemy_type checks
+        # sa_type before everything else). Without this, fields like
+        # ``options: list[str] | None = Field(sa_type=JSON)`` incorrectly
+        # get JSONB from the Union[list, None] -> JSONB branch below,
+        # breaking non-PostgreSQL dialects (e.g., SQLite in tests).
+        explicit_sa_type = _get_explicit_sa_type(field)
+        if explicit_sa_type is not PydanticUndefined:
+            return explicit_sa_type
+
         # Check field.metadata (Pydantic-processed Annotated types)
         metadata = getattr(field, 'metadata', None)
         if metadata:
+            # Pass field.annotation as source_type so handlers that need the element type
+            # (e.g. _PendingArrayHandler extracting T from list[T] to compute ARRAY(T))
+            # can resolve. handler=None is fine because the sa_type extraction path only
+            # reads metadata['sa_type'] and never invokes the schema itself.
+            field_annotation = getattr(field, 'annotation', None)
             for metadata_item in metadata:
                 if hasattr(metadata_item, '__get_pydantic_core_schema__'):
                     try:
-                        schema = metadata_item.__get_pydantic_core_schema__(None, None)
+                        schema = metadata_item.__get_pydantic_core_schema__(field_annotation, None)
                         if isinstance(schema, dict) and 'metadata' in schema:
                             sa_type = schema['metadata'].get('sa_type')
                             if sa_type is not None:
@@ -75,7 +110,9 @@ if sys.version_info >= (3, 14):
                         for md in inner_args[1:]:
                             if hasattr(md, '__get_pydantic_core_schema__'):
                                 try:
-                                    schema = md.__get_pydantic_core_schema__(None, None)
+                                    # Pass first_arg (the full Annotated alias) as source_type so
+                                    # handlers like _PendingArrayHandler can extract the element type.
+                                    schema = md.__get_pydantic_core_schema__(first_arg, None)
                                     if isinstance(schema, dict) and 'metadata' in schema:
                                         sa_type = schema['metadata'].get('sa_type')
                                         if sa_type is not None:
@@ -123,7 +160,10 @@ if sys.version_info >= (3, 14):
                 for md in args[1:]:
                     if hasattr(md, '__get_pydantic_core_schema__'):
                         try:
-                            schema = md.__get_pydantic_core_schema__(None, None)
+                            # Pass annotation (the full Annotated form) as source_type so
+                            # handlers needing the element type (_PendingArrayHandler etc.)
+                            # can extract T from list[T].
+                            schema = md.__get_pydantic_core_schema__(annotation, None)
                             if isinstance(schema, dict) and 'metadata' in schema:
                                 sa_type = schema['metadata'].get('sa_type')
                                 if sa_type is not None:

sqlmodel_ext/base.py

@@ -15,7 +15,7 @@ import re
 import sys
 import types
 import typing
-from typing import Any, get_args, get_origin
+from typing import Any, Self, Sequence, get_args, get_origin
 
 from pydantic import ConfigDict, model_validator
 from pydantic.fields import FieldInfo
@@ -102,6 +102,47 @@ def _merge_field_info_attrs(target: SQLModelFieldInfo, source: SQLModelFieldInfo
         target.metadata = list(target_meta) + list(source_meta)
 
 
+def _find_field_info_in_annotated(annotation: Any) -> SQLModelFieldInfo | None:
+    """
+    Extract SQLModel ``FieldInfo`` embedded in ``Annotated[T, Field(...)]`` metadata.
+
+    Used by the metaclass sa_type injection loop. When a field is declared
+    ``Annotated[X, Field(default_factory=list, ...)]`` *without* an explicit
+    ``= ...`` assignment, ``attrs[field_name]`` is ``Undefined``. Replacing
+    it with a fresh ``Field(sa_type=sa_type)`` would discard the user's
+    Field metadata (``default_factory``, ``max_length``, validators, ...)
+    that lives inside the Annotated args. This helper recovers that
+    FieldInfo so the caller can attach ``sa_type`` to the user's Field
+    instead of clobbering it. The bug only surfaces after 2+ levels of
+    inheritance: single-class instantiation goes through Pydantic's native
+    Annotated path and works, but child classes rebuild ``model_fields``
+    from the clobbered ``attrs`` and the field becomes silently
+    ``is_required=True``.
+
+    Multiple FieldInfo args (e.g. ``Annotated[Str64, Field(unique=True)]``
+    expands to ``Annotated[str, Field(max_length=64), Field(unique=True)]``)
+    are merged into a single shallow copy so the shared Annotated metadata
+    singletons are never mutated.
+
+    :param annotation: Field type annotation
+    :returns: Merged SQLModelFieldInfo (shallow copy, safe to mutate), or None
+    """
+    if get_origin(annotation) is not typing.Annotated:
+        return None
+    args = get_args(annotation)
+    if len(args) < 2:
+        return None
+    sqlmodel_fis: list[SQLModelFieldInfo] = [
+        arg for arg in args[1:] if isinstance(arg, SQLModelFieldInfo)
+    ]
+    if not sqlmodel_fis:
+        return None
+    merged = copy.copy(sqlmodel_fis[0])
+    for extra_fi in sqlmodel_fis[1:]:
+        _merge_field_info_attrs(merged, extra_fi)
+    return merged
+
+
 def _make_annotation_optional(annotation: typing.Any) -> typing.Any:
     """
     Convert type annotation to optional: ``T → T | None``
@@ -179,6 +220,27 @@ def _apply_all_fields_optional(
         if original_ann is None:
             continue
 
+        # Bug fix: when a field is declared as ``field: T = Field(gt=..., le=...)`` (non-Annotated form),
+        # MRO ``__annotations__`` only stores the bare ``T``. The ``Field(...)`` constraint metadata
+        # lives on the right-hand-side assignment, so all_fields_optional-derived UpdateRequest classes
+        # lose those constraints (e.g. UFT-style "missing range" warnings fire on derived fields that
+        # had constraints in the source class). Patch: when ``original_ann`` is not already Annotated,
+        # pull constraints from the base class's resolved ``model_fields[name].metadata`` (Pydantic
+        # stores them there as ``[Gt(0), Le(600), ...]``) and re-wrap into ``Annotated[T, *metadata]``,
+        # letting downstream ``_make_annotation_optional`` preserve the constraints when converting
+        # to ``T | None``. The root recommended fix is still to declare fields in Annotated form at
+        # the source; this patch is defense-in-depth for legacy ``field: T = Field(...)`` declarations.
+        if get_origin(original_ann) is not typing.Annotated:
+            for base in bases:
+                base_model_fields = getattr(base, 'model_fields', None)
+                if not base_model_fields:
+                    continue
+                base_field_info = base_model_fields.get(field_name)
+                if base_field_info is None or not base_field_info.metadata:
+                    continue
+                original_ann = typing.Annotated[original_ann, *base_field_info.metadata]
+                break
+
         # Skip Literal type fields (e.g. discriminator):
         # Literal['text'] | None breaks Pydantic discriminated union
         raw_type = original_ann
@@ -268,10 +330,33 @@ def _recover_annotated_sqlmodel_fields(
     all_annotated.update(annotations)
 
     for field_name, field_type in all_annotated.items():
-        if get_origin(field_type) is not typing.Annotated:
+        # Unwrap Optional/Union wrappers: forms like ``Annotated[X, Field(sa_type=BigInteger)] | None``
+        # have ``get_origin() == Union`` (or ``types.UnionType`` for PEP 604 ``|``); we must
+        # peel back to find the inner Annotated to extract the SQLModel FieldInfo. Otherwise
+        # nullable aliases like ``PositiveBigInt | None`` lose ``sa_type`` and the SA column
+        # silently degrades (e.g. BigInteger → Integer → asyncpg int32 overflow on large defaults).
+        annotated_type = field_type
+        union_args: list[typing.Any] | None = None
+        union_origin = get_origin(field_type)
+        # ``X | None`` (PEP 604) has origin ``types.UnionType``; ``Union[X, None]`` is ``typing.Union``.
+        # Match both without depending on ``types`` import inside any version block.
+        is_union = union_origin is typing.Union or (
+            union_origin is not None and getattr(union_origin, '__name__', '') == 'UnionType'
+        )
+        if is_union:
+            union_args = list(get_args(field_type))
+            annotated_in_union = next(
+                (arg for arg in union_args if get_origin(arg) is typing.Annotated),
+                None,
+            )
+            if annotated_in_union is None:
+                continue
+            annotated_type = annotated_in_union
+
+        if get_origin(annotated_type) is not typing.Annotated:
             continue
 
-        args = get_args(field_type)
+        args = get_args(annotated_type)
         if len(args) < 2:
             continue
 
@@ -313,10 +398,24 @@ def _recover_annotated_sqlmodel_fields(
         base_type = args[0]
         remaining_metadata = [a for a in args[1:] if not isinstance(a, SQLModelFieldInfo)]
         if remaining_metadata:
-            new_ann = typing.Annotated[tuple([base_type] + remaining_metadata)]
+            new_inner: typing.Any = typing.Annotated[tuple([base_type] + remaining_metadata)]
         else:
-            new_ann = base_type
-        annotations[field_name] = new_ann
+            new_inner = base_type
+
+        if union_args is not None:
+            # Rebuild Union: replace the inner Annotated with the stripped version, keeping
+            # the other Union members (e.g. ``| None``) intact. Use PEP 604 ``|`` to accumulate
+            # so we don't trip the deprecated-typing.Union warning.
+            new_union_args = [
+                new_inner if get_origin(arg) is typing.Annotated else arg
+                for arg in union_args
+            ]
+            rebuilt: typing.Any = new_union_args[0]
+            for extra in new_union_args[1:]:
+                rebuilt = rebuilt | extra
+            annotations[field_name] = rebuilt
+        else:
+            annotations[field_name] = new_inner
 
 
 def _make_sti_fk_resolver(
@@ -495,7 +594,19 @@ class __DeclarativeMeta(SQLModelMetaclass):
                 field_value = attrs.get(field_name, Undefined)
 
                 if field_value is Undefined:
-                    attrs[field_name] = Field(sa_type=sa_type)
+                    # No explicit ``= Field(...)`` assignment. Prefer recovering
+                    # FieldInfo from inside Annotated[X, Field(default_factory=..., ...)]
+                    # so user-supplied default_factory / max_length / constraints
+                    # survive — clobbering with a fresh Field(sa_type=sa_type)
+                    # would silently make the field required after multi-level
+                    # inheritance.
+                    annotated_fi = _find_field_info_in_annotated(field_type)
+                    if annotated_fi is not None:
+                        if getattr(annotated_fi, 'sa_type', Undefined) is Undefined:
+                            setattr(annotated_fi, 'sa_type', sa_type)
+                        attrs[field_name] = annotated_fi
+                    else:
+                        attrs[field_name] = Field(sa_type=sa_type)
                 elif isinstance(field_value, FieldInfo):
                     if getattr(field_value, 'sa_type', Undefined) is Undefined:
                         setattr(field_value, 'sa_type', sa_type)
@@ -975,6 +1086,11 @@ class SQLModelBase(SQLModel, metaclass=__DeclarativeMeta):
                         prop['description'] = finfo.description
         return json_schema
 
+    @classmethod
+    def validate_list(cls, items: Sequence[Any]) -> list[Self]:
+        """Batch-convert a sequence of ORM instances (or dicts) to this model type."""
+        return [cls.model_validate(item, from_attributes=True) for item in items]
+
     @classmethod
     def get_computed_field_names(cls) -> set[str]:
         """Get the set of computed_field names for this model class."""

sqlmodel_ext/field_types/__init__.py

@@ -108,6 +108,9 @@ Text5K: TypeAlias = Annotated[str, Field(max_length=5000), _NO_NULL_BYTE]
 Text10K: TypeAlias = Annotated[str, Field(max_length=10000), _NO_NULL_BYTE]
 """10000-character text field"""
 
+Text16K: TypeAlias = Annotated[str, Field(max_length=16000), _NO_NULL_BYTE]
+"""16000-character text field (long-form descriptions, tool docs)"""
+
 Text32K: TypeAlias = Annotated[str, Field(max_length=32000), _NO_NULL_BYTE]
 """32000-character text field"""
 
@@ -120,9 +123,29 @@ Text64K: TypeAlias = Annotated[str, Field(max_length=65536), _NO_NULL_BYTE]
 Text100K: TypeAlias = Annotated[str, Field(max_length=100000), _NO_NULL_BYTE]
 """100000-character text field"""
 
+Text128K: TypeAlias = Annotated[str, Field(max_length=131072), _NO_NULL_BYTE]
+"""131072-character (128 * 1024) text field (large markdown documents etc.)"""
+
 Text1M: TypeAlias = Annotated[str, Field(max_length=1000000), _NO_NULL_BYTE]
 """1000000-character text field (tool call parameters, tool responses, etc.)"""
 
+# NonEmptyStr* — same as Str* but also requires ``min_length=1``, rejecting empty
+# ``""`` strings with a 422 ValidationError. Use for naming fields where the empty
+# string is semantically invalid (e.g. UserFolder.name).
+NonEmptyStr64: TypeAlias = Annotated[str, Field(min_length=1, max_length=64), _NO_NULL_BYTE]
+"""1-64 character non-empty string field"""
+
+NonEmptyStr128: TypeAlias = Annotated[str, Field(min_length=1, max_length=128), _NO_NULL_BYTE]
+"""1-128 character non-empty string field"""
+
+NonEmptyStr256: TypeAlias = Annotated[str, Field(min_length=1, max_length=256), _NO_NULL_BYTE]
+"""1-256 character non-empty string field"""
+
+# Sha256Hex — exactly 64 lowercase hex characters, the canonical SHA-256 hex digest form.
+# The strict regex also implicitly rejects NUL bytes, so no separate _NO_NULL_BYTE is needed.
+Sha256Hex: TypeAlias = Annotated[str, StringConstraints(min_length=64, max_length=64, pattern=r'^[0-9a-f]{64}$')]
+"""64-char lowercase-hex SHA-256 digest (e.g. content hashes)"""
+
 # Numeric range constraints
 Port: TypeAlias = Annotated[int, Field(ge=1, le=65535)]
 """Port number (1-65535)"""

sqlmodel_ext/mixins/cached_table.py

@@ -91,6 +91,7 @@ logger = logging.getLogger(__name__)
 
 from pydantic import ValidationError
 from sqlalchemy import ColumnElement, event, inspect as sa_inspect, select as sa_select
+from sqlalchemy.exc import NoResultFound
 from sqlalchemy.orm import InstanceState, QueryableAttribute, Session as _SyncSession, make_transient_to_detached
 from sqlalchemy.orm.attributes import set_committed_value
 from sqlalchemy.orm.relationships import MANYTOONE  # pyright: ignore[reportPrivateImportUsage]
@@ -1319,6 +1320,15 @@ class CachedTableBaseMixin(TableBaseMixin):
                         if cached is not _LOAD_CACHE_MISS:
                             if cls.on_cache_hit is not None:
                                 cls.on_cache_hit(cls.__name__)
+                            if cached is None and fetch_mode == 'one':
+                                # ``fetch_mode='one'`` type contract guarantees raise (not None);
+                                # when the cache hit is None we must raise, matching the SQL
+                                # path's ``result.one()`` behavior. Otherwise downstream
+                                # ``try/except NoResultFound`` callers (e.g. dep injection that
+                                # maps "missing" to 503) would silently see None and fail later.
+                                raise NoResultFound(
+                                    f"No row was found when one was required: {cls.__name__}(id={id_value})"
+                                )
                             return cached
                         # Redis was actually queried and missed.
 
@@ -1394,18 +1404,25 @@ class CachedTableBaseMixin(TableBaseMixin):
                 else:
                     # Phase 2: merge into the session identity map to preserve
                     # the same semantics as a DB query.
-                    if result is not None:
-                        if isinstance(result, list):
-                            merged_list: list[Self] = []
-                            for item in result:
-                                make_transient_to_detached(item)
-                                merged_list.append(await session.merge(item, load=False))
-                            return merged_list
-                        else:
-                            make_transient_to_detached(result)
-                            result = await session.merge(result, load=False)
                     if cls.on_cache_hit is not None:
                         cls.on_cache_hit(cls.__name__)
+                    if result is None:
+                        if fetch_mode == 'one':
+                            # ``fetch_mode='one'`` type contract guarantees raise (not None);
+                            # raise on cache hit to mirror the SQL path's ``result.one()`` behavior.
+                            raise NoResultFound(
+                                f"No row was found when one was required: {cls.__name__}"
+                            )
+                        return result
+                    if isinstance(result, list):
+                        merged_list: list[Self] = []
+                        for item in result:
+                            make_transient_to_detached(item)
+                            merged_list.append(await session.merge(item, load=False))
+                        return merged_list
+                    else:
+                        make_transient_to_detached(result)
+                        result = await session.merge(result, load=False)
                     return result
 
         # Cache miss callback (only when Redis was actually queried, not skip_cache path)
@@ -1709,35 +1726,53 @@ class CachedTableBaseMixin(TableBaseMixin):
         # SA does not load children and persistent_to_deleted does not fire,
         # so we must query child IDs ourselves before DELETE and invalidate
         # their caches afterwards.
+        #
+        # The walk is BFS over the entire passive_deletes chain — a single
+        # level is not enough. Example: A -[passive=True]-> B -[passive=True]-> C
+        # all use DB CASCADE, SA never loads B or C, persistent_to_deleted
+        # only fires for A. Stale rows of both B and C linger in Redis until
+        # TTL. The BFS prefetches every cached level before issuing DELETE.
         passive_targets: dict[type[CachedTableBaseMixin], list[Any]] = {}
-        try:
-            mapper = sa_inspect(cls)
-            if mapper is None:
-                raise TypeError(f"sa_inspect({cls.__name__}) returned None")
-            for rel in mapper.relationships:
-                if not rel.cascade.delete or not rel.passive_deletes:
-                    continue
-                target = rel.mapper.class_
-                if not (isinstance(target, type) and issubclass(target, CachedTableBaseMixin)):
+        # Queue items: (current_cls, IDs from the previous level, or None for
+        # full-model propagation when the upstream delete used a condition).
+        passive_queue: list[tuple[type, list[Any] | None]] = [
+            (cls, list(instance_ids) if instance_ids else None)
+        ]
+        while passive_queue:
+            current_cls, current_ids = passive_queue.pop(0)
+            try:
+                current_mapper = sa_inspect(current_cls)
+                if current_mapper is None:
                     continue
-                if instance_ids:
+                for rel in current_mapper.relationships:
+                    if not rel.cascade.delete or not rel.passive_deletes:
+                        continue
+                    target = rel.mapper.class_
+                    if not (isinstance(target, type) and issubclass(target, CachedTableBaseMixin)):
+                        continue
+                    if current_ids is None:
+                        # Condition delete or already-full propagation.
+                        if _FULL_MODEL_INVALIDATION not in passive_targets.get(target, []):
+                            passive_targets.setdefault(target, []).append(_FULL_MODEL_INVALIDATION)
+                            passive_queue.append((target, None))
+                        continue
                     remote_cols = list(rel.remote_side)
-                    if len(remote_cols) == 1:
-                        target_mapper = sa_inspect(target)
-                        if target_mapper is None:
-                            continue
-                        target_pk = target_mapper.primary_key[0]
-                        stmt = sa_select(target_pk).where(remote_cols[0].in_(instance_ids))
-                        rows = await session.execute(stmt)
-                        child_ids = [row[0] for row in rows]
-                        if child_ids:
-                            passive_targets[target] = child_ids
-                else:
-                    # Condition deletes cannot enumerate parent IDs; use the
-                    # sentinel to request a model-level full invalidation.
-                    passive_targets[target] = [_FULL_MODEL_INVALIDATION]
-        except Exception as e:
-            logger.warning(f"passive_deletes pre-query failed ({cls.__name__}): {e}")
+                    if len(remote_cols) != 1:
+                        # Composite FK is not supported (matches the original
+                        # single-level behaviour).
+                        continue
+                    target_mapper = sa_inspect(target)
+                    if target_mapper is None:
+                        continue
+                    target_pk = target_mapper.primary_key[0]
+                    stmt = sa_select(target_pk).where(remote_cols[0].in_(current_ids))
+                    rows = await session.execute(stmt)
+                    child_ids = [row[0] for row in rows]
+                    if child_ids:
+                        passive_targets.setdefault(target, []).extend(child_ids)
+                        passive_queue.append((target, child_ids))
+            except Exception as e:
+                logger.warning(f"passive_deletes pre-query failed ({current_cls.__name__}): {e}")
 
         # Clear any leftover cascade data from a previous run (defensive;
         # normal flows never leave residue).

sqlmodel_ext/mixins/polymorphic.py

@@ -453,6 +453,22 @@ class AutoPolymorphicIdentityMixin:
                 # other subclasses' rows won't have values for these columns.
                 # Pydantic-level constraints still apply when creating specific subclasses.
                 column.nullable = True
+
+                # Clear Python-side and server-side defaults on the shared column.
+                # Otherwise, a Pydantic field default (e.g. ``some_field: int = 5``)
+                # gets propagated into Column.default by ``get_column_from_field()``.
+                # When sibling subclasses that do NOT declare this field are inserted,
+                # the attribute is absent from their model_fields and from the
+                # instance's ``__dict__``; the ORM falls back to Column.default and
+                # writes the declaring subclass's default into the sibling row,
+                # silently polluting unrelated rows across the STI table.
+                # The declaring subclass itself is unaffected: Pydantic populates the
+                # instance attribute at ``__init__`` time, and the ORM reads the
+                # value directly from the instance on flush without ever consulting
+                # Column.default.
+                column.default = None
+                column.server_default = None
+
                 parent_table.append_column(column)
             except Exception as e:
                 logger.warning(f"Failed to create column {field_name} for {cls.__name__}: {e}")