sqlspec 0.17.0__py3-none-any.whl → 0.18.0__py3-none-any.whl

sqlspec/core/compiler.py

@@ -1,18 +1,9 @@
-"""SQL processor with integrated caching and compilation.
-
-This module implements the core compilation system for SQL statements with
-integrated parameter processing and caching.
+"""SQL compilation and caching.
 
 Components:
-- CompiledSQL: Immutable compilation result with complete information
-- SQLProcessor: Single-pass compiler with integrated caching
-- Integrated parameter processing via ParameterProcessor
-
-Features:
-- Single SQLGlot parse for efficient processing
-- AST-based operation type detection
-- Unified caching system with LRU eviction
-- Complete StatementConfig support
+- CompiledSQL: Immutable compilation result
+- SQLProcessor: SQL compiler with caching
+- Parameter processing via ParameterProcessor
 """
 
 import hashlib
@@ -31,7 +22,7 @@ from sqlspec.utils.logging import get_logger
 if TYPE_CHECKING:
     from sqlspec.core.statement import StatementConfig
 
-# Define OperationType here to avoid circular import
+
 OperationType = Literal[
     "SELECT",
     "INSERT",
@@ -52,35 +43,24 @@ __all__ = ("CompiledSQL", "OperationType", "SQLProcessor")
 
 logger = get_logger("sqlspec.core.compiler")
 
-_OPERATION_TYPES = {
-    "SELECT": "SELECT",
-    "INSERT": "INSERT",
-    "UPDATE": "UPDATE",
-    "DELETE": "DELETE",
-    "COPY": "COPY",
-    "COPY_FROM": "COPY_FROM",
-    "COPY_TO": "COPY_TO",
-    "EXECUTE": "EXECUTE",
-    "SCRIPT": "SCRIPT",
-    "DDL": "DDL",
-    "PRAGMA": "PRAGMA",
-    "UNKNOWN": "UNKNOWN",
+OPERATION_TYPE_MAP: "dict[type[exp.Expression], OperationType]" = {
+    exp.Select: "SELECT",
+    exp.Insert: "INSERT",
+    exp.Update: "UPDATE",
+    exp.Delete: "DELETE",
+    exp.Pragma: "PRAGMA",
+    exp.Command: "EXECUTE",
+    exp.Create: "DDL",
+    exp.Drop: "DDL",
+    exp.Alter: "DDL",
 }
 
 
-@mypyc_attr(allow_interpreted_subclasses=True)
+@mypyc_attr(allow_interpreted_subclasses=False)
 class CompiledSQL:
-    """Immutable compiled SQL result with complete information.
-
-    This class represents the result of SQL compilation, containing all
-    information needed for execution.
+    """Compiled SQL result.
 
-    Features:
-    - Immutable design for safe sharing
-    - Cached hash for efficient dictionary operations
-    - Complete operation type detection
-    - Parameter style and execution information
-    - Support for execute_many operations
+    Contains the result of SQL compilation with information needed for execution.
     """
 
     __slots__ = (
@@ -93,21 +73,23 @@ class CompiledSQL:
         "supports_many",
     )
 
+    operation_type: "OperationType"
+
     def __init__(
         self,
         compiled_sql: str,
         execution_parameters: Any,
-        operation_type: str,
+        operation_type: "OperationType",
         expression: Optional["exp.Expression"] = None,
         parameter_style: Optional[str] = None,
         supports_many: bool = False,
     ) -> None:
-        """Initialize immutable compiled result.
+        """Initialize compiled result.
 
         Args:
-            compiled_sql: Final SQL string ready for execution
+            compiled_sql: SQL string ready for execution
             execution_parameters: Parameters in driver-specific format
-            operation_type: Detected SQL operation type (SELECT, INSERT, etc.)
+            operation_type: SQL operation type (SELECT, INSERT, etc.)
             expression: SQLGlot AST expression
             parameter_style: Parameter style used in compilation
             supports_many: Whether this supports execute_many operations
@@ -121,15 +103,14 @@ class CompiledSQL:
         self._hash: Optional[int] = None
 
     def __hash__(self) -> int:
-        """Cached hash value with optimization."""
+        """Cached hash value."""
         if self._hash is None:
-            # Optimize by avoiding str() conversion if possible
             param_str = str(self.execution_parameters)
             self._hash = hash((self.compiled_sql, param_str, self.operation_type, self.parameter_style))
         return self._hash
 
     def __eq__(self, other: object) -> bool:
-        """Equality comparison for compiled results."""
+        """Equality comparison."""
         if not isinstance(other, CompiledSQL):
             return False
         return (
@@ -140,7 +121,7 @@ class CompiledSQL:
         )
 
     def __repr__(self) -> str:
-        """String representation for debugging."""
+        """String representation."""
         return (
             f"CompiledSQL(sql={self.compiled_sql!r}, "
             f"params={self.execution_parameters!r}, "
@@ -148,35 +129,21 @@ class CompiledSQL:
         )
 
 
-@mypyc_attr(allow_interpreted_subclasses=True)
+@mypyc_attr(allow_interpreted_subclasses=False)
 class SQLProcessor:
-    """SQL processor with integrated caching and compilation.
-
-    This is the core compilation engine that processes SQL statements with
-    integrated parameter processing and caching.
-
-    Processing Flow:
-    1. Parameter detection and normalization (if needed)
-    2. Single SQLGlot parse
-    3. AST-based operation type detection
-    4. Parameter conversion (if needed)
-    5. Final SQL generation with execution parameters
-
-    Features:
-    - LRU cache with O(1) operations
-    - Integrated parameter processing
-    - Cached compilation results
-    - Complete StatementConfig support
+    """SQL processor with compilation and caching.
+
+    Processes SQL statements with parameter processing and caching.
     """
 
     __slots__ = ("_cache", "_cache_hits", "_cache_misses", "_config", "_max_cache_size", "_parameter_processor")
 
     def __init__(self, config: "StatementConfig", max_cache_size: int = 1000) -> None:
-        """Initialize processor with configuration and caching.
+        """Initialize processor.
 
         Args:
-            config: Statement configuration with parameter processing settings
-            max_cache_size: Maximum number of cached compilation results
+            config: Statement configuration
+            max_cache_size: Maximum number of compilation results to cache
         """
         self._config = config
         self._cache: OrderedDict[str, CompiledSQL] = OrderedDict()
@@ -186,15 +153,15 @@ class SQLProcessor:
         self._cache_misses = 0
 
     def compile(self, sql: str, parameters: Any = None, is_many: bool = False) -> CompiledSQL:
-        """Compile SQL statement with integrated caching.
+        """Compile SQL statement.
 
         Args:
-            sql: Raw SQL string for compilation
-            parameters: Parameter values in any format
+            sql: SQL string for compilation
+            parameters: Parameter values
             is_many: Whether this is for execute_many operation
 
         Returns:
-            CompiledSQL with all information for execution
+            CompiledSQL with execution information
         """
         if not self._config.enable_caching:
             return self._compile_uncached(sql, parameters, is_many)
@@ -202,7 +169,6 @@ class SQLProcessor:
         cache_key = self._make_cache_key(sql, parameters)
 
         if cache_key in self._cache:
-            # Move to end for LRU behavior
             result = self._cache[cache_key]
             del self._cache[cache_key]
             self._cache[cache_key] = result
@@ -222,7 +188,7 @@ class SQLProcessor:
         """Compile SQL without caching.
 
         Args:
-            sql: Raw SQL string
+            sql: SQL string
             parameters: Parameter values
             is_many: Whether this is for execute_many operation
 
@@ -230,10 +196,8 @@ class SQLProcessor:
             CompiledSQL result
         """
         try:
-            # Cache dialect string to avoid repeated conversions
             dialect_str = str(self._config.dialect) if self._config.dialect else None
 
-            # Process parameters in single call
             processed_sql: str
             processed_params: Any
             processed_sql, processed_params = self._parameter_processor.process(
@@ -244,7 +208,6 @@ class SQLProcessor:
                 is_many=is_many,
             )
 
-            # Optimize static compilation path
             if self._config.parameter_config.needs_static_script_compilation and processed_params is None:
                 sqlglot_sql = processed_sql
             else:
@@ -255,15 +218,13 @@ class SQLProcessor:
             final_parameters = processed_params
             ast_was_transformed = False
             expression = None
-            operation_type = "EXECUTE"
+            operation_type: OperationType = "EXECUTE"
 
             if self._config.enable_parsing:
                 try:
-                    # Use copy=False for performance optimization
                     expression = sqlglot.parse_one(sqlglot_sql, dialect=dialect_str)
                     operation_type = self._detect_operation_type(expression)
 
-                    # Handle AST transformation if configured
                     ast_transformer = self._config.parameter_config.ast_transformer
                     if ast_transformer:
                         expression, final_parameters = ast_transformer(expression, processed_params)
@@ -273,7 +234,6 @@ class SQLProcessor:
                     expression = None
                     operation_type = "EXECUTE"
 
-            # Optimize final SQL generation path
             if self._config.parameter_config.needs_static_script_compilation and processed_params is None:
                 final_sql, final_params = processed_sql, processed_params
             elif ast_was_transformed and expression is not None:
@@ -303,12 +263,10 @@ class SQLProcessor:
 
         except Exception as e:
             logger.warning("Compilation failed, using fallback: %s", e)
-            return CompiledSQL(
-                compiled_sql=sql, execution_parameters=parameters, operation_type=_OPERATION_TYPES["UNKNOWN"]
-            )
+            return CompiledSQL(compiled_sql=sql, execution_parameters=parameters, operation_type="UNKNOWN")
 
     def _make_cache_key(self, sql: str, parameters: Any) -> str:
-        """Generate cache key for compilation result.
+        """Generate cache key.
 
         Args:
             sql: SQL string
@@ -317,12 +275,11 @@ class SQLProcessor:
         Returns:
             Cache key string
         """
-        # Optimize key generation by avoiding string conversion overhead
+
         param_repr = repr(parameters)
         dialect_str = str(self._config.dialect) if self._config.dialect else None
         param_style = self._config.parameter_config.default_parameter_style.value
 
-        # Use direct tuple construction for better performance
         hash_data = (
             sql,
             param_repr,
@@ -332,34 +289,23 @@ class SQLProcessor:
             self._config.enable_transformations,
         )
 
-        # Optimize hash computation
         hash_str = hashlib.sha256(str(hash_data).encode("utf-8")).hexdigest()[:16]
         return f"sql_{hash_str}"
 
-    def _detect_operation_type(self, expression: "exp.Expression") -> str:
+    def _detect_operation_type(self, expression: "exp.Expression") -> "OperationType":
         """Detect operation type from AST.
 
-        Uses SQLGlot AST structure to determine operation type.
-
         Args:
-            expression: SQLGlot AST expression
+            expression: AST expression
 
         Returns:
-            Operation type string
+            Operation type literal
         """
-        # Use isinstance for compatibility with mocks and inheritance
-        if isinstance(expression, exp.Select):
-            return "SELECT"
-        if isinstance(expression, exp.Insert):
-            return "INSERT"
-        if isinstance(expression, exp.Update):
-            return "UPDATE"
-        if isinstance(expression, exp.Delete):
-            return "DELETE"
-        if isinstance(expression, exp.Pragma):
-            return "PRAGMA"
-        if isinstance(expression, exp.Command):
-            return "EXECUTE"
+
+        expr_type = type(expression)
+        if expr_type in OPERATION_TYPE_MAP:
+            return OPERATION_TYPE_MAP[expr_type]  # pyright: ignore
+
         if isinstance(expression, exp.Copy):
             copy_kind = expression.args.get("kind")
             if copy_kind is True:
@@ -367,8 +313,7 @@ class SQLProcessor:
             if copy_kind is False:
                 return "COPY_TO"
             return "COPY"
-        if isinstance(expression, (exp.Create, exp.Drop, exp.Alter)):
-            return "DDL"
+
         return "UNKNOWN"
 
     def _apply_final_transformations(
@@ -377,10 +322,10 @@ class SQLProcessor:
         """Apply final transformations.
 
         Args:
-            expression: SQLGlot AST expression (if available)
-            sql: Compiled SQL string (fallback)
+            expression: SQLGlot AST expression
+            sql: SQL string
             parameters: Execution parameters
-            dialect_str: SQL dialect for AST-to-SQL conversion
+            dialect_str: SQL dialect
 
         Returns:
             Tuple of (final_sql, final_parameters)
@@ -395,7 +340,7 @@ class SQLProcessor:
         return sql, parameters
 
     def clear_cache(self) -> None:
-        """Clear compilation cache."""
+        """Clear cache."""
         self._cache.clear()
         self._cache_hits = 0
         self._cache_misses = 0
@@ -405,7 +350,7 @@ class SQLProcessor:
         """Get cache statistics.
 
         Returns:
-            Dictionary with cache hit/miss statistics
+            Dictionary with cache statistics
         """
         total_requests = self._cache_hits + self._cache_misses
         hit_rate_pct = int((self._cache_hits / total_requests) * 100) if total_requests > 0 else 0

sqlspec/core/filters.py

@@ -25,6 +25,7 @@ from collections.abc import Sequence
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Generic, Literal, Optional, Union
 
+import sqlglot
 from sqlglot import exp
 from typing_extensions import TypeAlias, TypeVar
 
@@ -160,7 +161,6 @@ class BeforeAfterFilter(StatementFilter):
         conditions: list[Condition] = []
         col_expr = exp.column(self.field_name)
 
-        # Resolve parameter name conflicts
         proposed_names = []
         if self.before and self._param_name_before:
             proposed_names.append(self._param_name_before)
@@ -238,7 +238,6 @@ class OnBeforeAfterFilter(StatementFilter):
     def append_to_statement(self, statement: "SQL") -> "SQL":
         conditions: list[Condition] = []
 
-        # Resolve parameter name conflicts
         proposed_names = []
         if self.on_or_before and self._param_name_on_or_before:
             proposed_names.append(self._param_name_on_or_before)
@@ -328,7 +327,6 @@ class InCollectionFilter(InAnyFilter[T]):
         if not self.values:
             return statement.where(exp.false())
 
-        # Resolve parameter name conflicts
         resolved_names = self._resolve_parameter_conflicts(statement, self._param_names)
 
         placeholder_expressions: list[exp.Placeholder] = [
@@ -337,7 +335,6 @@ class InCollectionFilter(InAnyFilter[T]):
 
         result = statement.where(exp.In(this=exp.column(self.field_name), expressions=placeholder_expressions))
 
-        # Add parameters with resolved names
         for resolved_name, value in zip(resolved_names, self.values):
             result = result.add_named_parameter(resolved_name, value)
         return result
@@ -383,7 +380,6 @@ class NotInCollectionFilter(InAnyFilter[T]):
         if self.values is None or not self.values:
             return statement
 
-        # Resolve parameter name conflicts
         resolved_names = self._resolve_parameter_conflicts(statement, self._param_names)
 
         placeholder_expressions: list[exp.Placeholder] = [
@@ -394,7 +390,6 @@ class NotInCollectionFilter(InAnyFilter[T]):
             exp.Not(this=exp.In(this=exp.column(self.field_name), expressions=placeholder_expressions))
         )
 
-        # Add parameters with resolved names
         for resolved_name, value in zip(resolved_names, self.values):
             result = result.add_named_parameter(resolved_name, value)
         return result
@@ -445,7 +440,6 @@ class AnyCollectionFilter(InAnyFilter[T]):
         if not self.values:
             return statement.where(exp.false())
 
-        # Resolve parameter name conflicts
         resolved_names = self._resolve_parameter_conflicts(statement, self._param_names)
 
         placeholder_expressions: list[exp.Expression] = [
@@ -455,7 +449,6 @@ class AnyCollectionFilter(InAnyFilter[T]):
         array_expr = exp.Array(expressions=placeholder_expressions)
         result = statement.where(exp.EQ(this=exp.column(self.field_name), expression=exp.Any(this=array_expr)))
 
-        # Add parameters with resolved names
         for resolved_name, value in zip(resolved_names, self.values):
             result = result.add_named_parameter(resolved_name, value)
         return result
@@ -500,7 +493,6 @@ class NotAnyCollectionFilter(InAnyFilter[T]):
         if self.values is None or not self.values:
             return statement
 
-        # Resolve parameter name conflicts
         resolved_names = self._resolve_parameter_conflicts(statement, self._param_names)
 
         placeholder_expressions: list[exp.Expression] = [
@@ -511,7 +503,6 @@ class NotAnyCollectionFilter(InAnyFilter[T]):
         condition = exp.EQ(this=exp.column(self.field_name), expression=exp.Any(this=array_expr))
         result = statement.where(exp.Not(this=condition))
 
-        # Add parameters with resolved names
         for resolved_name, value in zip(resolved_names, self.values):
             result = result.add_named_parameter(resolved_name, value)
         return result
@@ -558,27 +549,20 @@ class LimitOffsetFilter(PaginationFilter):
         return [], {self._limit_param_name: self.limit, self._offset_param_name: self.offset}
 
     def append_to_statement(self, statement: "SQL") -> "SQL":
-        import sqlglot
-        from sqlglot import exp
-
-        # Resolve parameter name conflicts
         resolved_names = self._resolve_parameter_conflicts(statement, [self._limit_param_name, self._offset_param_name])
         limit_param_name, offset_param_name = resolved_names
 
         limit_placeholder = exp.Placeholder(this=limit_param_name)
         offset_placeholder = exp.Placeholder(this=offset_param_name)
 
-        # Parse the current SQL to get the statement structure
         try:
             current_statement = sqlglot.parse_one(statement._raw_sql, dialect=getattr(statement, "_dialect", None))
         except Exception:
-            # Fallback to wrapping in subquery if parsing fails
             current_statement = exp.Select().from_(f"({statement._raw_sql})")
 
         if isinstance(current_statement, exp.Select):
             new_statement = current_statement.limit(limit_placeholder).offset(offset_placeholder)
         else:
-            # Wrap non-SELECT statements in a subquery
             new_statement = exp.Select().from_(current_statement).limit(limit_placeholder).offset(offset_placeholder)
 
         result = statement.copy(statement=new_statement)
@@ -678,7 +662,6 @@ class SearchFilter(StatementFilter):
         if not self.value or not self._param_name:
             return statement
 
-        # Resolve parameter name conflicts
         resolved_names = self._resolve_parameter_conflicts(statement, [self._param_name])
         param_name = resolved_names[0]
 
@@ -701,7 +684,6 @@ class SearchFilter(StatementFilter):
         else:
             result = statement
 
-        # Add parameter with resolved name
         search_value_with_wildcards = f"%{self.value}%"
         return result.add_named_parameter(param_name, search_value_with_wildcards)
 
@@ -745,7 +727,6 @@ class NotInSearchFilter(SearchFilter):
         if not self.value or not self._param_name:
             return statement
 
-        # Resolve parameter name conflicts
         resolved_names = self._resolve_parameter_conflicts(statement, [self._param_name])
         param_name = resolved_names[0]
 
@@ -768,7 +749,6 @@ class NotInSearchFilter(SearchFilter):
                     final_condition = exp.And(this=final_condition, expression=cond)
             result = statement.where(final_condition)
 
-        # Add parameter with resolved name
         search_value_with_wildcards = f"%{self.value}%"
         return result.add_named_parameter(param_name, search_value_with_wildcards)