sqlmodel-ext 0.5.2__py3-none-any.whl → 0.5.4__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.5.2"
+__version__ = "0.5.4"
 
 # 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

sqlmodel_ext/_compat.py

@@ -1,261 +1,261 @@
-"""
-Python 3.14+ compatibility patches for SQLModel.
-
-This module applies monkey-patches to fix SQLModel's compatibility issues
-with Python 3.14 (PEP 649 deferred evaluation of annotations).
-
-Import this module for side effects before using SQLModelBase.
-"""
-import sys
-
-if sys.version_info >= (3, 14):
-    # 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
-
-    from pydantic_core import PydanticUndefined
-    from sqlalchemy import String
-    from sqlalchemy.orm.attributes import InstrumentedAttribute
-
-    # JSONB with fallback to generic JSON for non-PostgreSQL databases
-    try:
-        from sqlalchemy.dialects.postgresql import JSONB
-    except ImportError:
-        from sqlalchemy.types import JSON as JSONB  # type: ignore[assignment]
-
-    # Monkey-patch 1: Fix get_sqlalchemy_type for Python 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.
-
-        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__(field_annotation, None)
-                        if isinstance(schema, dict) and 'metadata' in schema:
-                            sa_type = schema['metadata'].get('sa_type')
-                            if sa_type is not None:
-                                return sa_type
-                    except (TypeError, AttributeError, KeyError):
-                        pass
-
-        # Check InstrumentedAttribute defaults
-        default = getattr(field, 'default', None)
-        if default is not None:
-            if isinstance(default, InstrumentedAttribute):
-                return None
-
-        annotation = getattr(field, 'annotation', None)
-        if annotation is not None:
-            # Handle Union[list/dict/..., None] types -> JSONB
-            origin = get_origin(annotation)
-
-            is_union = origin is Union or isinstance(annotation, types.UnionType)
-            if is_union:
-                args = get_args(annotation)
-                non_none_args = [a for a in args if a is not type(None)]
-                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)];
-                    # 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__
-                    if first_arg_type_name in ('AnnotatedAlias', '_AnnotatedAlias'):
-                        inner_args = get_args(first_arg)
-                        for md in inner_args[1:]:
-                            if hasattr(md, '__get_pydantic_core_schema__'):
-                                try:
-                                    # 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:
-                                            return sa_type
-                                except (TypeError, AttributeError, KeyError):
-                                    pass
-                    first_origin = get_origin(first_arg)
-                    # Plain list/dict/tuple/set (no Annotated SA type) -> JSONB
-                    if first_origin in (list, dict, tuple, set):
-                        return JSONB
-
-            # Handle Literal[StrEnum.MEMBER] types -> String
-            if origin is Literal:
-                literal_args = get_args(annotation)
-                if literal_args:
-                    if all(isinstance(arg, StrEnum) for arg in literal_args):
-                        return String
-
-            # Check __sqlmodel_sa_type__ attribute
-            if hasattr(annotation, '__sqlmodel_sa_type__'):
-                return annotation.__sqlmodel_sa_type__
-
-            # Check __get_pydantic_core_schema__ for custom types
-            if hasattr(annotation, '__get_pydantic_core_schema__'):
-                try:
-                    schema = annotation.__get_pydantic_core_schema__(annotation, lambda x: None)
-                    if isinstance(schema, dict) and 'metadata' in schema:
-                        sa_type = schema['metadata'].get('sa_type')
-                        if sa_type is not None:
-                            return sa_type
-                except (TypeError, AttributeError, KeyError):
-                    pass
-
-            import typing
-            from sqlalchemy.orm import Mapped
-            anno_type_name = type(annotation).__name__
-
-            # ForwardRef: Relationship field annotations
-            if anno_type_name == 'ForwardRef':
-                return None
-
-            # AnnotatedAlias: check for sa_type metadata
-            if anno_type_name in ('AnnotatedAlias', '_AnnotatedAlias'):
-                args = get_args(annotation)
-                for md in args[1:]:
-                    if hasattr(md, '__get_pydantic_core_schema__'):
-                        try:
-                            # 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:
-                                    return sa_type
-                        except (TypeError, AttributeError, KeyError):
-                            pass
-
-            # _GenericAlias or GenericAlias: typing generic types
-            if anno_type_name in ('_GenericAlias', 'GenericAlias'):
-                local_origin = get_origin(annotation)
-
-                if local_origin is typing.ClassVar:
-                    return None
-
-                if local_origin in (list, dict, tuple, set):
-                    field_info = getattr(field, 'field_info', None)
-                    if field_info is None:
-                        return None
-
-            # Mapped type handling
-            if 'Mapped' in anno_type_name or 'Mapped' in str(annotation):
-                return None
-
-            if get_origin(annotation) is Mapped:
-                return None
-            try:
-                if annotation is Mapped or isinstance(annotation, type) and issubclass(annotation, Mapped):
-                    return None
-            except TypeError:
-                pass
-
-        return _original_get_sqlalchemy_type(field)
-
-    sqlmodel.main.get_sqlalchemy_type = _patched_get_sqlalchemy_type
-
-    # Monkey-patch 2: Fix InstrumentedAttribute defaults in inherited table classes
-    import sqlmodel._compat as _compat
-    from pydantic_core import PydanticUndefined as Undefined
-    from sqlalchemy.orm import attributes as _sa_attributes
-
-    _original_sqlmodel_table_construct = _compat.sqlmodel_table_construct
-
-    def _patched_sqlmodel_table_construct(self_instance, values):
-        """
-        Fix sqlmodel_table_construct to skip InstrumentedAttribute defaults.
-
-        In polymorphic inherited table classes, inherited Relationship fields
-        may have InstrumentedAttribute as their default value, causing errors.
-        """
-        cls = type(self_instance)
-
-        fields_to_set = {}
-
-        for name, field in cls.model_fields.items():
-            if name in values:
-                fields_to_set[name] = values[name]
-                continue
-
-            if isinstance(field.default, _sa_attributes.InstrumentedAttribute):
-                continue
-
-            if field.default is not Undefined:
-                fields_to_set[name] = field.default
-            elif field.default_factory is not None:
-                fields_to_set[name] = field.get_default(call_default_factory=True)
-
-        for key, value in fields_to_set.items():
-            if not isinstance(value, _sa_attributes.InstrumentedAttribute):
-                setattr(self_instance, key, value)
-
-        object.__setattr__(self_instance, '__pydantic_fields_set__', set(values.keys()))
-        if not cls.__pydantic_root_model__:
-            _extra = None
-            if cls.model_config.get('extra') == 'allow':
-                _extra = {}
-                for k, v in values.items():
-                    if k not in cls.model_fields:
-                        _extra[k] = v
-            object.__setattr__(self_instance, '__pydantic_extra__', _extra)
-
-        if cls.__pydantic_post_init__:
-            self_instance.model_post_init(None)
-        elif not cls.__pydantic_root_model__:
-            object.__setattr__(self_instance, '__pydantic_private__', None)
-
-        for key in self_instance.__sqlmodel_relationships__:
-            value = values.get(key, Undefined)
-            if value is not Undefined:
-                setattr(self_instance, key, value)
-
-        return self_instance
-
-    _compat.sqlmodel_table_construct = _patched_sqlmodel_table_construct
+"""
+Python 3.14+ compatibility patches for SQLModel.
+
+This module applies monkey-patches to fix SQLModel's compatibility issues
+with Python 3.14 (PEP 649 deferred evaluation of annotations).
+
+Import this module for side effects before using SQLModelBase.
+"""
+import sys
+
+if sys.version_info >= (3, 14):
+    # 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
+
+    from pydantic_core import PydanticUndefined
+    from sqlalchemy import String
+    from sqlalchemy.orm.attributes import InstrumentedAttribute
+
+    # JSONB with fallback to generic JSON for non-PostgreSQL databases
+    try:
+        from sqlalchemy.dialects.postgresql import JSONB
+    except ImportError:
+        from sqlalchemy.types import JSON as JSONB  # type: ignore[assignment]
+
+    # Monkey-patch 1: Fix get_sqlalchemy_type for Python 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.
+
+        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__(field_annotation, None)
+                        if isinstance(schema, dict) and 'metadata' in schema:
+                            sa_type = schema['metadata'].get('sa_type')
+                            if sa_type is not None:
+                                return sa_type
+                    except (TypeError, AttributeError, KeyError):
+                        pass
+
+        # Check InstrumentedAttribute defaults
+        default = getattr(field, 'default', None)
+        if default is not None:
+            if isinstance(default, InstrumentedAttribute):
+                return None
+
+        annotation = getattr(field, 'annotation', None)
+        if annotation is not None:
+            # Handle Union[list/dict/..., None] types -> JSONB
+            origin = get_origin(annotation)
+
+            is_union = origin is Union or isinstance(annotation, types.UnionType)
+            if is_union:
+                args = get_args(annotation)
+                non_none_args = [a for a in args if a is not type(None)]
+                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)];
+                    # 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__
+                    if first_arg_type_name in ('AnnotatedAlias', '_AnnotatedAlias'):
+                        inner_args = get_args(first_arg)
+                        for md in inner_args[1:]:
+                            if hasattr(md, '__get_pydantic_core_schema__'):
+                                try:
+                                    # 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:
+                                            return sa_type
+                                except (TypeError, AttributeError, KeyError):
+                                    pass
+                    first_origin = get_origin(first_arg)
+                    # Plain list/dict/tuple/set (no Annotated SA type) -> JSONB
+                    if first_origin in (list, dict, tuple, set):
+                        return JSONB
+
+            # Handle Literal[StrEnum.MEMBER] types -> String
+            if origin is Literal:
+                literal_args = get_args(annotation)
+                if literal_args:
+                    if all(isinstance(arg, StrEnum) for arg in literal_args):
+                        return String
+
+            # Check __sqlmodel_sa_type__ attribute
+            if hasattr(annotation, '__sqlmodel_sa_type__'):
+                return annotation.__sqlmodel_sa_type__
+
+            # Check __get_pydantic_core_schema__ for custom types
+            if hasattr(annotation, '__get_pydantic_core_schema__'):
+                try:
+                    schema = annotation.__get_pydantic_core_schema__(annotation, lambda x: None)
+                    if isinstance(schema, dict) and 'metadata' in schema:
+                        sa_type = schema['metadata'].get('sa_type')
+                        if sa_type is not None:
+                            return sa_type
+                except (TypeError, AttributeError, KeyError):
+                    pass
+
+            import typing
+            from sqlalchemy.orm import Mapped
+            anno_type_name = type(annotation).__name__
+
+            # ForwardRef: Relationship field annotations
+            if anno_type_name == 'ForwardRef':
+                return None
+
+            # AnnotatedAlias: check for sa_type metadata
+            if anno_type_name in ('AnnotatedAlias', '_AnnotatedAlias'):
+                args = get_args(annotation)
+                for md in args[1:]:
+                    if hasattr(md, '__get_pydantic_core_schema__'):
+                        try:
+                            # 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:
+                                    return sa_type
+                        except (TypeError, AttributeError, KeyError):
+                            pass
+
+            # _GenericAlias or GenericAlias: typing generic types
+            if anno_type_name in ('_GenericAlias', 'GenericAlias'):
+                local_origin = get_origin(annotation)
+
+                if local_origin is typing.ClassVar:
+                    return None
+
+                if local_origin in (list, dict, tuple, set):
+                    field_info = getattr(field, 'field_info', None)
+                    if field_info is None:
+                        return None
+
+            # Mapped type handling
+            if 'Mapped' in anno_type_name or 'Mapped' in str(annotation):
+                return None
+
+            if get_origin(annotation) is Mapped:
+                return None
+            try:
+                if annotation is Mapped or isinstance(annotation, type) and issubclass(annotation, Mapped):
+                    return None
+            except TypeError:
+                pass
+
+        return _original_get_sqlalchemy_type(field)
+
+    sqlmodel.main.get_sqlalchemy_type = _patched_get_sqlalchemy_type
+
+    # Monkey-patch 2: Fix InstrumentedAttribute defaults in inherited table classes
+    import sqlmodel._compat as _compat
+    from pydantic_core import PydanticUndefined as Undefined
+    from sqlalchemy.orm import attributes as _sa_attributes
+
+    _original_sqlmodel_table_construct = _compat.sqlmodel_table_construct
+
+    def _patched_sqlmodel_table_construct(self_instance, values):
+        """
+        Fix sqlmodel_table_construct to skip InstrumentedAttribute defaults.
+
+        In polymorphic inherited table classes, inherited Relationship fields
+        may have InstrumentedAttribute as their default value, causing errors.
+        """
+        cls = type(self_instance)
+
+        fields_to_set = {}
+
+        for name, field in cls.model_fields.items():
+            if name in values:
+                fields_to_set[name] = values[name]
+                continue
+
+            if isinstance(field.default, _sa_attributes.InstrumentedAttribute):
+                continue
+
+            if field.default is not Undefined:
+                fields_to_set[name] = field.default
+            elif field.default_factory is not None:
+                fields_to_set[name] = field.get_default(call_default_factory=True)
+
+        for key, value in fields_to_set.items():
+            if not isinstance(value, _sa_attributes.InstrumentedAttribute):
+                setattr(self_instance, key, value)
+
+        object.__setattr__(self_instance, '__pydantic_fields_set__', set(values.keys()))
+        if not cls.__pydantic_root_model__:
+            _extra = None
+            if cls.model_config.get('extra') == 'allow':
+                _extra = {}
+                for k, v in values.items():
+                    if k not in cls.model_fields:
+                        _extra[k] = v
+            object.__setattr__(self_instance, '__pydantic_extra__', _extra)
+
+        if cls.__pydantic_post_init__:
+            self_instance.model_post_init(None)
+        elif not cls.__pydantic_root_model__:
+            object.__setattr__(self_instance, '__pydantic_private__', None)
+
+        for key in self_instance.__sqlmodel_relationships__:
+            value = values.get(key, Undefined)
+            if value is not Undefined:
+                setattr(self_instance, key, value)
+
+        return self_instance
+
+    _compat.sqlmodel_table_construct = _patched_sqlmodel_table_construct

sqlmodel_ext/_exceptions.py

@@ -1,16 +1,16 @@
-"""Exceptions for sqlmodel_ext."""
-
-
-class RecordNotFoundError(Exception):
-    """
-    Raised when a database record is not found.
-
-    Attributes:
-        status_code: HTTP-compatible status code (404)
-        detail: Human-readable error message
-    """
-    status_code: int = 404
-
-    def __init__(self, detail: str = "Not found"):
-        self.detail: str = detail
-        super().__init__(detail)
+"""Exceptions for sqlmodel_ext."""
+
+
+class RecordNotFoundError(Exception):
+    """
+    Raised when a database record is not found.
+
+    Attributes:
+        status_code: HTTP-compatible status code (404)
+        detail: Human-readable error message
+    """
+    status_code: int = 404
+
+    def __init__(self, detail: str = "Not found"):
+        self.detail: str = detail
+        super().__init__(detail)