sqlspec 0.25.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/driver/mixins/_result_tools.py

@@ -1,130 +1,15 @@
-# ruff: noqa: C901
 """Result handling and schema conversion mixins for database drivers."""
 
-import datetime
-import logging
-from collections.abc import Sequence
-from enum import Enum
-from functools import partial
-from pathlib import Path, PurePath
-from typing import Any, Callable, Final, Optional, overload
-from uuid import UUID
+from typing import TYPE_CHECKING, Any, overload
 
 from mypy_extensions import trait
 
-from sqlspec.exceptions import SQLSpecError
-from sqlspec.typing import (
-    CATTRS_INSTALLED,
-    NUMPY_INSTALLED,
-    ModelDTOT,
-    ModelT,
-    attrs_asdict,
-    cattrs_structure,
-    cattrs_unstructure,
-    convert,
-    get_type_adapter,
-)
-from sqlspec.utils.data_transformation import transform_dict_keys
-from sqlspec.utils.text import camelize, kebabize, pascalize
-from sqlspec.utils.type_guards import (
-    get_msgspec_rename_config,
-    is_attrs_schema,
-    is_dataclass,
-    is_dict,
-    is_msgspec_struct,
-    is_pydantic_model,
-)
+from sqlspec.utils.schema import to_schema
 
-__all__ = ("_DEFAULT_TYPE_DECODERS", "_default_msgspec_deserializer")
+if TYPE_CHECKING:
+    from sqlspec.typing import SchemaT
 
-
-logger = logging.getLogger(__name__)
-
-
-_DATETIME_TYPES: Final[set[type]] = {datetime.datetime, datetime.date, datetime.time}
-
-
-def _is_list_type_target(target_type: Any) -> bool:
-    """Check if target type is a list type (e.g., list[float])."""
-    try:
-        return hasattr(target_type, "__origin__") and target_type.__origin__ is list
-    except (AttributeError, TypeError):
-        return False
-
-
-def _convert_numpy_to_list(target_type: Any, value: Any) -> Any:
-    """Convert numpy array to list if target is a list type."""
-    if not NUMPY_INSTALLED:
-        return value
-
-    import numpy as np
-
-    if isinstance(value, np.ndarray) and _is_list_type_target(target_type):
-        return value.tolist()
-
-    return value
-
-
-_DEFAULT_TYPE_DECODERS: Final[list[tuple[Callable[[Any], bool], Callable[[Any, Any], Any]]]] = [
-    (lambda x: x is UUID, lambda t, v: t(v.hex)),
-    (lambda x: x is datetime.datetime, lambda t, v: t(v.isoformat())),
-    (lambda x: x is datetime.date, lambda t, v: t(v.isoformat())),
-    (lambda x: x is datetime.time, lambda t, v: t(v.isoformat())),
-    (lambda x: x is Enum, lambda t, v: t(v.value)),
-    (_is_list_type_target, _convert_numpy_to_list),
-]
-
-
-def _default_msgspec_deserializer(
-    target_type: Any, value: Any, type_decoders: "Optional[Sequence[tuple[Any, Any]]]" = None
-) -> Any:
-    """Convert msgspec types with type decoder support.
-
-    Args:
-        target_type: Type to convert to
-        value: Value to convert
-        type_decoders: Optional sequence of (predicate, decoder) pairs
-
-    Returns:
-        Converted value or original value if conversion not applicable
-    """
-    # Handle numpy arrays first for list types
-    if NUMPY_INSTALLED:
-        import numpy as np
-
-        if isinstance(value, np.ndarray) and _is_list_type_target(target_type):
-            return value.tolist()
-
-    if type_decoders:
-        for predicate, decoder in type_decoders:
-            if predicate(target_type):
-                return decoder(target_type, value)
-
-    if target_type is UUID and isinstance(value, UUID):
-        return value.hex
-
-    if target_type in _DATETIME_TYPES and hasattr(value, "isoformat"):
-        return value.isoformat()  # pyright: ignore
-
-    if isinstance(target_type, type) and issubclass(target_type, Enum) and isinstance(value, Enum):
-        return value.value
-
-    # Check if value is already the correct type (but avoid parameterized generics)
-    try:
-        if isinstance(target_type, type) and isinstance(value, target_type):
-            return value
-    except TypeError:
-        # Handle parameterized generics like list[int] which can't be used with isinstance
-        pass
-
-    if isinstance(target_type, type):
-        try:
-            if issubclass(target_type, (Path, PurePath)) or issubclass(target_type, UUID):
-                return target_type(str(value))
-        except (TypeError, ValueError):
-            pass
-
-    return value
+__all__ = ("ToSchemaMixin",)
 
 
 @trait
@@ -135,143 +20,42 @@ class ToSchemaMixin:
 
     @overload
     @staticmethod
-    def to_schema(data: "list[dict[str, Any]]") -> "list[dict[str, Any]]": ...
-    @overload
-    @staticmethod
-    def to_schema(data: "list[dict[str, Any]]", *, schema_type: "type[ModelDTOT]") -> "list[ModelDTOT]": ...
+    def to_schema(data: "list[dict[str, Any]]", *, schema_type: "type[SchemaT]") -> "list[SchemaT]": ...
     @overload
     @staticmethod
     def to_schema(data: "list[dict[str, Any]]", *, schema_type: None = None) -> "list[dict[str, Any]]": ...
     @overload
     @staticmethod
-    def to_schema(data: "dict[str, Any]") -> "dict[str, Any]": ...
-    @overload
-    @staticmethod
-    def to_schema(data: "dict[str, Any]", *, schema_type: "type[ModelDTOT]") -> "ModelDTOT": ...
+    def to_schema(data: "dict[str, Any]", *, schema_type: "type[SchemaT]") -> "SchemaT": ...
     @overload
     @staticmethod
     def to_schema(data: "dict[str, Any]", *, schema_type: None = None) -> "dict[str, Any]": ...
     @overload
     @staticmethod
-    def to_schema(data: "list[ModelT]") -> "list[ModelT]": ...
-    @overload
-    @staticmethod
-    def to_schema(data: "list[ModelT]", *, schema_type: "type[ModelDTOT]") -> "list[ModelDTOT]": ...
-    @overload
-    @staticmethod
-    def to_schema(data: "list[ModelT]", *, schema_type: None = None) -> "list[ModelT]": ...
-    @overload
-    @staticmethod
-    def to_schema(data: "ModelT") -> "ModelT": ...
+    def to_schema(data: Any, *, schema_type: "type[SchemaT]") -> Any: ...
     @overload
     @staticmethod
     def to_schema(data: Any, *, schema_type: None = None) -> Any: ...
 
     @staticmethod
-    def to_schema(data: Any, *, schema_type: "Optional[type[ModelDTOT]]" = None) -> Any:
+    def to_schema(data: Any, *, schema_type: "type[Any] | None" = None) -> Any:
         """Convert data to a specified schema type.
 
+        Supports transformation to various schema types including:
+        - TypedDict
+        - dataclasses
+        - msgspec Structs
+        - Pydantic models
+        - attrs classes
+
         Args:
-            data: Input data to convert
-            schema_type: Target schema type for conversion
+            data: Input data to convert (dict, list of dicts, or other)
+            schema_type: Target schema type for conversion. If None, returns data unchanged.
 
         Returns:
-            Converted data in the specified schema type
+            Converted data in the specified schema type, or original data if schema_type is None
 
         Raises:
             SQLSpecError: If schema_type is not a supported type
         """
-        if schema_type is None:
-            return data
-        if is_dataclass(schema_type):
-            if isinstance(data, list):
-                result: list[Any] = []
-                for item in data:
-                    if is_dict(item):
-                        result.append(schema_type(**dict(item)))  # type: ignore[operator]
-                    else:
-                        result.append(item)
-                return result
-            if is_dict(data):
-                return schema_type(**dict(data))  # type: ignore[operator]
-            if isinstance(data, dict):
-                return schema_type(**data)  # type: ignore[operator]
-            return data
-        if is_msgspec_struct(schema_type):
-            rename_config = get_msgspec_rename_config(schema_type)  # type: ignore[arg-type]
-            deserializer = partial(_default_msgspec_deserializer, type_decoders=_DEFAULT_TYPE_DECODERS)
-
-            # Transform field names if rename configuration exists
-            transformed_data = data
-            if (rename_config and is_dict(data)) or (isinstance(data, Sequence) and data and is_dict(data[0])):
-                try:
-                    converter = None
-                    if rename_config == "camel":
-                        converter = camelize
-                    elif rename_config == "kebab":
-                        converter = kebabize
-                    elif rename_config == "pascal":
-                        converter = pascalize
-
-                    if converter is not None:
-                        if isinstance(data, Sequence):
-                            transformed_data = [
-                                transform_dict_keys(item, converter) if is_dict(item) else item for item in data
-                            ]
-                        else:
-                            transformed_data = transform_dict_keys(data, converter) if is_dict(data) else data
-                except Exception as e:
-                    logger.debug("Field name transformation failed for msgspec schema: %s", e)
-                    transformed_data = data
-
-            # Pre-process numpy arrays to lists before msgspec conversion
-            if NUMPY_INSTALLED:
-                try:
-                    import numpy as np
-
-                    def _convert_numpy_arrays_in_data(obj: Any) -> Any:
-                        """Recursively convert numpy arrays to lists in data structures."""
-                        if isinstance(obj, np.ndarray):
-                            return obj.tolist()
-                        if isinstance(obj, dict):
-                            return {k: _convert_numpy_arrays_in_data(v) for k, v in obj.items()}
-                        if isinstance(obj, (list, tuple)):
-                            return type(obj)(_convert_numpy_arrays_in_data(item) for item in obj)
-                        return obj
-
-                    transformed_data = _convert_numpy_arrays_in_data(transformed_data)
-                except ImportError:
-                    pass
-
-            if not isinstance(transformed_data, Sequence):
-                return convert(obj=transformed_data, type=schema_type, from_attributes=True, dec_hook=deserializer)
-            return convert(obj=transformed_data, type=list[schema_type], from_attributes=True, dec_hook=deserializer)  # type: ignore[valid-type]
-        if is_pydantic_model(schema_type):
-            if not isinstance(data, Sequence):
-                adapter = get_type_adapter(schema_type)
-                return adapter.validate_python(data, from_attributes=True)
-            list_adapter = get_type_adapter(list[schema_type])  # type: ignore[valid-type]
-            return list_adapter.validate_python(data, from_attributes=True)
-        if is_attrs_schema(schema_type):
-            if CATTRS_INSTALLED:
-                if isinstance(data, Sequence):
-                    return cattrs_structure(data, list[schema_type])  # type: ignore[valid-type]
-                if hasattr(data, "__attrs_attrs__"):
-                    unstructured_data = cattrs_unstructure(data)
-                    return cattrs_structure(unstructured_data, schema_type)
-                return cattrs_structure(data, schema_type)
-            if isinstance(data, list):
-                attrs_result: list[Any] = []
-                for item in data:
-                    if hasattr(item, "keys"):
-                        attrs_result.append(schema_type(**dict(item)))
-                    else:
-                        attrs_result.append(schema_type(**attrs_asdict(item)))
-                return attrs_result
-            if hasattr(data, "keys"):
-                return schema_type(**dict(data))
-            if isinstance(data, dict):
-                return schema_type(**data)
-            return data
-        msg = "`schema_type` should be a valid Dataclass, Pydantic model, Msgspec struct, or Attrs class"
-        raise SQLSpecError(msg)
+        return to_schema(data, schema_type=schema_type)

sqlspec/driver/mixins/_sql_translator.py

@@ -1,6 +1,6 @@
 """SQL translation mixin for cross-database compatibility."""
 
-from typing import Final, NoReturn, Optional
+from typing import Final, NoReturn
 
 from mypy_extensions import trait
 from sqlglot import exp, parse_one
@@ -20,10 +20,10 @@ class SQLTranslatorMixin:
     """Mixin for drivers supporting SQL translation."""
 
     __slots__ = ()
-    dialect: "Optional[DialectType]"
+    dialect: "DialectType | None"
 
     def convert_to_dialect(
-        self, statement: "Statement", to_dialect: "Optional[DialectType]" = None, pretty: bool = _DEFAULT_PRETTY
+        self, statement: "Statement", to_dialect: "DialectType | None" = None, pretty: bool = _DEFAULT_PRETTY
     ) -> str:
         """Convert a statement to a target SQL dialect.
 
@@ -38,7 +38,7 @@ class SQLTranslatorMixin:
 
         """
 
-        parsed_expression: Optional[exp.Expression] = None
+        parsed_expression: exp.Expression | None = None
 
         if statement is not None and isinstance(statement, SQL):
             if statement.expression is None:

sqlspec/exceptions.py

@@ -1,14 +1,24 @@
 from collections.abc import Generator
 from contextlib import contextmanager
-from typing import Any, Optional, Union
+from typing import Any
 
 __all__ = (
+    "CheckViolationError",
+    "ConfigResolverError",
+    "DataError",
+    "DatabaseConnectionError",
     "FileNotFoundInStorageError",
+    "ForeignKeyViolationError",
     "ImproperConfigurationError",
     "IntegrityError",
+    "InvalidVersionFormatError",
+    "MigrationError",
     "MissingDependencyError",
     "MultipleResultsFoundError",
     "NotFoundError",
+    "NotNullViolationError",
+    "OperationalError",
+    "OutOfOrderMigrationError",
     "RepositoryError",
     "SQLBuilderError",
     "SQLConversionError",
@@ -18,6 +28,8 @@ __all__ = (
     "SQLSpecError",
     "SerializationError",
     "StorageOperationFailedError",
+    "TransactionError",
+    "UniqueViolationError",
 )
 
 
@@ -54,7 +66,7 @@ class SQLSpecError(Exception):
 class MissingDependencyError(SQLSpecError, ImportError):
     """Raised when a required dependency is not installed."""
 
-    def __init__(self, package: str, install_package: Optional[str] = None) -> None:
+    def __init__(self, package: str, install_package: str | None = None) -> None:
         super().__init__(
             f"Package {package!r} is not installed but required. You can install it by running "
             f"'pip install sqlspec[{install_package or package}]' to install sqlspec with the required extra "
@@ -69,10 +81,14 @@ class BackendNotRegisteredError(SQLSpecError):
         super().__init__(f"Storage backend '{backend_key}' is not registered. Please register it before use.")
 
 
+class ConfigResolverError(SQLSpecError):
+    """Exception raised when config resolution fails."""
+
+
 class SQLParsingError(SQLSpecError):
     """Issues parsing SQL statements."""
 
-    def __init__(self, message: Optional[str] = None) -> None:
+    def __init__(self, message: str | None = None) -> None:
         if message is None:
             message = "Issues parsing SQL statement."
         super().__init__(message)
@@ -81,7 +97,7 @@ class SQLParsingError(SQLSpecError):
 class SQLBuilderError(SQLSpecError):
     """Issues Building or Generating SQL statements."""
 
-    def __init__(self, message: Optional[str] = None) -> None:
+    def __init__(self, message: str | None = None) -> None:
         if message is None:
             message = "Issues building SQL statement."
         super().__init__(message)
@@ -90,7 +106,7 @@ class SQLBuilderError(SQLSpecError):
 class SQLConversionError(SQLSpecError):
     """Issues converting SQL statements."""
 
-    def __init__(self, message: Optional[str] = None) -> None:
+    def __init__(self, message: str | None = None) -> None:
         if message is None:
             message = "Issues converting SQL statement."
         super().__init__(message)
@@ -120,6 +136,38 @@ class MultipleResultsFoundError(RepositoryError):
     """A single database result was required but more than one were found."""
 
 
+class UniqueViolationError(IntegrityError):
+    """A unique constraint was violated."""
+
+
+class ForeignKeyViolationError(IntegrityError):
+    """A foreign key constraint was violated."""
+
+
+class CheckViolationError(IntegrityError):
+    """A check constraint was violated."""
+
+
+class NotNullViolationError(IntegrityError):
+    """A not-null constraint was violated."""
+
+
+class DatabaseConnectionError(SQLSpecError):
+    """Database connection error (invalid credentials, network failure, etc.)."""
+
+
+class TransactionError(SQLSpecError):
+    """Transaction error (rollback, deadlock, serialization failure)."""
+
+
+class DataError(SQLSpecError):
+    """Invalid data type or format for database operation."""
+
+
+class OperationalError(SQLSpecError):
+    """Operational database error (timeout, disk full, resource limit)."""
+
+
 class StorageOperationFailedError(SQLSpecError):
     """Raised when a storage backend operation fails (e.g., network, permission, API error)."""
 
@@ -131,7 +179,7 @@ class FileNotFoundInStorageError(StorageOperationFailedError):
 class SQLFileNotFoundError(SQLSpecError):
     """Raised when a SQL file cannot be found."""
 
-    def __init__(self, name: str, path: "Optional[str]" = None) -> None:
+    def __init__(self, name: str, path: "str | None" = None) -> None:
         """Initialize the error.
 
         Args:
@@ -162,9 +210,29 @@ class SQLFileParseError(SQLSpecError):
         self.original_error = original_error
 
 
+class MigrationError(SQLSpecError):
+    """Base exception for migration-related errors."""
+
+
+class InvalidVersionFormatError(MigrationError):
+    """Raised when a migration version format is invalid.
+
+    Invalid formats include versions that don't match sequential (0001)
+    or timestamp (YYYYMMDDHHmmss) patterns, or timestamps with invalid dates.
+    """
+
+
+class OutOfOrderMigrationError(MigrationError):
+    """Raised when an out-of-order migration is detected in strict mode.
+
+    Out-of-order migrations occur when a pending migration has a timestamp
+    earlier than already-applied migrations, typically from late-merging branches.
+    """
+
+
 @contextmanager
 def wrap_exceptions(
-    wrap_exceptions: bool = True, suppress: "Optional[Union[type[Exception], tuple[type[Exception], ...]]]" = None
+    wrap_exceptions: bool = True, suppress: "type[Exception] | tuple[type[Exception], ...] | None" = None
 ) -> Generator[None, None, None]:
     """Context manager for exception handling with optional suppression.
 

sqlspec/extensions/adk/__init__.py

@@ -0,0 +1,53 @@
+"""Google ADK session backend extension for SQLSpec.
+
+Provides session and event storage for Google Agent Development Kit using
+SQLSpec database adapters.
+
+Public API exports:
+    - ADKConfig: TypedDict for extension config (type-safe configuration)
+    - SQLSpecSessionService: Main service class implementing BaseSessionService
+    - BaseAsyncADKStore: Base class for async database store implementations
+    - BaseSyncADKStore: Base class for sync database store implementations
+    - SessionRecord: TypedDict for session database records
+    - EventRecord: TypedDict for event database records
+
+Example (with extension_config):
+    from sqlspec.adapters.asyncpg import AsyncpgConfig
+    from sqlspec.adapters.asyncpg.adk.store import AsyncpgADKStore
+    from sqlspec.extensions.adk import SQLSpecSessionService
+
+    config = AsyncpgConfig(
+        pool_config={"dsn": "postgresql://..."},
+        extension_config={
+            "adk": {
+                "session_table": "my_sessions",
+                "events_table": "my_events",
+                "owner_id_column": "tenant_id INTEGER REFERENCES tenants(id)"
+            }
+        }
+    )
+
+    store = AsyncpgADKStore(config)
+    await store.create_tables()
+
+    service = SQLSpecSessionService(store)
+    session = await service.create_session(
+        app_name="my_app",
+        user_id="user123",
+        state={"key": "value"}
+    )
+"""
+
+from sqlspec.config import ADKConfig
+from sqlspec.extensions.adk._types import EventRecord, SessionRecord
+from sqlspec.extensions.adk.service import SQLSpecSessionService
+from sqlspec.extensions.adk.store import BaseAsyncADKStore, BaseSyncADKStore
+
+__all__ = (
+    "ADKConfig",
+    "BaseAsyncADKStore",
+    "BaseSyncADKStore",
+    "EventRecord",
+    "SQLSpecSessionService",
+    "SessionRecord",
+)

sqlspec/extensions/adk/_types.py

@@ -0,0 +1,51 @@
+"""Type definitions for ADK extension.
+
+These types define the database record structures for storing sessions and events.
+They are separate from the Pydantic models to keep mypyc compilation working.
+"""
+
+from datetime import datetime
+from typing import Any, TypedDict
+
+__all__ = ("EventRecord", "SessionRecord")
+
+
+class SessionRecord(TypedDict):
+    """Database record for a session.
+
+    Represents the schema for sessions stored in the database.
+    """
+
+    id: str
+    app_name: str
+    user_id: str
+    state: "dict[str, Any]"
+    create_time: datetime
+    update_time: datetime
+
+
+class EventRecord(TypedDict):
+    """Database record for an event.
+
+    Represents the schema for events stored in the database.
+    Follows the ADK Event model plus session metadata.
+    """
+
+    id: str
+    app_name: str
+    user_id: str
+    session_id: str
+    invocation_id: str
+    author: str
+    branch: "str | None"
+    actions: bytes
+    long_running_tool_ids_json: "str | None"
+    timestamp: datetime
+    content: "dict[str, Any] | None"
+    grounding_metadata: "dict[str, Any] | None"
+    custom_metadata: "dict[str, Any] | None"
+    partial: "bool | None"
+    turn_complete: "bool | None"
+    interrupted: "bool | None"
+    error_code: "str | None"
+    error_message: "str | None"