sqlspec 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

sqlspec/core/__init__.py

@@ -1,9 +1,9 @@
-"""SQLSpec Core Module - High-Performance SQL Processing System.
+"""SQLSpec Core Module - SQL Processing System.
 
 This module provides the core SQL processing infrastructure for SQLSpec, implementing
 a complete pipeline for SQL statement compilation, parameter processing, caching,
-and result management. All components are optimized for MyPyC compilation and
-designed for maximum performance with minimal overhead.
+and result management. All components are optimized for MyPyC compilation to
+reduce overhead.
 
 Architecture Overview:
     The core module implements a single-pass processing pipeline where SQL statements
@@ -90,7 +90,7 @@ Example Usage:
 """
 
 from sqlspec.core import filters
-from sqlspec.core.cache import CacheConfig, CacheStats, MultiLevelCache, UnifiedCache, get_cache
+from sqlspec.core.cache import CacheConfig, CacheStats, MultiLevelCache, UnifiedCache, get_cache, get_cache_config
 from sqlspec.core.compiler import OperationType, SQLProcessor
 from sqlspec.core.filters import StatementFilter
 from sqlspec.core.hashing import (
@@ -131,6 +131,7 @@ __all__ = (
     "UnifiedCache",
     "filters",
     "get_cache",
+    "get_cache_config",
     "hash_expression",
     "hash_expression_node",
     "hash_optimized_expression",

sqlspec/core/cache.py

@@ -14,7 +14,7 @@ Components:
 import threading
 import time
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Final, Optional, Union
+from typing import TYPE_CHECKING, Any, Final, Optional
 
 from mypy_extensions import mypyc_attr
 from typing_extensions import TypeVar
@@ -173,8 +173,8 @@ class CacheNode:
         """
         self.key = key
         self.value = value
-        self.prev: Optional[CacheNode] = None
-        self.next: Optional[CacheNode] = None
+        self.prev: CacheNode | None = None
+        self.next: CacheNode | None = None
         self.timestamp = time.time()
         self.access_count = 1
 
@@ -190,7 +190,7 @@ class UnifiedCache:
 
     __slots__ = UNIFIED_CACHE_SLOTS
 
-    def __init__(self, max_size: int = DEFAULT_MAX_SIZE, ttl_seconds: Optional[int] = DEFAULT_TTL_SECONDS) -> None:
+    def __init__(self, max_size: int = DEFAULT_MAX_SIZE, ttl_seconds: int | None = DEFAULT_TTL_SECONDS) -> None:
         """Initialize unified cache.
 
         Args:
@@ -208,7 +208,7 @@ class UnifiedCache:
         self._head.next = self._tail
         self._tail.prev = self._head
 
-    def get(self, key: CacheKey) -> Optional[Any]:
+    def get(self, key: CacheKey) -> Any | None:
         """Get value from cache.
 
         Args:
@@ -275,7 +275,7 @@ class UnifiedCache:
             True if key was found and deleted, False otherwise
         """
         with self._lock:
-            node: Optional[CacheNode] = self._cache.get(key)
+            node: CacheNode | None = self._cache.get(key)
             if node is None:
                 return False
 
@@ -306,7 +306,7 @@ class UnifiedCache:
     def _add_to_head(self, node: CacheNode) -> None:
         """Add node to head of list."""
         node.prev = self._head
-        head_next: Optional[CacheNode] = self._head.next
+        head_next: CacheNode | None = self._head.next
         node.next = head_next
         if head_next is not None:
             head_next.prev = node
@@ -314,8 +314,8 @@ class UnifiedCache:
 
     def _remove_node(self, node: CacheNode) -> None:
         """Remove node from linked list."""
-        node_prev: Optional[CacheNode] = node.prev
-        node_next: Optional[CacheNode] = node.next
+        node_prev: CacheNode | None = node.prev
+        node_next: CacheNode | None = node.next
         if node_prev is not None:
             node_prev.next = node_next
         if node_next is not None:
@@ -341,7 +341,7 @@ class UnifiedCache:
             return not (ttl is not None and time.time() - node.timestamp > ttl)
 
 
-_default_cache: Optional[UnifiedCache] = None
+_default_cache: UnifiedCache | None = None
 _cache_lock = threading.Lock()
 
 
@@ -381,7 +381,7 @@ def get_cache_statistics() -> dict[str, CacheStats]:
     return stats
 
 
-_global_cache_config: "Optional[CacheConfig]" = None
+_global_cache_config: "CacheConfig | None" = None
 
 
 @mypyc_attr(allow_interpreted_subclasses=False)
@@ -558,7 +558,7 @@ class CachedStatement:
     """
 
     compiled_sql: str
-    parameters: Optional[Union[tuple[Any, ...], dict[str, Any]]]  # None allowed for static script compilation
+    parameters: tuple[Any, ...] | dict[str, Any] | None  # None allowed for static script compilation
     expression: Optional["exp.Expression"]
 
     def get_parameters_view(self) -> "ParametersView":
@@ -572,7 +572,7 @@ class CachedStatement:
         return ParametersView(list(self.parameters), {})
 
 
-def create_cache_key(level: str, key: str, dialect: Optional[str] = None) -> str:
+def create_cache_key(level: str, key: str, dialect: str | None = None) -> str:
     """Create optimized cache key using string concatenation.
 
     Args:
@@ -592,7 +592,7 @@ class MultiLevelCache:
 
     __slots__ = ("_cache",)
 
-    def __init__(self, max_size: int = DEFAULT_MAX_SIZE, ttl_seconds: Optional[int] = DEFAULT_TTL_SECONDS) -> None:
+    def __init__(self, max_size: int = DEFAULT_MAX_SIZE, ttl_seconds: int | None = DEFAULT_TTL_SECONDS) -> None:
         """Initialize multi-level cache.
 
         Args:
@@ -601,7 +601,7 @@ class MultiLevelCache:
         """
         self._cache = UnifiedCache(max_size, ttl_seconds)
 
-    def get(self, level: str, key: str, dialect: Optional[str] = None) -> Optional[Any]:
+    def get(self, level: str, key: str, dialect: str | None = None) -> Any | None:
         """Get value from cache with level and dialect namespace.
 
         Args:
@@ -616,7 +616,7 @@ class MultiLevelCache:
         cache_key = CacheKey((full_key,))
         return self._cache.get(cache_key)
 
-    def put(self, level: str, key: str, value: Any, dialect: Optional[str] = None) -> None:
+    def put(self, level: str, key: str, value: Any, dialect: str | None = None) -> None:
         """Put value in cache with level and dialect namespace.
 
         Args:
@@ -629,7 +629,7 @@ class MultiLevelCache:
         cache_key = CacheKey((full_key,))
         self._cache.put(cache_key, value)
 
-    def delete(self, level: str, key: str, dialect: Optional[str] = None) -> bool:
+    def delete(self, level: str, key: str, dialect: str | None = None) -> bool:
         """Delete entry from cache.
 
         Args:
@@ -653,7 +653,7 @@ class MultiLevelCache:
         return self._cache.get_stats()
 
 
-_multi_level_cache: Optional[MultiLevelCache] = None
+_multi_level_cache: MultiLevelCache | None = None
 
 
 def get_cache() -> MultiLevelCache:

sqlspec/core/compiler.py

@@ -8,16 +8,15 @@ Components:
 
 import hashlib
 from collections import OrderedDict
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any, Literal, Optional
 
 import sqlglot
 from mypy_extensions import mypyc_attr
 from sqlglot import expressions as exp
 from sqlglot.errors import ParseError
-from typing_extensions import Literal
 
+import sqlspec.exceptions
 from sqlspec.core.parameters import ParameterProcessor
-from sqlspec.exceptions import SQLSpecError
 from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
@@ -85,7 +84,7 @@ class CompiledSQL:
         execution_parameters: Any,
         operation_type: "OperationType",
         expression: Optional["exp.Expression"] = None,
-        parameter_style: Optional[str] = None,
+        parameter_style: str | None = None,
         supports_many: bool = False,
         parameter_casts: Optional["dict[int, str]"] = None,
     ) -> None:
@@ -107,7 +106,7 @@ class CompiledSQL:
         self.parameter_style = parameter_style
         self.supports_many = supports_many
         self.parameter_casts = parameter_casts or {}
-        self._hash: Optional[int] = None
+        self._hash: int | None = None
 
     def __hash__(self) -> int:
         """Cached hash value."""
@@ -274,8 +273,7 @@ class SQLProcessor:
                 parameter_casts=parameter_casts,
             )
 
-        except SQLSpecError:
-            # Re-raise SQLSpecError (validation errors, parameter mismatches) - these should fail hard
+        except sqlspec.exceptions.SQLSpecError:
             raise
         except Exception as e:
             logger.warning("Compilation failed, using fallback: %s", e)
@@ -382,7 +380,7 @@ class SQLProcessor:
         return cast_positions
 
     def _apply_final_transformations(
-        self, expression: "Optional[exp.Expression]", sql: str, parameters: Any, dialect_str: "Optional[str]"
+        self, expression: "exp.Expression | None", sql: str, parameters: Any, dialect_str: "str | None"
     ) -> "tuple[str, Any]":
         """Apply final transformations.
 

sqlspec/core/filters.py

@@ -23,11 +23,11 @@ from abc import ABC, abstractmethod
 from collections import abc
 from collections.abc import Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Generic, Literal, Optional, Union
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeAlias
 
 import sqlglot
 from sqlglot import exp
-from typing_extensions import TypeAlias, TypeVar
+from typing_extensions import TypeVar
 
 if TYPE_CHECKING:
     from sqlglot.expressions import Condition
@@ -125,7 +125,7 @@ class BeforeAfterFilter(StatementFilter):
 
     __slots__ = ("_after", "_before", "_field_name")
 
-    def __init__(self, field_name: str, before: Optional[datetime] = None, after: Optional[datetime] = None) -> None:
+    def __init__(self, field_name: str, before: datetime | None = None, after: datetime | None = None) -> None:
         self._field_name = field_name
         self._before = before
         self._after = after
@@ -135,11 +135,11 @@ class BeforeAfterFilter(StatementFilter):
         return self._field_name
 
     @property
-    def before(self) -> Optional[datetime]:
+    def before(self) -> datetime | None:
         return self._before
 
     @property
-    def after(self) -> Optional[datetime]:
+    def after(self) -> datetime | None:
         return self._after
 
     def get_param_names(self) -> list[str]:
@@ -206,7 +206,7 @@ class OnBeforeAfterFilter(StatementFilter):
     __slots__ = ("_field_name", "_on_or_after", "_on_or_before")
 
     def __init__(
-        self, field_name: str, on_or_before: Optional[datetime] = None, on_or_after: Optional[datetime] = None
+        self, field_name: str, on_or_before: datetime | None = None, on_or_after: datetime | None = None
     ) -> None:
         self._field_name = field_name
         self._on_or_before = on_or_before
@@ -217,11 +217,11 @@ class OnBeforeAfterFilter(StatementFilter):
         return self._field_name
 
     @property
-    def on_or_before(self) -> Optional[datetime]:
+    def on_or_before(self) -> datetime | None:
         return self._on_or_before
 
     @property
-    def on_or_after(self) -> Optional[datetime]:
+    def on_or_after(self) -> datetime | None:
         return self._on_or_after
 
     def get_param_names(self) -> list[str]:
@@ -298,7 +298,7 @@ class InCollectionFilter(InAnyFilter[T]):
 
     __slots__ = ("_field_name", "_values")
 
-    def __init__(self, field_name: str, values: Optional[abc.Collection[T]] = None) -> None:
+    def __init__(self, field_name: str, values: abc.Collection[T] | None = None) -> None:
         self._field_name = field_name
         self._values = values
 
@@ -307,7 +307,7 @@ class InCollectionFilter(InAnyFilter[T]):
         return self._field_name
 
     @property
-    def values(self) -> Optional[abc.Collection[T]]:
+    def values(self) -> abc.Collection[T] | None:
         return self._values
 
     def get_param_names(self) -> list[str]:
@@ -340,7 +340,7 @@ class InCollectionFilter(InAnyFilter[T]):
 
         result = statement.where(exp.In(this=exp.column(self.field_name), expressions=placeholder_expressions))
 
-        for resolved_name, value in zip(resolved_names, self.values):
+        for resolved_name, value in zip(resolved_names, self.values, strict=False):
             result = result.add_named_parameter(resolved_name, value)
         return result
 
@@ -358,7 +358,7 @@ class NotInCollectionFilter(InAnyFilter[T]):
 
     __slots__ = ("_field_name", "_values")
 
-    def __init__(self, field_name: str, values: Optional[abc.Collection[T]] = None) -> None:
+    def __init__(self, field_name: str, values: abc.Collection[T] | None = None) -> None:
         self._field_name = field_name
         self._values = values
 
@@ -367,7 +367,7 @@ class NotInCollectionFilter(InAnyFilter[T]):
         return self._field_name
 
     @property
-    def values(self) -> Optional[abc.Collection[T]]:
+    def values(self) -> abc.Collection[T] | None:
         return self._values
 
     def get_param_names(self) -> list[str]:
@@ -400,7 +400,7 @@ class NotInCollectionFilter(InAnyFilter[T]):
             exp.Not(this=exp.In(this=exp.column(self.field_name), expressions=placeholder_expressions))
         )
 
-        for resolved_name, value in zip(resolved_names, self.values):
+        for resolved_name, value in zip(resolved_names, self.values, strict=False):
             result = result.add_named_parameter(resolved_name, value)
         return result
 
@@ -418,7 +418,7 @@ class AnyCollectionFilter(InAnyFilter[T]):
 
     __slots__ = ("_field_name", "_values")
 
-    def __init__(self, field_name: str, values: Optional[abc.Collection[T]] = None) -> None:
+    def __init__(self, field_name: str, values: abc.Collection[T] | None = None) -> None:
         self._field_name = field_name
         self._values = values
 
@@ -427,7 +427,7 @@ class AnyCollectionFilter(InAnyFilter[T]):
         return self._field_name
 
     @property
-    def values(self) -> Optional[abc.Collection[T]]:
+    def values(self) -> abc.Collection[T] | None:
         return self._values
 
     def get_param_names(self) -> list[str]:
@@ -461,7 +461,7 @@ 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)))
 
-        for resolved_name, value in zip(resolved_names, self.values):
+        for resolved_name, value in zip(resolved_names, self.values, strict=False):
             result = result.add_named_parameter(resolved_name, value)
         return result
 
@@ -479,7 +479,7 @@ class NotAnyCollectionFilter(InAnyFilter[T]):
 
     __slots__ = ("_field_name", "_values")
 
-    def __init__(self, field_name: str, values: Optional[abc.Collection[T]] = None) -> None:
+    def __init__(self, field_name: str, values: abc.Collection[T] | None = None) -> None:
         self._field_name = field_name
         self._values = values
 
@@ -488,7 +488,7 @@ class NotAnyCollectionFilter(InAnyFilter[T]):
         return self._field_name
 
     @property
-    def values(self) -> Optional[abc.Collection[T]]:
+    def values(self) -> abc.Collection[T] | None:
         return self._values
 
     def get_param_names(self) -> list[str]:
@@ -520,7 +520,7 @@ 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))
 
-        for resolved_name, value in zip(resolved_names, self.values):
+        for resolved_name, value in zip(resolved_names, self.values, strict=False):
             result = result.add_named_parameter(resolved_name, value)
         return result
 
@@ -576,10 +576,13 @@ class LimitOffsetFilter(PaginationFilter):
         limit_placeholder = exp.Placeholder(this=limit_param_name)
         offset_placeholder = exp.Placeholder(this=offset_param_name)
 
-        try:
-            current_statement = sqlglot.parse_one(statement.raw_sql, dialect=statement.dialect)
-        except Exception:
-            current_statement = exp.Select().from_(f"({statement.raw_sql})")
+        if statement.statement_expression is not None:
+            current_statement = statement.statement_expression
+        else:
+            try:
+                current_statement = sqlglot.parse_one(statement.raw_sql, dialect=statement.dialect)
+            except Exception:
+                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)
@@ -587,7 +590,6 @@ class LimitOffsetFilter(PaginationFilter):
             new_statement = exp.Select().from_(current_statement).limit(limit_placeholder).offset(offset_placeholder)
 
         result = statement.copy(statement=new_statement)
-
         result = result.add_named_parameter(limit_param_name, self.limit)
         return result.add_named_parameter(offset_param_name, self.offset)
 
@@ -628,12 +630,18 @@ class OrderByFilter(StatementFilter):
         col_expr = exp.column(self.field_name)
         order_expr = col_expr.desc() if converted_sort_order == "desc" else col_expr.asc()
 
-        if statement.statement_expression is None:
-            new_statement = exp.Select().order_by(order_expr)
-        elif isinstance(statement.statement_expression, exp.Select):
-            new_statement = statement.statement_expression.order_by(order_expr)
+        if statement.statement_expression is not None:
+            current_statement = statement.statement_expression
+        else:
+            try:
+                current_statement = sqlglot.parse_one(statement.raw_sql, dialect=statement.dialect)
+            except Exception:
+                current_statement = exp.Select().from_(f"({statement.raw_sql})")
+
+        if isinstance(current_statement, exp.Select):
+            new_statement = current_statement.order_by(order_expr)
         else:
-            new_statement = exp.Select().from_(statement.statement_expression).order_by(order_expr)
+            new_statement = exp.Select().from_(current_statement).order_by(order_expr)
 
         return statement.copy(statement=new_statement)
 
@@ -650,13 +658,13 @@ class SearchFilter(StatementFilter):
 
     __slots__ = ("_field_name", "_ignore_case", "_value")
 
-    def __init__(self, field_name: Union[str, set[str]], value: str, ignore_case: Optional[bool] = False) -> None:
+    def __init__(self, field_name: str | set[str], value: str, ignore_case: bool | None = False) -> None:
         self._field_name = field_name
         self._value = value
         self._ignore_case = ignore_case
 
     @property
-    def field_name(self) -> Union[str, set[str]]:
+    def field_name(self) -> str | set[str]:
         return self._field_name
 
     @property
@@ -664,10 +672,10 @@ class SearchFilter(StatementFilter):
         return self._value
 
     @property
-    def ignore_case(self) -> Optional[bool]:
+    def ignore_case(self) -> bool | None:
         return self._ignore_case
 
-    def get_param_name(self) -> Optional[str]:
+    def get_param_name(self) -> str | None:
         """Get parameter name without storing it."""
         if not self.value:
             return None
@@ -726,7 +734,7 @@ class NotInSearchFilter(SearchFilter):
     Constructs WHERE field_name NOT LIKE '%value%' clauses.
     """
 
-    def get_param_name(self) -> Optional[str]:
+    def get_param_name(self) -> str | None:
         """Get parameter name without storing it."""
         if not self.value:
             return None
@@ -817,18 +825,18 @@ def apply_filter(statement: "SQL", filter_obj: StatementFilter) -> "SQL":
     return filter_obj.append_to_statement(statement)
 
 
-FilterTypes: TypeAlias = Union[
-    BeforeAfterFilter,
-    OnBeforeAfterFilter,
-    InCollectionFilter[Any],
-    LimitOffsetFilter,
-    OrderByFilter,
-    SearchFilter,
-    NotInCollectionFilter[Any],
-    NotInSearchFilter,
-    AnyCollectionFilter[Any],
-    NotAnyCollectionFilter[Any],
-]
+FilterTypes: TypeAlias = (
+    BeforeAfterFilter
+    | OnBeforeAfterFilter
+    | InCollectionFilter[Any]
+    | LimitOffsetFilter
+    | OrderByFilter
+    | SearchFilter
+    | NotInCollectionFilter[Any]
+    | NotInSearchFilter
+    | AnyCollectionFilter[Any]
+    | NotAnyCollectionFilter[Any]
+)
 
 
 def create_filters(filters: "list[StatementFilter]") -> tuple["StatementFilter", ...]:

sqlspec/core/hashing.py

@@ -4,7 +4,7 @@ Provides hashing functions for SQL statements, expressions, parameters,
 filters, and AST sub-expressions.
 """
 
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any
 
 from sqlglot import exp
 
@@ -23,7 +23,7 @@ __all__ = (
 )
 
 
-def hash_expression(expr: Optional[exp.Expression], _seen: Optional[set[int]] = None) -> int:
+def hash_expression(expr: exp.Expression | None, _seen: set[int] | None = None) -> int:
     """Generate hash from AST structure.
 
     Args:
@@ -77,9 +77,9 @@ def _hash_value(value: Any, _seen: set[int]) -> int:
 
 
 def hash_parameters(
-    positional_parameters: Optional[list[Any]] = None,
-    named_parameters: Optional[dict[str, Any]] = None,
-    original_parameters: Optional[Any] = None,
+    positional_parameters: list[Any] | None = None,
+    named_parameters: dict[str, Any] | None = None,
+    original_parameters: Any | None = None,
 ) -> int:
     """Generate hash for SQL parameters.
 
@@ -148,7 +148,7 @@ def _hash_filter_value(value: Any) -> int:
         return hash(repr(value))
 
 
-def hash_filters(filters: Optional[list["StatementFilter"]] = None) -> int:
+def hash_filters(filters: list["StatementFilter"] | None = None) -> int:
     """Generate hash for statement filters.
 
     Args:
@@ -208,7 +208,7 @@ def hash_sql_statement(statement: "SQL") -> str:
     return f"sql:{hash(tuple(state_components))}"
 
 
-def hash_expression_node(node: exp.Expression, include_children: bool = True, dialect: Optional[str] = None) -> str:
+def hash_expression_node(node: exp.Expression, include_children: bool = True, dialect: str | None = None) -> str:
     """Generate cache key for an expression node.
 
     Args:
@@ -235,8 +235,8 @@ def hash_expression_node(node: exp.Expression, include_children: bool = True, di
 def hash_optimized_expression(
     expr: exp.Expression,
     dialect: str,
-    schema: Optional[dict[str, Any]] = None,
-    optimizer_settings: Optional[dict[str, Any]] = None,
+    schema: dict[str, Any] | None = None,
+    optimizer_settings: dict[str, Any] | None = None,
 ) -> str:
     """Generate cache key for optimized expressions.