sqlmodel-ext 0.4.2__py3-none-any.whl → 0.5.1__py3-none-any.whl

sqlmodel_ext/__init__.py

@@ -20,154 +20,235 @@ Quick start::
     user = await user.save(session)
     users = await User.get(session, fetch_mode="all")
 """
-__version__ = "0.4.2"
+__version__ = "0.5.1"
+
+# Every re-export below uses the redundant ``X as X`` form: the package ships
+# ``py.typed``, and type checkers treat a plain ``from m import X`` in a typed
+# package as private (consumers would get ``reportPrivateImportUsage``).
 
 # Base
-from sqlmodel_ext.base import SQLModelBase, ExtraIgnoreModelBase, CustomTableArg
+from sqlmodel_ext.base import (
+    SQLModelBase as SQLModelBase,
+    ExtraIgnoreModelBase as ExtraIgnoreModelBase,
+    CustomTableArg as CustomTableArg,
+    SQLModelExtConfig as SQLModelExtConfig,
+)
+
+# Tri-state semantics ("not provided" vs null) and the optional wire value
+from sqlmodel_ext.unset import Unset as Unset, OMITTED_SENTINEL as OMITTED_SENTINEL
+
+# Field metadata markers
+from sqlmodel_ext.constants import EXCLUDE_IF_NONE as EXCLUDE_IF_NONE
 
-# Enhanced session (cache-aware commit/reset/refresh/execute)
-from sqlmodel_ext.session import AsyncSession
+# ``sqlmodel.select`` with overloads for 5-9 column projections (same object at runtime)
+from sqlmodel_ext.select import select as select
+
+# Enhanced session (cache-aware commit/reset/refresh/execute, REPEATABLE READ retries)
+from sqlmodel_ext.session import (
+    AsyncSession as AsyncSession,
+    SessionFactory as SessionFactory,
+    RepeatableReadSnapshotConflictError as RepeatableReadSnapshotConflictError,
+    SerializationRetryExhaustedError as SerializationRetryExhaustedError,
+)
 
 # Exceptions
-from sqlmodel_ext._exceptions import RecordNotFoundError
+from sqlmodel_ext._exceptions import RecordNotFoundError as RecordNotFoundError
 
 # Pagination
 from sqlmodel_ext.pagination import (
-    ListResponse,
-    TimeFilterRequest,
-    PaginationRequest,
-    TableViewRequest,
+    DEFAULT_PAGE_SIZE as DEFAULT_PAGE_SIZE,
+    MAX_PAGE_SIZE as MAX_PAGE_SIZE,
+    MAX_TABLE_VIEW_OFFSET as MAX_TABLE_VIEW_OFFSET,
+    ListResponse as ListResponse,
+    TimeFilterRequest as TimeFilterRequest,
+    PageWindowRequest as PageWindowRequest,
+    PaginationRequest as PaginationRequest,
+    TableViewRequest as TableViewRequest,
 )
 
+# FastAPI dependency for query-parameter DTOs (cross-field errors -> 422; requires the `fastapi` extra when called)
+from sqlmodel_ext.dependencies import query_dependency as query_dependency
+
 # Mixins
 from sqlmodel_ext.mixins import (
     # Table
-    SESSION_FOR_UPDATE_KEY,
-    TableBaseMixin,
-    UUIDTableBaseMixin,
-    rel,
-    cond,
+    SESSION_FOR_UPDATE_KEY as SESSION_FOR_UPDATE_KEY,
+    SESSION_REPEATABLE_READ_KEY as SESSION_REPEATABLE_READ_KEY,
+    GroupSumRow as GroupSumRow,
+    TableBaseMixin as TableBaseMixin,
+    UUIDTableBaseMixin as UUIDTableBaseMixin,
+    rel as rel,
+    cond as cond,
+    uuid7 as uuid7,
+    # Delete / keyset exceptions
+    FK_DELETE_RESTRICT_FALLBACK_MESSAGE as FK_DELETE_RESTRICT_FALLBACK_MESSAGE,
+    ResourceReferencedError as ResourceReferencedError,
+    KeysetCursorError as KeysetCursorError,
+    KeysetCursorInvalidError as KeysetCursorInvalidError,
+    KeysetCursorUnsupportedError as KeysetCursorUnsupportedError,
     # Polymorphic
-    PolymorphicBaseMixin,
-    AutoPolymorphicIdentityMixin,
-    DeferredIndex,
-    create_subclass_id_mixin,
-    register_sti_columns_for_all_subclasses,
-    register_sti_column_properties_for_all_subclasses,
+    PolymorphicBaseMixin as PolymorphicBaseMixin,
+    AutoPolymorphicIdentityMixin as AutoPolymorphicIdentityMixin,
+    DeferredIndex as DeferredIndex,
+    create_subclass_id_mixin as create_subclass_id_mixin,
+    register_sti_columns_for_all_subclasses as register_sti_columns_for_all_subclasses,
+    register_sti_column_properties_for_all_subclasses as register_sti_column_properties_for_all_subclasses,
     # Optimistic Lock
-    OptimisticLockMixin,
-    OptimisticLockError,
+    OptimisticLockMixin as OptimisticLockMixin,
+    OptimisticLockError as OptimisticLockError,
     # Relation Preload
-    RelationPreloadMixin,
-    requires_relations,
-    requires_for_update,
+    RelationPreloadMixin as RelationPreloadMixin,
+    requires_relations as requires_relations,
+    requires_for_update as requires_for_update,
+    requires_locked_param as requires_locked_param,
+    requires_read_committed as requires_read_committed,
+    requires_repeatable_read as requires_repeatable_read,
+    validate_locked_instances as validate_locked_instances,
     # Cached Table
-    CachedTableBaseMixin,
+    CachedTableBaseMixin as CachedTableBaseMixin,
+    CACHE_TTL_HOT as CACHE_TTL_HOT,
+    CACHE_TTL_WARM as CACHE_TTL_WARM,
+    CACHE_TTL_COLD as CACHE_TTL_COLD,
+    collect_migration_invalidation_tasks as collect_migration_invalidation_tasks,
+    run_pending_migration_cache_invalidations as run_pending_migration_cache_invalidations,
     # Info Response DTOs
-    IntIdInfoMixin,
-    UUIDIdInfoMixin,
-    DatetimeInfoMixin,
-    IntIdDatetimeInfoMixin,
-    UUIDIdDatetimeInfoMixin,
+    IntIdInfoMixin as IntIdInfoMixin,
+    UUIDIdInfoMixin as UUIDIdInfoMixin,
+    DatetimeInfoMixin as DatetimeInfoMixin,
+    IntIdDatetimeInfoMixin as IntIdDatetimeInfoMixin,
+    UUIDIdDatetimeInfoMixin as UUIDIdDatetimeInfoMixin,
+    # Resource quota
+    ResourceQuotaMixin as ResourceQuotaMixin,
+    QuotaExceededError as QuotaExceededError,
+    QuotaOwnerNotFoundError as QuotaOwnerNotFoundError,
+    CallerDidNotCommitError as CallerDidNotCommitError,
+    # Mixin table scan
+    MixinTableScanMixin as MixinTableScanMixin,
+    # Trigram search (PostgreSQL pg_trgm)
+    BIGRAM_FUNCTION_SQL as BIGRAM_FUNCTION_SQL,
+    TrgmSearchableMixin as TrgmSearchableMixin,
+    TrgmSearchRequest as TrgmSearchRequest,
 )
 
 # Field Types
 from sqlmodel_ext.field_types import (
     # Path types
-    DirectoryPathType,
-    FilePathType,
+    DirectoryPathType as DirectoryPathType,
+    FilePathType as FilePathType,
     # String constraints
-    Str16,
-    Str24,
-    Str32,
-    Str36,
-    Str48,
-    Str64,
-    Str100,
-    Str128,
-    Str255,
-    Str256,
-    Str500,
-    Str512,
-    Str2048,
-    Text1K,
-    Text1024,
-    Text2K,
-    Text2500,
-    Text3K,
-    Text5K,
-    Text8K,
-    Text10K,
-    Text16K,
-    Text32K,
-    Text48K,
-    Text60K,
-    Text64K,
-    Text100K,
-    Text128K,
-    Text1M,
-    NonEmptyStr64,
-    NonEmptyStr128,
-    NonEmptyStr256,
-    NonEmptyStrippedStr64,
-    NonEmptyStrippedStr128,
-    NonEmptyStrippedStr256,
-    Sha256Hex,
-    BCP47LanguageCode,
+    max_length_of as max_length_of,
+    Str1 as Str1,
+    Str16 as Str16,
+    Str24 as Str24,
+    Str32 as Str32,
+    Str36 as Str36,
+    Str48 as Str48,
+    Str64 as Str64,
+    Str100 as Str100,
+    Str128 as Str128,
+    Str255 as Str255,
+    Str256 as Str256,
+    Str500 as Str500,
+    Str512 as Str512,
+    Str2048 as Str2048,
+    Text1K as Text1K,
+    Text1024 as Text1024,
+    Text2K as Text2K,
+    Text2500 as Text2500,
+    Text3K as Text3K,
+    Text3072 as Text3072,
+    Text4K as Text4K,
+    Text5K as Text5K,
+    Text8K as Text8K,
+    Text10K as Text10K,
+    Text16K as Text16K,
+    Text32K as Text32K,
+    Text48K as Text48K,
+    Text60K as Text60K,
+    Text64K as Text64K,
+    Text100K as Text100K,
+    Text128K as Text128K,
+    Text1M as Text1M,
+    NonEmptyStr64 as NonEmptyStr64,
+    NonEmptyStr128 as NonEmptyStr128,
+    NonEmptyStr256 as NonEmptyStr256,
+    NonEmptyStrippedStr32 as NonEmptyStrippedStr32,
+    NonEmptyStrippedStr64 as NonEmptyStrippedStr64,
+    NonEmptyStrippedStr128 as NonEmptyStrippedStr128,
+    NonEmptyStrippedStr256 as NonEmptyStrippedStr256,
+    Sha256Hex as Sha256Hex,
+    BCP47LanguageCode as BCP47LanguageCode,
+    SingleLineStr64 as SingleLineStr64,
+    SearchQueryStr64 as SearchQueryStr64,
+    HttpHeaderName as HttpHeaderName,
     # Numeric constraints
-    INT32_MAX,
-    INT64_MAX,
-    JS_MAX_SAFE_INTEGER,
-    Port,
-    Percentage,
-    PositiveInt,
-    NonNegativeInt,
-    PositiveBigInt,
-    NonNegativeBigInt,
-    PositiveFloat,
-    NonNegativeFloat,
+    INT32_MIN as INT32_MIN,
+    INT32_MAX as INT32_MAX,
+    INT64_MAX as INT64_MAX,
+    JS_MAX_SAFE_INTEGER as JS_MAX_SAFE_INTEGER,
+    Port as Port,
+    Percentage as Percentage,
+    PositiveInt as PositiveInt,
+    NonNegativeInt as NonNegativeInt,
+    PositiveBigInt as PositiveBigInt,
+    NonNegativeBigInt as NonNegativeBigInt,
+    SignedBigInt as SignedBigInt,
+    PositiveFloat as PositiveFloat,
+    NonNegativeFloat as NonNegativeFloat,
     # Decimal constraints (NUMERIC(p, s) + sign + JSON-string serialization)
-    SignedDecimal38_18,
-    NonNegativeDecimal38_18,
-    PositiveDecimal38_18,
-    OptionalNonNegativeDecimal38_18,
-    SignedDecimal20_10,
-    NonNegativeDecimal20_10,
-    OptionalNonNegativeDecimal20_10,
+    SignedDecimal38_18 as SignedDecimal38_18,
+    NonNegativeDecimal38_18 as NonNegativeDecimal38_18,
+    PositiveDecimal38_18 as PositiveDecimal38_18,
+    OptionalNonNegativeDecimal38_18 as OptionalNonNegativeDecimal38_18,
+    OptionalSignedDecimal38_18 as OptionalSignedDecimal38_18,
+    SignedWriteDecimal38_18 as SignedWriteDecimal38_18,
+    NonNegativeWriteDecimal38_18 as NonNegativeWriteDecimal38_18,
+    PositiveWriteDecimal38_18 as PositiveWriteDecimal38_18,
+    OptionalNonNegativeWriteDecimal38_18 as OptionalNonNegativeWriteDecimal38_18,
+    OptionalSignedWriteDecimal38_18 as OptionalSignedWriteDecimal38_18,
+    SignedSumDecimal38_18 as SignedSumDecimal38_18,
+    DECIMAL_38_18_COLUMN_DIGITS as DECIMAL_38_18_COLUMN_DIGITS,
+    DECIMAL_38_18_WRITE_DIGITS as DECIMAL_38_18_WRITE_DIGITS,
+    DECIMAL_38_18_PLACES as DECIMAL_38_18_PLACES,
+    SignedDecimal20_10 as SignedDecimal20_10,
+    NonNegativeDecimal20_10 as NonNegativeDecimal20_10,
+    OptionalNonNegativeDecimal20_10 as OptionalNonNegativeDecimal20_10,
+    NullableNonNegativeDecimal20_10 as NullableNonNegativeDecimal20_10,
     # Bounded-length list aliases
-    List,
-    List1,
-    List2,
-    List3,
-    List7,
-    List10,
-    List16,
-    List20,
-    List32,
-    List40,
-    List50,
-    List64,
-    List100,
-    List128,
-    List200,
-    List256,
-    List1024,
+    List as List,
+    List1 as List1,
+    List2 as List2,
+    List3 as List3,
+    List7 as List7,
+    List10 as List10,
+    List16 as List16,
+    List20 as List20,
+    List32 as List32,
+    List40 as List40,
+    List50 as List50,
+    List64 as List64,
+    List100 as List100,
+    List128 as List128,
+    List200 as List200,
+    List256 as List256,
+    List1024 as List1024,
     # Custom types
-    IPAddress,
-    Url,
-    HttpUrl,
-    WebSocketUrl,
-    SafeHttpUrl,
-    UnsafeURLError,
-    validate_not_private_host,
-    ModuleNameMixin,
+    IPAddress as IPAddress,
+    ClientIPAddress as ClientIPAddress,
+    Url as Url,
+    HttpUrl as HttpUrl,
+    WebSocketUrl as WebSocketUrl,
+    SafeHttpUrl as SafeHttpUrl,
+    UnsafeURLError as UnsafeURLError,
+    validate_not_private_host as validate_not_private_host,
+    ModuleNameMixin as ModuleNameMixin,
 )
 
 # Relation Load Checker (static analysis)
 from sqlmodel_ext.relation_load_checker import (
-    RelationLoadChecker,
-    RelationLoadWarning,
-    RelationLoadCheckMiddleware,
-    run_model_checks,
-    mark_app_check_completed,
+    RelationLoadChecker as RelationLoadChecker,
+    RelationLoadWarning as RelationLoadWarning,
+    RelationLoadCheckMiddleware as RelationLoadCheckMiddleware,
+    run_model_checks as run_model_checks,
+    mark_app_check_completed as mark_app_check_completed,
 )

sqlmodel_ext/_compat.py

@@ -9,7 +9,9 @@ Import this module for side effects before using SQLModelBase.
 import sys
 
 if sys.version_info >= (3, 14):
-    import annotationlib  # noqa: F401
+    # The checker analyzes at pythonVersion 3.12 (the lowest supported version), where this
+    # version-gated block is statically unreachable; it does run on 3.14+.
+    import annotationlib  # noqa: F401  # pyright: ignore[reportUnreachable]
     import types
     from enum import StrEnum
     from typing import Literal, Union, get_args, get_origin
@@ -101,7 +103,7 @@ if sys.version_info >= (3, 14):
                 if non_none_args:
                     first_arg = non_none_args[0]
                     # Check for Annotated SA type metadata first (e.g. Array[T] | None).
-                    # Array[T] desugars to Annotated[list[T], _ArrayTypeHandler(T)];
+                    # Array[T] desugars to Annotated[list[T], ArrayTypeHandler(T)];
                     # wrapping with | None produces Union[Annotated[...], None],
                     # so the SA type must be extracted from the inner Annotated.
                     first_arg_type_name = type(first_arg).__name__

sqlmodel_ext/_exceptions.py

@@ -12,5 +12,5 @@ class RecordNotFoundError(Exception):
     status_code: int = 404
 
     def __init__(self, detail: str = "Not found"):
-        self.detail = detail
+        self.detail: str = detail
         super().__init__(detail)

sqlmodel_ext/_sa_type.py

@@ -2,15 +2,27 @@
 Internal helpers for extracting SQLAlchemy types from annotations.
 
 These are used by the metaclass to inject sa_type into Field definitions.
+
+Internal protocol, not part of the public API: the functions carry public names
+only because :mod:`sqlmodel_ext.base` (the metaclass) imports them across module
+boundaries; the module itself stays private (``_sa_type``).
 """
 import sys
 import typing
-from typing import Any, Mapping, get_args, get_origin, get_type_hints
+from collections.abc import Mapping
+from typing import Any, get_args, get_origin, get_type_hints
+
 
-from sqlalchemy.orm import Mapped
+def _null_schema_handler(_source_type: Any) -> None:
+    """
+    Stand-in for pydantic's ``GetCoreSchemaHandler`` when probing a type's
+    ``__get_pydantic_core_schema__`` for ``metadata['sa_type']``: the probe
+    only reads the metadata and never needs the delegated inner schema.
+    """
+    return None
 
 
-def _extract_sa_type_from_annotation(annotation: Any) -> Any | None:
+def extract_sa_type_from_annotation(annotation: Any) -> Any | None:
     """
     Extract SQLAlchemy type from a type annotation.
 
@@ -40,7 +52,7 @@ def _extract_sa_type_from_annotation(annotation: Any) -> Any | None:
                     try:
                         schema = item.__get_pydantic_core_schema__(
                             annotation,
-                            lambda x: None,
+                            _null_schema_handler,
                         )
                         if isinstance(schema, dict) and 'metadata' in schema:
                             sa_type = schema['metadata'].get('sa_type')
@@ -54,7 +66,7 @@ def _extract_sa_type_from_annotation(annotation: Any) -> Any | None:
         try:
             schema = annotation.__get_pydantic_core_schema__(
                 annotation,
-                lambda x: None,
+                _null_schema_handler,
             )
             if isinstance(schema, dict) and 'metadata' in schema:
                 sa_type = schema['metadata'].get('sa_type')
@@ -66,7 +78,7 @@ def _extract_sa_type_from_annotation(annotation: Any) -> Any | None:
     return None
 
 
-def _resolve_annotations(attrs: dict[str, Any]) -> tuple[
+def resolve_annotations(attrs: dict[str, Any]) -> tuple[
     dict[str, Any],
     dict[str, str],
     Mapping[str, Any],
@@ -112,7 +124,7 @@ def _resolve_annotations(attrs: dict[str, Any]) -> tuple[
     return dict(evaluated), {}, module_globals, localns
 
 
-def _evaluate_annotation_from_string(
+def evaluate_annotation_from_string(
     field_name: str,
     annotation_strings: dict[str, str],
     current_type: Any,
@@ -129,7 +141,7 @@ def _evaluate_annotation_from_string(
         return current_type
 
     expr = annotation_strings.get(field_name)
-    if not expr or not isinstance(expr, str):
+    if not expr:
         return current_type
 
     try:

sqlmodel_ext/_type_unwrap.py

@@ -0,0 +1,117 @@
+"""
+Type-annotation unwrapping helpers (shared mechanical operations).
+
+Extracts the inner concrete type from wrappers such as ``Annotated[X, ...]``,
+``X | None`` or ``ListResponse[X]``. Pure type-system operations with no domain
+semantics and no state, hence plain module-level functions.
+
+**Why a dedicated unwrapper is needed**: Pydantic v2 concrete generics (e.g.
+``ListResponse[FooResponse]``) are fully concrete ``ModelMetaclass`` instances;
+``typing.get_origin()`` / ``typing.get_args()`` **both return empty values** for
+them. The real generic arguments live in
+``__pydantic_generic_metadata__['args']``. Using only the standard ``typing``
+API would make every generic response model opaque.
+
+Consumer: :mod:`sqlmodel_ext.relation_load_checker` (RLC005 / RLC012 drill down
+from a ``response_model`` to its DTO / ORM classes).
+"""
+import types
+import typing
+from typing import Annotated, Any, Final
+
+# ``typing.Union`` as a runtime value: the ``get_origin()`` of ``Optional[X]`` /
+# ``Union[X, Y]`` on Python < 3.14 (``X | Y`` has origin ``types.UnionType``).
+# reportDeprecated targets spelling *annotations* with ``Union`` (use ``X | Y``);
+# an identity-comparison target has no non-deprecated spelling, so the single
+# reference lives here and every origin check in the package compares against
+# this name (internal protocol, not part of the public API).
+TYPING_UNION: Final = typing.Union  # pyright: ignore[reportDeprecated]
+
+
+def unwrap_to_class(hint: Any) -> type | None:
+    """
+    Extract the actual class from a type annotation.
+
+    Handles ``Annotated[X, ...]``, ``X | None``, ``Optional[X]`` and returns the
+    innermost concrete type. Generic containers are **not** drilled into
+    (``ListResponse[X]`` returns the container class itself); use
+    :func:`unwrap_generic_to_dto_class` for that.
+
+    :param hint: any type annotation object
+    :returns: the actual type, or ``None`` if it cannot be extracted
+    """
+    origin = typing.get_origin(hint)
+
+    # Annotated[X, ...] -> unwrap X
+    if origin is Annotated:
+        args = typing.get_args(hint)
+        if args:
+            return unwrap_to_class(args[0])
+
+    # X | None (UnionType) or Optional[X] (Union[X, None])
+    if origin is types.UnionType or origin is TYPING_UNION:
+        args = typing.get_args(hint)
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return unwrap_to_class(non_none[0])
+
+    # Plain class
+    if isinstance(hint, type):
+        return hint
+
+    return None
+
+
+def get_pydantic_generic_args(hint: Any) -> tuple[Any, ...]:
+    """
+    Extract the type arguments of a generic (compatible with Pydantic v2 concrete generics).
+
+    Pydantic v2's ``ListResponse[T]`` creates a fully concrete ``ModelMetaclass``
+    instance for which ``typing.get_origin()`` / ``typing.get_args()`` return
+    empty values. The real generic arguments are in
+    ``__pydantic_generic_metadata__['args']``.
+
+    :param hint: any type annotation object
+    :returns: the generic arguments, or an empty tuple if there are none
+    """
+    # Standard typing API first
+    args = typing.get_args(hint)
+    if args:
+        return args
+    # Pydantic concrete-generic fallback
+    pgm = getattr(hint, '__pydantic_generic_metadata__', None)
+    if pgm is not None:
+        return pgm.get('args', ())
+    return ()
+
+
+def unwrap_generic_to_dto_class(hint: Any) -> type | None:
+    """
+    Recursively extract a DTO class (a class with ``model_fields``) from a type annotation.
+
+    Container types (Pydantic generic models such as ``ListResponse``) are skipped
+    and their generic arguments are drilled into. For a union annotation the
+    **first** member that yields a DTO wins; callers that need every member must
+    iterate ``get_pydantic_generic_args`` / ``typing.get_args`` themselves.
+
+    :param hint: any type annotation object
+    :returns: the inner DTO class, or ``None`` if it cannot be extracted
+    """
+    # Pydantic generic container? (has __pydantic_generic_metadata__ with a non-empty origin)
+    pgm = getattr(hint, '__pydantic_generic_metadata__', None)
+    is_pydantic_generic = pgm is not None and pgm.get('origin') is not None
+
+    if not is_pydantic_generic:
+        cls = unwrap_to_class(hint)
+        if cls is not None and hasattr(cls, 'model_fields'):
+            return cls
+
+    # Recurse into generic arguments
+    for arg in get_pydantic_generic_args(hint):
+        if arg is type(None):
+            continue
+        result = unwrap_generic_to_dto_class(arg)
+        if result is not None:
+            return result
+
+    return None