sqlspec 0.13.1__py3-none-any.whl → 0.16.2__py3-none-any.whl

sqlspec/driver/mixins/__init__.py

@@ -1,17 +1,6 @@
 """Driver mixins for instrumentation, storage, and utilities."""
 
-from sqlspec.driver.mixins._pipeline import AsyncPipelinedExecutionMixin, SyncPipelinedExecutionMixin
-from sqlspec.driver.mixins._result_utils import ToSchemaMixin
+from sqlspec.driver.mixins._result_tools import ToSchemaMixin
 from sqlspec.driver.mixins._sql_translator import SQLTranslatorMixin
-from sqlspec.driver.mixins._storage import AsyncStorageMixin, SyncStorageMixin
-from sqlspec.driver.mixins._type_coercion import TypeCoercionMixin
 
-__all__ = (
-    "AsyncPipelinedExecutionMixin",
-    "AsyncStorageMixin",
-    "SQLTranslatorMixin",
-    "SyncPipelinedExecutionMixin",
-    "SyncStorageMixin",
-    "ToSchemaMixin",
-    "TypeCoercionMixin",
-)
+__all__ = ("SQLTranslatorMixin", "ToSchemaMixin")

sqlspec/driver/mixins/_result_tools.py

@@ -0,0 +1,193 @@
+# pyright: reportCallIssue=false, reportAttributeAccessIssue=false, reportArgumentType=false
+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 mypy_extensions import trait
+
+from sqlspec.exceptions import SQLSpecError
+from sqlspec.typing import (
+    CATTRS_INSTALLED,
+    ModelDTOT,
+    ModelT,
+    attrs_asdict,
+    cattrs_structure,
+    cattrs_unstructure,
+    convert,
+    get_type_adapter,
+)
+from sqlspec.utils.type_guards import is_attrs_schema, is_dataclass, is_msgspec_struct, is_pydantic_model
+
+__all__ = ("_DEFAULT_TYPE_DECODERS", "_default_msgspec_deserializer")
+
+
+logger = logging.getLogger(__name__)
+
+# Constants for performance optimization
+_DATETIME_TYPES: Final[set[type]] = {datetime.datetime, datetime.date, datetime.time}
+_PATH_TYPES: Final[tuple[type, ...]] = (Path, PurePath, UUID)
+
+_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)),
+]
+
+
+def _default_msgspec_deserializer(
+    target_type: Any, value: Any, type_decoders: "Optional[Sequence[tuple[Any, Any]]]" = None
+) -> Any:
+    """Default msgspec deserializer with type conversion support.
+
+    Converts values to appropriate types for msgspec deserialization, including
+    UUID, datetime, date, time, Enum, Path, and PurePath types.
+    """
+    if type_decoders:
+        for predicate, decoder in type_decoders:
+            if predicate(target_type):
+                return decoder(target_type, value)
+
+    # Fast path checks using type identity and isinstance
+    if target_type is UUID and isinstance(value, UUID):
+        return value.hex
+
+    # Use pre-computed set for faster lookup
+    if target_type in _DATETIME_TYPES:
+        try:
+            return value.isoformat()
+        except AttributeError:
+            pass
+
+    if isinstance(target_type, type) and issubclass(target_type, Enum) and isinstance(value, Enum):
+        return value.value
+
+    if isinstance(value, target_type):
+        return value
+
+    # Check for path types using pre-computed tuple
+    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
+
+
+@trait
+class ToSchemaMixin:
+    __slots__ = ()
+
+    # Schema conversion overloads - handle common cases first
+    @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]": ...
+    @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": ...
+    @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": ...
+    @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:
+        """Convert data to a specified schema type.
+
+        Supports conversion to dataclasses, msgspec structs, Pydantic models, and attrs classes.
+        Handles both single objects and sequences.
+
+        Raises:
+            SQLSpecError if `schema_type` is not a valid type.
+
+        Returns:
+            Converted data in the specified schema 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 hasattr(item, "keys"):
+                        result.append(schema_type(**dict(item)))  # type: ignore[operator]
+                    else:
+                        result.append(item)
+                return result
+            if hasattr(data, "keys"):
+                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):
+            # Cache the deserializer to avoid repeated partial() calls
+            deserializer = partial(_default_msgspec_deserializer, type_decoders=_DEFAULT_TYPE_DECODERS)
+            if not isinstance(data, Sequence):
+                return convert(obj=data, type=schema_type, from_attributes=True, dec_hook=deserializer)
+            return convert(
+                obj=data,
+                type=list[schema_type],  # type: ignore[valid-type]  # pyright: ignore
+                from_attributes=True,
+                dec_hook=deserializer,
+            )
+        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)  # pyright: ignore
+            list_adapter = get_type_adapter(list[schema_type])  # type: ignore[valid-type]  # pyright: ignore
+            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]  # pyright: ignore
+                if hasattr(data, "__attrs_attrs__"):
+                    unstructured_data = cattrs_unstructure(data)
+                    return cattrs_structure(unstructured_data, schema_type)  # pyright: ignore
+                return cattrs_structure(data, schema_type)  # pyright: ignore
+            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)

sqlspec/driver/mixins/_sql_translator.py

@@ -1,35 +1,86 @@
+from typing import Final, NoReturn, Optional
+
+from mypy_extensions import trait
 from sqlglot import exp, parse_one
 from sqlglot.dialects.dialect import DialectType
 
+from sqlspec.core.statement import SQL, Statement
 from sqlspec.exceptions import SQLConversionError
-from sqlspec.statement.sql import SQL, Statement
 
 __all__ = ("SQLTranslatorMixin",)
 
+# Constants for better performance
+_DEFAULT_PRETTY: Final[bool] = True
+
 
+@trait
 class SQLTranslatorMixin:
     """Mixin for drivers supporting SQL translation."""
 
     __slots__ = ()
 
-    def convert_to_dialect(self, statement: "Statement", to_dialect: DialectType = None, pretty: bool = True) -> str:
-        parsed_expression: exp.Expression
+    def convert_to_dialect(
+        self, statement: "Statement", to_dialect: "Optional[DialectType]" = None, pretty: bool = _DEFAULT_PRETTY
+    ) -> str:
+        """Convert a statement to a target SQL dialect.
+
+        Args:
+            statement: SQL statement to convert
+            to_dialect: Target dialect (defaults to current dialect)
+            pretty: Whether to format the output SQL
+
+        Returns:
+            SQL string in target dialect
+
+        Raises:
+            SQLConversionError: If parsing or conversion fails
+        """
+        # Fast path: get the parsed expression with minimal allocations
+        parsed_expression: Optional[exp.Expression] = None
+
         if statement is not None and isinstance(statement, SQL):
             if statement.expression is None:
-                msg = "Statement could not be parsed"
-                raise SQLConversionError(msg)
+                self._raise_statement_parse_error()
             parsed_expression = statement.expression
         elif isinstance(statement, exp.Expression):
             parsed_expression = statement
         else:
-            try:
-                parsed_expression = parse_one(statement, dialect=self.dialect)  # type: ignore[attr-defined]
-            except Exception as e:
-                error_msg = f"Failed to parse SQL statement: {e!s}"
-                raise SQLConversionError(error_msg) from e
-        target_dialect = to_dialect if to_dialect is not None else self.dialect  # type: ignore[attr-defined]
+            parsed_expression = self._parse_statement_safely(statement)
+
+        # Get target dialect with fallback
+        target_dialect = to_dialect or self.dialect  # type: ignore[attr-defined]
+
+        # Generate SQL with error handling
+        return self._generate_sql_safely(parsed_expression, target_dialect, pretty)
+
+    def _parse_statement_safely(self, statement: "Statement") -> "exp.Expression":
+        """Parse statement with copy=False optimization and proper error handling."""
+        try:
+            # Convert statement to string if needed
+            sql_string = str(statement)
+            # Use copy=False for better performance
+            return parse_one(sql_string, dialect=self.dialect, copy=False)  # type: ignore[attr-defined]
+        except Exception as e:
+            self._raise_parse_error(e)
+
+    def _generate_sql_safely(self, expression: "exp.Expression", dialect: DialectType, pretty: bool) -> str:
+        """Generate SQL with proper error handling."""
         try:
-            return parsed_expression.sql(dialect=target_dialect, pretty=pretty)
+            return expression.sql(dialect=dialect, pretty=pretty)
         except Exception as e:
-            error_msg = f"Failed to convert SQL expression to {target_dialect}: {e!s}"
-            raise SQLConversionError(error_msg) from e
+            self._raise_conversion_error(dialect, e)
+
+    def _raise_statement_parse_error(self) -> NoReturn:
+        """Raise error for unparsable statements."""
+        msg = "Statement could not be parsed"
+        raise SQLConversionError(msg)
+
+    def _raise_parse_error(self, e: Exception) -> NoReturn:
+        """Raise error for parsing failures."""
+        error_msg = f"Failed to parse SQL statement: {e!s}"
+        raise SQLConversionError(error_msg) from e
+
+    def _raise_conversion_error(self, dialect: DialectType, e: Exception) -> NoReturn:
+        """Raise error for conversion failures."""
+        error_msg = f"Failed to convert SQL expression to {dialect}: {e!s}"
+        raise SQLConversionError(error_msg) from e

sqlspec/exceptions.py

@@ -1,48 +1,33 @@
 from collections.abc import Generator
 from contextlib import contextmanager
-from enum import Enum
-from typing import Any, Optional, Union, cast
+from typing import Any, Optional, Union
 
 __all__ = (
-    "ExtraParameterError",
     "FileNotFoundInStorageError",
     "ImproperConfigurationError",
     "IntegrityError",
     "MissingDependencyError",
-    "MissingParameterError",
     "MultipleResultsFoundError",
     "NotFoundError",
-    "ParameterError",
-    "ParameterStyleMismatchError",
-    "PipelineExecutionError",
-    "QueryError",
     "RepositoryError",
-    "RiskLevel",
     "SQLBuilderError",
-    "SQLCompilationError",
     "SQLConversionError",
     "SQLFileNotFoundError",
     "SQLFileParseError",
-    "SQLFileParsingError",
-    "SQLInjectionError",
     "SQLParsingError",
     "SQLSpecError",
-    "SQLTransformationError",
-    "SQLValidationError",
     "SerializationError",
     "StorageOperationFailedError",
-    "UnknownParameterError",
-    "UnsafeSQLError",
 )
 
 
 class SQLSpecError(Exception):
-    """Base exception class from which all Advanced Alchemy exceptions inherit."""
+    """Base exception class for SQLSpec exceptions."""
 
     detail: str
 
     def __init__(self, *args: Any, detail: str = "") -> None:
-        """Initialize ``AdvancedAlchemyException``.
+        """Initialize SQLSpecError.
 
         Args:
             *args: args are converted to :class:`str` before passing to :class:`Exception`
@@ -67,10 +52,7 @@ class SQLSpecError(Exception):
 
 
 class MissingDependencyError(SQLSpecError, ImportError):
-    """Missing optional dependency.
-
-    This exception is raised only when a module depends on a dependency that has not been installed.
-    """
+    """Raised when a required dependency is not installed."""
 
     def __init__(self, package: str, install_package: Optional[str] = None) -> None:
         super().__init__(
@@ -87,15 +69,6 @@ class BackendNotRegisteredError(SQLSpecError):
         super().__init__(f"Storage backend '{backend_key}' is not registered. Please register it before use.")
 
 
-class SQLLoadingError(SQLSpecError):
-    """Issues loading referenced SQL file."""
-
-    def __init__(self, message: Optional[str] = None) -> None:
-        if message is None:
-            message = "Issues loading referenced SQL file."
-        super().__init__(message)
-
-
 class SQLParsingError(SQLSpecError):
     """Issues parsing SQL statements."""
 
@@ -105,15 +78,6 @@ class SQLParsingError(SQLSpecError):
         super().__init__(message)
 
 
-class SQLFileParsingError(SQLSpecError):
-    """Issues parsing SQL files."""
-
-    def __init__(self, message: Optional[str] = None) -> None:
-        if message is None:
-            message = "Issues parsing SQL files."
-        super().__init__(message)
-
-
 class SQLBuilderError(SQLSpecError):
     """Issues Building or Generating SQL statements."""
 
@@ -123,15 +87,6 @@ class SQLBuilderError(SQLSpecError):
         super().__init__(message)
 
 
-class SQLCompilationError(SQLSpecError):
-    """Issues Compiling SQL statements."""
-
-    def __init__(self, message: Optional[str] = None) -> None:
-        if message is None:
-            message = "Issues compiling SQL statement."
-        super().__init__(message)
-
-
 class SQLConversionError(SQLSpecError):
     """Issues converting SQL statements."""
 
@@ -141,170 +96,8 @@ class SQLConversionError(SQLSpecError):
         super().__init__(message)
 
 
-# -- SQL Validation Errors --
-class RiskLevel(Enum):
-    """SQL risk assessment levels."""
-
-    SKIP = 1
-    SAFE = 2
-    LOW = 3
-    MEDIUM = 4
-    HIGH = 5
-    CRITICAL = 6
-
-    def __str__(self) -> str:
-        """String representation.
-
-        Returns:
-            Lowercase name of the style.
-        """
-        return self.name.lower()
-
-    def __lt__(self, other: "RiskLevel") -> bool:  # pragma: no cover
-        """Less than comparison for ordering."""
-        if not isinstance(other, RiskLevel):
-            return NotImplemented
-        return self.value < other.value
-
-    def __le__(self, other: "RiskLevel") -> bool:  # pragma: no cover
-        """Less than or equal comparison for ordering."""
-        if not isinstance(other, RiskLevel):
-            return NotImplemented
-        return self.value <= other.value
-
-    def __gt__(self, other: "RiskLevel") -> bool:  # pragma: no cover
-        """Greater than comparison for ordering."""
-        if not isinstance(other, RiskLevel):
-            return NotImplemented
-        return self.value > other.value
-
-    def __ge__(self, other: "RiskLevel") -> bool:  # pragma: no cover
-        """Greater than or equal comparison for ordering."""
-        if not isinstance(other, RiskLevel):
-            return NotImplemented
-        return self.value >= other.value
-
-
-class SQLValidationError(SQLSpecError):
-    """Base class for SQL validation errors."""
-
-    sql: Optional[str]
-    risk_level: RiskLevel
-
-    def __init__(self, message: str, sql: Optional[str] = None, risk_level: RiskLevel = RiskLevel.MEDIUM) -> None:
-        """Initialize with SQL context and risk level."""
-        detail_message = message
-        if sql is not None:
-            detail_message = f"{message}\nSQL: {sql}"
-        super().__init__(detail=detail_message)
-        self.sql = sql
-        self.risk_level = risk_level
-
-
-class SQLTransformationError(SQLSpecError):
-    """Base class for SQL transformation errors."""
-
-    sql: Optional[str]
-
-    def __init__(self, message: str, sql: Optional[str] = None) -> None:
-        """Initialize with SQL context and risk level."""
-        detail_message = message
-        if sql is not None:
-            detail_message = f"{message}\nSQL: {sql}"
-        super().__init__(detail=detail_message)
-        self.sql = sql
-
-
-class SQLInjectionError(SQLValidationError):
-    """Raised when potential SQL injection is detected."""
-
-    pattern: Optional[str]
-
-    def __init__(self, message: str, sql: Optional[str] = None, pattern: Optional[str] = None) -> None:
-        """Initialize with injection pattern context."""
-        detail_message = message
-        if pattern:
-            detail_message = f"{message} (Pattern: {pattern})"
-        super().__init__(detail_message, sql, RiskLevel.CRITICAL)
-        self.pattern = pattern
-
-
-class UnsafeSQLError(SQLValidationError):
-    """Raised when unsafe SQL constructs are detected."""
-
-    construct: Optional[str]
-
-    def __init__(self, message: str, sql: Optional[str] = None, construct: Optional[str] = None) -> None:
-        """Initialize with unsafe construct context."""
-        detail_message = message
-        if construct:
-            detail_message = f"{message} (Construct: {construct})"
-        super().__init__(detail_message, sql, RiskLevel.HIGH)
-        self.construct = construct
-
-
-# -- SQL Query Errors --
-class QueryError(SQLSpecError):
-    """Base class for Query errors."""
-
-
-# -- SQL Parameter Errors --
-class ParameterError(SQLSpecError):
-    """Base class for parameter-related errors."""
-
-    sql: Optional[str]
-
-    def __init__(self, message: str, sql: Optional[str] = None) -> None:
-        """Initialize with optional SQL context."""
-        detail_message = message
-        if sql is not None:
-            detail_message = f"{message}\nSQL: {sql}"
-        super().__init__(detail=detail_message)
-        self.sql = sql
-
-
-class UnknownParameterError(ParameterError):
-    """Raised when encountering unknown parameter syntax."""
-
-
-class MissingParameterError(ParameterError):
-    """Raised when required parameters are missing."""
-
-
-class ExtraParameterError(ParameterError):
-    """Raised when extra parameters are provided."""
-
-
-class ParameterStyleMismatchError(SQLSpecError):
-    """Error when parameter style doesn't match SQL placeholder style.
-
-    This exception is raised when there's a mismatch between the parameter type
-    (dictionary, tuple, etc.) and the placeholder style in the SQL query
-    (named, positional, etc.).
-    """
-
-    sql: Optional[str]
-
-    def __init__(self, message: Optional[str] = None, sql: Optional[str] = None) -> None:
-        final_message = message
-        if final_message is None:
-            final_message = (
-                "Parameter style mismatch: dictionary parameters provided but no named placeholders found in SQL."
-            )
-
-        detail_message = final_message
-        if sql:
-            detail_message = f"{final_message}\nSQL: {sql}"
-
-        super().__init__(detail=detail_message)
-        self.sql = sql
-
-
 class ImproperConfigurationError(SQLSpecError):
-    """Improper Configuration error.
-
-    This exception is raised only when a module depends on a dependency that has not been installed.
-    """
+    """Raised when configuration is invalid or incomplete."""
 
 
 class SerializationError(SQLSpecError):
@@ -398,43 +191,3 @@ def wrap_exceptions(
             raise
         msg = "An error occurred during the operation."
         raise RepositoryError(detail=msg) from exc
-
-
-class PipelineExecutionError(SQLSpecError):
-    """Rich error information for pipeline execution failures."""
-
-    def __init__(
-        self,
-        message: str,
-        *,
-        operation_index: "Optional[int]" = None,
-        failed_operation: "Optional[Any]" = None,
-        partial_results: "Optional[list[Any]]" = None,
-        driver_error: "Optional[Exception]" = None,
-    ) -> None:
-        """Initialize the pipeline execution error.
-
-        Args:
-            message: Error message describing the failure
-            operation_index: Index of the operation that failed
-            failed_operation: The PipelineOperation that failed
-            partial_results: Results from operations that succeeded before the failure
-            driver_error: Original exception from the database driver
-        """
-        super().__init__(message)
-        self.operation_index = operation_index
-        self.failed_operation = failed_operation
-        self.partial_results = partial_results or []
-        self.driver_error = driver_error
-
-    def get_failed_sql(self) -> "Optional[str]":
-        """Get the SQL that failed for debugging."""
-        if self.failed_operation and hasattr(self.failed_operation, "sql"):
-            return cast("str", self.failed_operation.sql.to_sql())
-        return None
-
-    def get_failed_parameters(self) -> "Optional[Any]":
-        """Get the parameters that failed."""
-        if self.failed_operation and hasattr(self.failed_operation, "original_params"):
-            return self.failed_operation.original_params
-        return None