sqlspec 0.17.1__py3-none-any.whl → 0.19.0__py3-none-any.whl

sqlspec/driver/_common.py

@@ -1,8 +1,4 @@
-"""Common driver attributes and utilities.
-
-This module provides core driver infrastructure including execution result handling,
-common driver attributes, parameter processing, and SQL compilation utilities.
-"""
+"""Common driver attributes and utilities."""
 
 from typing import TYPE_CHECKING, Any, Final, NamedTuple, Optional, Union, cast
 
@@ -10,7 +6,7 @@ from mypy_extensions import trait
 from sqlglot import exp
 
 from sqlspec.builder import QueryBuilder
-from sqlspec.core import SQL, OperationType, ParameterStyle, SQLResult, Statement, StatementConfig, TypedParameter
+from sqlspec.core import SQL, ParameterStyle, SQLResult, Statement, StatementConfig, TypedParameter
 from sqlspec.core.cache import get_cache_config, sql_cache
 from sqlspec.core.splitter import split_sql_script
 from sqlspec.exceptions import ImproperConfigurationError
@@ -38,19 +34,7 @@ logger = get_logger("driver")
 
 
 class ScriptExecutionResult(NamedTuple):
-    """Result from script execution with statement count information.
-
-    This named tuple eliminates the need for redundant script splitting
-    by providing statement count information during execution rather than
-    requiring re-parsing after execution.
-
-    Attributes:
-        cursor_result: The result returned by the database cursor/driver
-        rowcount_override: Optional override for the number of affected rows
-        special_data: Any special metadata or additional information
-        statement_count: Total number of statements in the script
-        successful_statements: Number of statements that executed successfully
-    """
+    """Result from script execution with statement count information."""
 
     cursor_result: Any
     rowcount_override: Optional[int]
@@ -60,24 +44,7 @@ class ScriptExecutionResult(NamedTuple):
 
 
 class ExecutionResult(NamedTuple):
-    """Comprehensive execution result containing all data needed for SQLResult building.
-
-    This named tuple consolidates all execution result data to eliminate the need
-    for additional data extraction calls and script re-parsing in build_statement_result.
-
-    Attributes:
-        cursor_result: The raw result returned by the database cursor/driver
-        rowcount_override: Optional override for the number of affected rows
-        special_data: Any special metadata or additional information from execution
-        selected_data: For SELECT operations, the extracted row data
-        column_names: For SELECT operations, the column names
-        data_row_count: For SELECT operations, the number of rows returned
-        statement_count: For script operations, total number of statements
-        successful_statements: For script operations, number of successful statements
-        is_script_result: Whether this result is from script execution
-        is_select_result: Whether this result is from a SELECT operation
-        is_many_result: Whether this result is from an execute_many operation
-    """
+    """Execution result containing all data needed for SQLResult building."""
 
     cursor_result: Any
     rowcount_override: Optional[int]
@@ -93,20 +60,15 @@ class ExecutionResult(NamedTuple):
     last_inserted_id: Optional[Union[int, str]] = None
 
 
-EXEC_CURSOR_RESULT = 0
-EXEC_ROWCOUNT_OVERRIDE = 1
-EXEC_SPECIAL_DATA = 2
+EXEC_CURSOR_RESULT: Final[int] = 0
+EXEC_ROWCOUNT_OVERRIDE: Final[int] = 1
+EXEC_SPECIAL_DATA: Final[int] = 2
 DEFAULT_EXECUTION_RESULT: Final[tuple[Any, Optional[int], Any]] = (None, None, None)
 
 
 @trait
 class CommonDriverAttributesMixin:
-    """Common attributes and methods for driver adapters.
-
-    This mixin provides the foundation for all SQLSpec drivers, including
-    connection and configuration management, parameter processing, caching,
-    and SQL compilation.
-    """
+    """Common attributes and methods for driver adapters."""
 
     __slots__ = ("connection", "driver_features", "statement_config")
     connection: "Any"
@@ -180,9 +142,6 @@ class CommonDriverAttributesMixin:
     def build_statement_result(self, statement: "SQL", execution_result: ExecutionResult) -> "SQLResult":
         """Build and return the SQLResult from ExecutionResult data.
 
-        Creates SQLResult objects from ExecutionResult data without requiring
-        additional data extraction calls or script re-parsing.
-
         Args:
             statement: SQL statement that was executed
             execution_result: ExecutionResult containing all necessary data
@@ -215,51 +174,11 @@ class CommonDriverAttributesMixin:
             statement=statement,
             data=[],
             rows_affected=execution_result.rowcount_override or 0,
-            operation_type=self._determine_operation_type(statement),
+            operation_type=statement.operation_type,
             last_inserted_id=execution_result.last_inserted_id,
             metadata=execution_result.special_data or {"status_message": "OK"},
         )
 
-    def _determine_operation_type(self, statement: "Any") -> OperationType:
-        """Determine operation type from SQL statement expression.
-
-        Examines the statement's expression type to determine if it's
-        INSERT, UPDATE, DELETE, SELECT, SCRIPT, or generic EXECUTE.
-
-        Args:
-            statement: SQL statement object with expression attribute
-
-        Returns:
-            OperationType literal value
-        """
-        if statement.is_script:
-            return "SCRIPT"
-
-        try:
-            expression = statement.expression
-        except AttributeError:
-            return "EXECUTE"
-
-        if not expression:
-            return "EXECUTE"
-
-        expr_type = type(expression).__name__.upper()
-
-        if "ANONYMOUS" in expr_type and statement.is_script:
-            return "SCRIPT"
-
-        if "INSERT" in expr_type:
-            return "INSERT"
-        if "UPDATE" in expr_type:
-            return "UPDATE"
-        if "DELETE" in expr_type:
-            return "DELETE"
-        if "SELECT" in expr_type:
-            return "SELECT"
-        if "COPY" in expr_type:
-            return "COPY"
-        return "EXECUTE"
-
     def prepare_statement(
         self,
         statement: "Union[Statement, QueryBuilder]",
@@ -489,7 +408,8 @@ class CommonDriverAttributesMixin:
             if cached_result is not None:
                 return cached_result
 
-        compiled_sql, execution_parameters = statement.compile()
+        prepared_statement = self.prepare_statement(statement, statement_config=statement_config)
+        compiled_sql, execution_parameters = prepared_statement.compile()
 
         prepared_parameters = self.prepare_driver_parameters(
             execution_parameters, statement_config, is_many=statement.is_many
@@ -590,7 +510,7 @@ class CommonDriverAttributesMixin:
     def find_filter(
         filter_type: "type[FilterTypeT]",
         filters: "Sequence[StatementFilter | StatementParameters] | Sequence[StatementFilter]",
-    ) -> "FilterTypeT | None":
+    ) -> "Optional[FilterTypeT]":
         """Get the filter specified by filter type from the filters.
 
         Args:
@@ -600,9 +520,10 @@ class CommonDriverAttributesMixin:
         Returns:
             The match filter instance or None
         """
-        return next(
-            (cast("FilterTypeT | None", filter_) for filter_ in filters if isinstance(filter_, filter_type)), None
-        )
+        for filter_ in filters:
+            if isinstance(filter_, filter_type):
+                return filter_
+        return None
 
     def _create_count_query(self, original_sql: "SQL") -> "SQL":
         """Create a COUNT query from the original SQL statement.

sqlspec/driver/_sync.py

@@ -1,8 +1,4 @@
-"""Synchronous driver protocol implementation.
-
-This module provides the sync driver infrastructure for database adapters,
-including connection management, transaction support, and result processing.
-"""
+"""Synchronous driver protocol implementation."""
 
 from abc import abstractmethod
 from typing import TYPE_CHECKING, Any, Final, NoReturn, Optional, Union, cast, overload
@@ -32,22 +28,13 @@ EMPTY_FILTERS: Final["list[StatementFilter]"] = []
 
 
 class SyncDriverAdapterBase(CommonDriverAttributesMixin, SQLTranslatorMixin, ToSchemaMixin):
-    """Base class for synchronous database drivers.
-
-    Provides the foundation for sync database adapters, including connection management,
-    transaction support, and SQL execution methods. All database operations are performed
-    synchronously and support context manager patterns for proper resource cleanup.
-    """
+    """Base class for synchronous database drivers."""
 
     __slots__ = ()
 
     def dispatch_statement_execution(self, statement: "SQL", connection: "Any") -> "SQLResult":
         """Central execution dispatcher using the Template Method Pattern.
 
-        Orchestrates the common execution flow, delegating database-specific steps
-        to abstract methods that concrete adapters must implement.
-        All database operations are wrapped in exception handling.
-
         Args:
             statement: The SQL statement to execute
             connection: The database connection to use

sqlspec/driver/mixins/_result_tools.py

@@ -1,4 +1,3 @@
-# pyright: reportCallIssue=false, reportAttributeAccessIssue=false, reportArgumentType=false
 import datetime
 import logging
 from collections.abc import Sequence
@@ -28,10 +27,8 @@ __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)
 
+_DATETIME_TYPES: Final[set[type]] = {datetime.datetime, datetime.date, datetime.time}
 _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())),
@@ -44,21 +41,15 @@ _DEFAULT_TYPE_DECODERS: Final[list[tuple[Callable[[Any], bool], Callable[[Any, A
 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.
-    """
+    """Default msgspec deserializer with type conversion support."""
     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()
@@ -71,7 +62,6 @@ def _default_msgspec_deserializer(
     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):
@@ -86,7 +76,6 @@ def _default_msgspec_deserializer(
 class ToSchemaMixin:
     __slots__ = ()
 
-    # Schema conversion overloads - handle common cases first
     @overload
     @staticmethod
     def to_schema(data: "list[dict[str, Any]]") -> "list[dict[str, Any]]": ...
@@ -125,15 +114,11 @@ class ToSchemaMixin:
     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
@@ -152,30 +137,24 @@ class ToSchemaMixin:
                 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,
-            )
+            return convert(obj=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)  # pyright: ignore
-            list_adapter = get_type_adapter(list[schema_type])  # type: ignore[valid-type]  # pyright: ignore
+                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]  # pyright: ignore
+                    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)  # pyright: ignore
-                return cattrs_structure(data, schema_type)  # pyright: ignore
+                    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:

sqlspec/driver/mixins/_sql_translator.py

@@ -9,7 +9,7 @@ from sqlspec.exceptions import SQLConversionError
 
 __all__ = ("SQLTranslatorMixin",)
 
-# Constants for better performance
+
 _DEFAULT_PRETTY: Final[bool] = True
 
 
@@ -18,6 +18,7 @@ class SQLTranslatorMixin:
     """Mixin for drivers supporting SQL translation."""
 
     __slots__ = ()
+    dialect: "Optional[DialectType]"
 
     def convert_to_dialect(
         self, statement: "Statement", to_dialect: "Optional[DialectType]" = None, pretty: bool = _DEFAULT_PRETTY
@@ -35,7 +36,7 @@ class SQLTranslatorMixin:
         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):
@@ -47,19 +48,16 @@ class SQLTranslatorMixin:
         else:
             parsed_expression = self._parse_statement_safely(statement)
 
-        # Get target dialect with fallback
-        target_dialect = to_dialect or self.dialect  # type: ignore[attr-defined]
+        target_dialect = to_dialect or self.dialect
 
-        # 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]
+
+            return parse_one(sql_string, dialect=self.dialect, copy=False)
         except Exception as e:
             self._raise_parse_error(e)
 

sqlspec/exceptions.py

@@ -181,9 +181,8 @@ def wrap_exceptions(
             (isinstance(suppress, type) and isinstance(exc, suppress))
             or (isinstance(suppress, tuple) and isinstance(exc, suppress))
         ):
-            return  # Suppress this exception
+            return
 
-        # If it's already a SQLSpec exception, don't wrap it
         if isinstance(exc, SQLSpecError):
             raise
 

sqlspec/extensions/litestar/plugin.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Any, Union
+from typing import TYPE_CHECKING, Optional, Union
 
 from litestar.di import Provide
 from litestar.plugins import CLIPlugin, InitPluginProtocol
@@ -14,23 +14,31 @@ if TYPE_CHECKING:
     from click import Group
     from litestar.config.app import AppConfig
 
+    from sqlspec.loader import SQLFileLoader
+
 logger = get_logger("extensions.litestar")
 
 
-class SQLSpec(InitPluginProtocol, CLIPlugin, SQLSpecBase):
+class SQLSpec(SQLSpecBase, InitPluginProtocol, CLIPlugin):
     """Litestar plugin for SQLSpec database integration."""
 
-    __slots__ = ("_config", "_plugin_configs")
+    __slots__ = ("_plugin_configs",)
 
-    def __init__(self, config: Union["SyncConfigT", "AsyncConfigT", "DatabaseConfig", list["DatabaseConfig"]]) -> None:
+    def __init__(
+        self,
+        config: Union["SyncConfigT", "AsyncConfigT", "DatabaseConfig", list["DatabaseConfig"]],
+        *,
+        loader: "Optional[SQLFileLoader]" = None,
+    ) -> None:
         """Initialize SQLSpec plugin.
 
         Args:
             config: Database configuration for SQLSpec plugin.
+            loader: Optional SQL file loader instance.
         """
-        self._configs: dict[Any, DatabaseConfigProtocol[Any, Any, Any]] = {}
+        super().__init__(loader=loader)
         if isinstance(config, DatabaseConfigProtocol):
-            self._plugin_configs: list[DatabaseConfig] = [DatabaseConfig(config=config)]
+            self._plugin_configs: list[DatabaseConfig] = [DatabaseConfig(config=config)]  # pyright: ignore
         elif isinstance(config, DatabaseConfig):
             self._plugin_configs = [config]
         else:
@@ -83,8 +91,7 @@ class SQLSpec(InitPluginProtocol, CLIPlugin, SQLSpecBase):
             app_config.signature_types.append(c.config.connection_type)  # type: ignore[union-attr]
             app_config.signature_types.append(c.config.driver_type)  # type: ignore[union-attr]
 
-            if hasattr(c.config, "get_signature_namespace"):
-                signature_namespace.update(c.config.get_signature_namespace())  # type: ignore[attr-defined]
+            signature_namespace.update(c.config.get_signature_namespace())  # type: ignore[union-attr]
 
             app_config.before_send.append(c.before_send_handler)
             app_config.lifespan.append(c.lifespan_handler)  # pyright: ignore[reportUnknownMemberType]