sqlspec 0.16.1__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

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

@@ -0,0 +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
+
+__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: "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:
+                self._raise_statement_parse_error()
+            parsed_expression = statement.expression
+        elif isinstance(statement, exp.Expression):
+            parsed_expression = statement
+        else:
+            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 expression.sql(dialect=dialect, pretty=pretty)
+        except Exception as 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

@@ -0,0 +1,193 @@
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any, Optional, Union
+
+__all__ = (
+    "FileNotFoundInStorageError",
+    "ImproperConfigurationError",
+    "IntegrityError",
+    "MissingDependencyError",
+    "MultipleResultsFoundError",
+    "NotFoundError",
+    "RepositoryError",
+    "SQLBuilderError",
+    "SQLConversionError",
+    "SQLFileNotFoundError",
+    "SQLFileParseError",
+    "SQLParsingError",
+    "SQLSpecError",
+    "SerializationError",
+    "StorageOperationFailedError",
+)
+
+
+class SQLSpecError(Exception):
+    """Base exception class for SQLSpec exceptions."""
+
+    detail: str
+
+    def __init__(self, *args: Any, detail: str = "") -> None:
+        """Initialize SQLSpecError.
+
+        Args:
+            *args: args are converted to :class:`str` before passing to :class:`Exception`
+            detail: detail of the exception.
+        """
+        str_args = [str(arg) for arg in args if arg]
+        if not detail:
+            if str_args:
+                detail, *str_args = str_args
+            elif hasattr(self, "detail"):
+                detail = self.detail
+        self.detail = detail
+        super().__init__(*str_args)
+
+    def __repr__(self) -> str:
+        if self.detail:
+            return f"{self.__class__.__name__} - {self.detail}"
+        return self.__class__.__name__
+
+    def __str__(self) -> str:
+        return " ".join((*self.args, self.detail)).strip()
+
+
+class MissingDependencyError(SQLSpecError, ImportError):
+    """Raised when a required dependency is not installed."""
+
+    def __init__(self, package: str, install_package: Optional[str] = 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 "
+            f"or 'pip install {install_package or package}' to install the package separately"
+        )
+
+
+class BackendNotRegisteredError(SQLSpecError):
+    """Raised when a requested storage backend key is not registered."""
+
+    def __init__(self, backend_key: str) -> None:
+        super().__init__(f"Storage backend '{backend_key}' is not registered. Please register it before use.")
+
+
+class SQLParsingError(SQLSpecError):
+    """Issues parsing SQL statements."""
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        if message is None:
+            message = "Issues parsing SQL statement."
+        super().__init__(message)
+
+
+class SQLBuilderError(SQLSpecError):
+    """Issues Building or Generating SQL statements."""
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        if message is None:
+            message = "Issues building SQL statement."
+        super().__init__(message)
+
+
+class SQLConversionError(SQLSpecError):
+    """Issues converting SQL statements."""
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        if message is None:
+            message = "Issues converting SQL statement."
+        super().__init__(message)
+
+
+class ImproperConfigurationError(SQLSpecError):
+    """Raised when configuration is invalid or incomplete."""
+
+
+class SerializationError(SQLSpecError):
+    """Encoding or decoding of an object failed."""
+
+
+class RepositoryError(SQLSpecError):
+    """Base repository exception type."""
+
+
+class IntegrityError(RepositoryError):
+    """Data integrity error."""
+
+
+class NotFoundError(RepositoryError):
+    """An identity does not exist."""
+
+
+class MultipleResultsFoundError(RepositoryError):
+    """A single database result was required but more than one were found."""
+
+
+class StorageOperationFailedError(SQLSpecError):
+    """Raised when a storage backend operation fails (e.g., network, permission, API error)."""
+
+
+class FileNotFoundInStorageError(StorageOperationFailedError):
+    """Raised when a file or object is not found in the storage backend."""
+
+
+class SQLFileNotFoundError(SQLSpecError):
+    """Raised when a SQL file cannot be found."""
+
+    def __init__(self, name: str, path: "Optional[str]" = None) -> None:
+        """Initialize the error.
+
+        Args:
+            name: Name of the SQL file.
+            path: Optional path where the file was expected.
+        """
+        message = f"SQL file '{name}' not found at path: {path}" if path else f"SQL file '{name}' not found"
+        super().__init__(message)
+        self.name = name
+        self.path = path
+
+
+class SQLFileParseError(SQLSpecError):
+    """Raised when a SQL file cannot be parsed."""
+
+    def __init__(self, name: str, path: str, original_error: "Exception") -> None:
+        """Initialize the error.
+
+        Args:
+            name: Name of the SQL file.
+            path: Path to the SQL file.
+            original_error: The underlying parsing error.
+        """
+        message = f"Failed to parse SQL file '{name}' at {path}: {original_error}"
+        super().__init__(message)
+        self.name = name
+        self.path = path
+        self.original_error = original_error
+
+
+@contextmanager
+def wrap_exceptions(
+    wrap_exceptions: bool = True, suppress: "Optional[Union[type[Exception], tuple[type[Exception], ...]]]" = None
+) -> Generator[None, None, None]:
+    """Context manager for exception handling with optional suppression.
+
+    Args:
+        wrap_exceptions: If True, wrap exceptions in RepositoryError. If False, let them pass through.
+        suppress: Exception type(s) to suppress completely (like contextlib.suppress).
+                 If provided, these exceptions are caught and ignored.
+    """
+    try:
+        yield
+
+    except Exception as exc:
+        if suppress is not None and (
+            (isinstance(suppress, type) and isinstance(exc, suppress))
+            or (isinstance(suppress, tuple) and isinstance(exc, suppress))
+        ):
+            return  # Suppress this exception
+
+        # If it's already a SQLSpec exception, don't wrap it
+        if isinstance(exc, SQLSpecError):
+            raise
+
+        if wrap_exceptions is False:
+            raise
+        msg = "An error occurred during the operation."
+        raise RepositoryError(detail=msg) from exc

sqlspec/extensions/aiosql/__init__.py

@@ -0,0 +1,10 @@
+"""SQLSpec aiosql integration for loading SQL files.
+
+This module provides a simple way to load aiosql-style SQL files and use them
+with SQLSpec drivers. It focuses on just the file parsing functionality,
+returning SQL objects that work with existing SQLSpec execution.
+"""
+
+from sqlspec.extensions.aiosql.adapter import AiosqlAsyncAdapter, AiosqlSyncAdapter
+
+__all__ = ("AiosqlAsyncAdapter", "AiosqlSyncAdapter")