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

sqlspec/statement/filters.py

@@ -2,6 +2,7 @@
 
 from abc import ABC, abstractmethod
 from collections import abc
+from collections.abc import Sequence
 from dataclasses import dataclass
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Generic, Literal, Optional, Protocol, Union, runtime_checkable
@@ -25,6 +26,7 @@ __all__ = (
     "NotAnyCollectionFilter",
     "NotInCollectionFilter",
     "NotInSearchFilter",
+    "OffsetPagination",
     "OnBeforeAfterFilter",
     "OrderByFilter",
     "PaginationFilter",
@@ -430,8 +432,7 @@ class LimitOffsetFilter(PaginationFilter):
         _, named_params = self.extract_parameters()
         for name, value in named_params.items():
             result = result.add_named_parameter(name, value)
-
-        return result
+        return result.filter(self)
 
 
 @dataclass
@@ -449,12 +450,21 @@ class OrderByFilter(StatementFilter):
         return [], {}
 
     def append_to_statement(self, statement: "SQL") -> "SQL":
-        normalized_sort_order = self.sort_order.lower()
-        if normalized_sort_order not in {"asc", "desc"}:
-            normalized_sort_order = "asc"
-        if normalized_sort_order == "desc":
-            return statement.order_by(exp.column(self.field_name).desc())
-        return statement.order_by(exp.column(self.field_name).asc())
+        converted_sort_order = self.sort_order.lower()
+        if converted_sort_order not in {"asc", "desc"}:
+            converted_sort_order = "asc"
+
+        col_expr = exp.column(self.field_name)
+        order_expr = col_expr.desc() if converted_sort_order == "desc" else col_expr.asc()
+
+        # Check if the statement supports ORDER BY directly
+        if isinstance(statement._statement, exp.Select):
+            new_statement = statement._statement.order_by(order_expr)
+        else:
+            # Wrap in a SELECT if the statement doesn't support ORDER BY directly
+            new_statement = exp.Select().from_(statement._statement).order_by(order_expr)
+
+        return statement.copy(statement=new_statement)
 
 
 @dataclass
@@ -568,6 +578,25 @@ class NotInSearchFilter(SearchFilter):
         return result
 
 
+@dataclass
+class OffsetPagination(Generic[T]):
+    """Container for data returned using limit/offset pagination."""
+
+    __slots__ = ("items", "limit", "offset", "total")
+
+    items: Sequence[T]
+    """List of data being sent as part of the response."""
+    limit: int
+    """Maximal number of items to send."""
+    offset: int
+    """Offset from the beginning of the query.
+
+    Identical to an index.
+    """
+    total: int
+    """Total number of items."""
+
+
 def apply_filter(statement: "SQL", filter_obj: StatementFilter) -> "SQL":
     """Apply a statement filter to a SQL query object.
 

sqlspec/statement/parameters.py

@@ -20,12 +20,15 @@ from sqlspec.typing import SQLParameterType
 if TYPE_CHECKING:
     from sqlglot import exp
 
+# Constants
+MAX_32BIT_INT: Final[int] = 2147483647
+
 __all__ = (
     "ConvertedParameters",
     "ParameterConverter",
     "ParameterInfo",
-    "ParameterNormalizationState",
     "ParameterStyle",
+    "ParameterStyleTransformationState",
     "ParameterValidator",
     "SQLParameterType",
     "TypedParameter",
@@ -140,40 +143,56 @@ class TypedParameter:
     semantic_name: "Optional[str]" = None
     """Optional semantic name derived from SQL context (e.g., 'user_id', 'email')."""
 
+    def __hash__(self) -> int:
+        """Make TypedParameter hashable for use in cache keys.
+
+        We hash based on the value and type_hint, which are the key attributes
+        that affect SQL compilation and parameter handling.
+        """
+        if isinstance(self.value, (list, dict)):
+            value_hash = hash(repr(self.value))
+        else:
+            try:
+                value_hash = hash(self.value)
+            except TypeError:
+                value_hash = hash(repr(self.value))
+
+        return hash((value_hash, self.type_hint, self.semantic_name))
 
-class NormalizationInfo(TypedDict, total=False):
-    """Information about SQL parameter normalization."""
 
-    was_normalized: bool
+class ParameterStyleInfo(TypedDict, total=False):
+    """Information about SQL parameter style transformation."""
+
+    was_converted: bool
     placeholder_map: dict[str, Union[str, int]]
     original_styles: list[ParameterStyle]
 
 
 @dataclass
-class ParameterNormalizationState:
-    """Encapsulates all information about parameter normalization.
+class ParameterStyleTransformationState:
+    """Encapsulates all information about parameter style transformation.
 
     This class provides a single source of truth for parameter style conversions,
-    making it easier to track and reverse normalizations applied for SQLGlot compatibility.
+    making it easier to track and reverse transformations applied for SQLGlot compatibility.
     """
 
-    was_normalized: bool = False
-    """Whether parameter normalization was applied."""
+    was_transformed: bool = False
+    """Whether parameter transformation was applied."""
 
     original_styles: list[ParameterStyle] = field(default_factory=list)
     """Original parameter style(s) detected in the SQL."""
 
-    normalized_style: Optional[ParameterStyle] = None
-    """Target style used for normalization (if normalized)."""
+    transformation_style: Optional[ParameterStyle] = None
+    """Target style used for transformation (if transformed)."""
 
     placeholder_map: dict[str, Union[str, int]] = field(default_factory=dict)
-    """Mapping from normalized names to original names/positions."""
+    """Mapping from transformed names to original names/positions."""
 
     reverse_map: dict[Union[str, int], str] = field(default_factory=dict)
     """Reverse mapping for quick lookups."""
 
     original_param_info: list["ParameterInfo"] = field(default_factory=list)
-    """Original parameter info before normalization."""
+    """Original parameter info before conversion."""
 
     def __post_init__(self) -> None:
         """Build reverse map if not provided."""
@@ -194,8 +213,8 @@ class ConvertedParameters:
     merged_parameters: "SQLParameterType"
     """Parameters after merging from various sources."""
 
-    normalization_state: ParameterNormalizationState
-    """Complete normalization state for tracking conversions."""
+    conversion_state: ParameterStyleTransformationState
+    """Complete conversion state for tracking conversions."""
 
 
 @dataclass
@@ -673,7 +692,7 @@ class ParameterConverter:
         """
         parameters_info = self.validator.extract_parameters(sql)
 
-        needs_normalization = any(p.style in SQLGLOT_INCOMPATIBLE_STYLES for p in parameters_info)
+        needs_conversion = any(p.style in SQLGLOT_INCOMPATIBLE_STYLES for p in parameters_info)
 
         has_positional = any(p.name is None for p in parameters_info)
         has_named = any(p.name is not None for p in parameters_info)
@@ -686,19 +705,19 @@ class ParameterConverter:
 
         if validate:
             self.validator.validate_parameters(parameters_info, merged_params, sql)
-        if needs_normalization:
+        if needs_conversion:
             transformed_sql, placeholder_map = self._transform_sql_for_parsing(sql, parameters_info)
-            normalization_state = ParameterNormalizationState(
-                was_normalized=True,
+            conversion_state = ParameterStyleTransformationState(
+                was_transformed=True,
                 original_styles=list({p.style for p in parameters_info}),
-                normalized_style=ParameterStyle.NAMED_COLON,
+                transformation_style=ParameterStyle.NAMED_COLON,
                 placeholder_map=placeholder_map,
                 original_param_info=parameters_info,
             )
         else:
             transformed_sql = sql
-            normalization_state = ParameterNormalizationState(
-                was_normalized=False,
+            conversion_state = ParameterStyleTransformationState(
+                was_transformed=False,
                 original_styles=list({p.style for p in parameters_info}),
                 original_param_info=parameters_info,
             )
@@ -707,7 +726,7 @@ class ParameterConverter:
             transformed_sql=transformed_sql,
             parameter_info=parameters_info,
             merged_parameters=merged_params,
-            normalization_state=normalization_state,
+            conversion_state=conversion_state,
         )
 
     @staticmethod
@@ -781,7 +800,117 @@ class ParameterConverter:
         Returns:
             Parameters with TypedParameter wrapping where appropriate
         """
-        return None if parameters is None else parameters
+        if parameters is None:
+            return None
+
+        # Import here to avoid circular imports
+        from datetime import date, datetime, time
+        from decimal import Decimal
+
+        def infer_type_from_value(value: Any) -> tuple[str, "exp.DataType"]:
+            """Infer SQL type hint and SQLGlot DataType from Python value."""
+            # Import here to avoid issues
+            from sqlglot import exp
+
+            # None/NULL
+            if value is None:
+                return "null", exp.DataType.build("NULL")
+
+            # Boolean
+            if isinstance(value, bool):
+                return "boolean", exp.DataType.build("BOOLEAN")
+
+            # Integer types
+            if isinstance(value, int) and not isinstance(value, bool):
+                if abs(value) > MAX_32BIT_INT:
+                    return "bigint", exp.DataType.build("BIGINT")
+                return "integer", exp.DataType.build("INT")
+
+            # Float/Decimal
+            if isinstance(value, float):
+                return "float", exp.DataType.build("FLOAT")
+            if isinstance(value, Decimal):
+                return "decimal", exp.DataType.build("DECIMAL")
+
+            # Date/Time types
+            if isinstance(value, datetime):
+                return "timestamp", exp.DataType.build("TIMESTAMP")
+            if isinstance(value, date):
+                return "date", exp.DataType.build("DATE")
+            if isinstance(value, time):
+                return "time", exp.DataType.build("TIME")
+
+            # JSON/Dict
+            if isinstance(value, dict):
+                return "json", exp.DataType.build("JSON")
+
+            # Array/List
+            if isinstance(value, (list, tuple)):
+                return "array", exp.DataType.build("ARRAY")
+
+            if isinstance(value, str):
+                return "string", exp.DataType.build("VARCHAR")
+
+            # Bytes
+            if isinstance(value, bytes):
+                return "binary", exp.DataType.build("BINARY")
+
+            # Default fallback
+            return "string", exp.DataType.build("VARCHAR")
+
+        def wrap_value(value: Any, semantic_name: Optional[str] = None) -> Any:
+            """Wrap a single value with TypedParameter if beneficial."""
+            # Don't wrap if already a TypedParameter
+            if hasattr(value, "__class__") and value.__class__.__name__ == "TypedParameter":
+                return value
+
+            # Don't wrap simple scalar types unless they need special handling
+            if isinstance(value, (str, int, float)) and not isinstance(value, bool):
+                # For simple types, only wrap if we have special type needs
+                # (e.g., bigint, decimal precision, etc.)
+                if isinstance(value, int) and abs(value) > MAX_32BIT_INT:
+                    # Wrap large integers as bigint
+                    type_hint, sqlglot_type = infer_type_from_value(value)
+                    return TypedParameter(
+                        value=value, sqlglot_type=sqlglot_type, type_hint=type_hint, semantic_name=semantic_name
+                    )
+                # Otherwise, return unwrapped for performance
+                return value
+
+            # Wrap complex types and types needing special handling
+            if isinstance(value, (datetime, date, time, Decimal, dict, list, tuple, bytes, bool, type(None))):
+                type_hint, sqlglot_type = infer_type_from_value(value)
+                return TypedParameter(
+                    value=value, sqlglot_type=sqlglot_type, type_hint=type_hint, semantic_name=semantic_name
+                )
+
+            # Default: return unwrapped
+            return value
+
+        # Handle different parameter structures
+        if isinstance(parameters, dict):
+            # Wrap dict values selectively
+            wrapped_dict = {}
+            for key, value in parameters.items():
+                wrapped_dict[key] = wrap_value(value, semantic_name=key)
+            return wrapped_dict
+
+        if isinstance(parameters, (list, tuple)):
+            # Wrap list/tuple values selectively
+            wrapped_list: list[Any] = []
+            for i, value in enumerate(parameters):
+                # Try to get semantic name from parameters_info if available
+                semantic_name = None
+                if parameters_info and i < len(parameters_info) and parameters_info[i].name:
+                    semantic_name = parameters_info[i].name
+                wrapped_list.append(wrap_value(value, semantic_name=semantic_name))
+            return wrapped_list if isinstance(parameters, list) else tuple(wrapped_list)
+
+        # Single scalar parameter
+        semantic_name = None
+        if parameters_info and parameters_info[0].name:
+            semantic_name = parameters_info[0].name
+        return wrap_value(parameters, semantic_name=semantic_name)
 
     def _convert_sql_placeholders(
         self, rendered_sql: str, final_parameter_info: "list[ParameterInfo]", target_style: "ParameterStyle"
@@ -816,7 +945,7 @@ class ParameterConverter:
             from sqlspec.exceptions import SQLTransformationError
 
             msg = (
-                f"Parameter count mismatch during denormalization. "
+                f"Parameter count mismatch during deconversion. "
                 f"Expected at least {len(final_parameter_info)} parameters, "
                 f"found {len(canonical_params)} in SQL"
             )

sqlspec/statement/pipelines/__init__.py

@@ -155,7 +155,7 @@ class StatementPipeline:
                     UnsupportedParameterStyleError,
                 )
 
-                if context.config.strict_mode and isinstance(
+                if not context.config.parse_errors_as_warnings and isinstance(
                     e, (MissingParameterError, MixedParameterStyleError, UnsupportedParameterStyleError)
                 ):
                     raise

sqlspec/statement/pipelines/context.py

@@ -8,7 +8,7 @@ from sqlspec.exceptions import RiskLevel
 if TYPE_CHECKING:
     from sqlglot.dialects.dialect import DialectType
 
-    from sqlspec.statement.parameters import ParameterInfo, ParameterNormalizationState
+    from sqlspec.statement.parameters import ParameterInfo, ParameterStyleTransformationState
     from sqlspec.statement.sql import SQLConfig
     from sqlspec.typing import SQLParameterType
 
@@ -97,10 +97,10 @@ class SQLProcessingContext:
     statement_type: Optional[str] = None
     """The detected type of the SQL statement (e.g., SELECT, INSERT, DDL)."""
     extra_info: dict[str, Any] = field(default_factory=dict)
-    """Extra information from parameter processing, including normalization state."""
+    """Extra information from parameter processing, including conversion state."""
 
-    parameter_normalization: "Optional[ParameterNormalizationState]" = None
-    """Single source of truth for parameter normalization tracking."""
+    parameter_conversion: "Optional[ParameterStyleTransformationState]" = None
+    """Single source of truth for parameter style conversion tracking."""
 
     @property
     def has_errors(self) -> bool:

sqlspec/statement/pipelines/transformers/_expression_simplifier.py

@@ -21,7 +21,7 @@ class SimplificationConfig:
     enable_literal_folding: bool = True
     enable_boolean_optimization: bool = True
     enable_connector_optimization: bool = True
-    enable_equality_normalization: bool = True
+    enable_equality_conversion: bool = True
     enable_complement_removal: bool = True
 
 
@@ -74,8 +74,8 @@ class ExpressionSimplifier(ProcessorProtocol):
                 optimizations.append("boolean_optimization")
             if self.config.enable_connector_optimization:
                 optimizations.append("connector_optimization")
-            if self.config.enable_equality_normalization:
-                optimizations.append("equality_normalization")
+            if self.config.enable_equality_conversion:
+                optimizations.append("equality_conversion")
             if self.config.enable_complement_removal:
                 optimizations.append("complement_removal")
 

sqlspec/statement/pipelines/validators/_parameter_style.py

@@ -73,13 +73,13 @@ class ParameterStyleValidator(ProcessorProtocol):
             config = context.config
             param_info = context.parameter_info
 
-            # Check if parameters were normalized by looking for param_ placeholders
-            # This happens when Oracle numeric parameters (:1, :2) are normalized
-            is_normalized = param_info and any(p.name and p.name.startswith("param_") for p in param_info)
+            # Check if parameters were converted by looking for param_ placeholders
+            # This happens when Oracle numeric parameters (:1, :2) are converted
+            is_converted = param_info and any(p.name and p.name.startswith("param_") for p in param_info)
 
-            # First check parameter styles if configured (skip if normalized)
+            # First check parameter styles if configured (skip if converted)
             has_style_errors = False
-            if not is_normalized and config.allowed_parameter_styles is not None and param_info:
+            if not is_converted and config.allowed_parameter_styles is not None and param_info:
                 unique_styles = {p.style for p in param_info}
 
                 if len(unique_styles) > 1 and not config.allow_mixed_parameter_styles:
@@ -279,11 +279,11 @@ class ParameterStyleValidator(ProcessorProtocol):
         """Handle validation for named parameters."""
         missing: list[str] = []
 
-        # Check if we have normalized parameters (e.g., param_0)
-        is_normalized = any(p.name and p.name.startswith("param_") for p in param_info)
+        # Check if we have converted parameters (e.g., param_0)
+        is_converted = any(p.name and p.name.startswith("param_") for p in param_info)
 
-        if is_normalized and hasattr(context, "extra_info"):
-            # For normalized parameters, we need to check against the original placeholder mapping
+        if is_converted and hasattr(context, "extra_info"):
+            # For converted parameters, we need to check against the original placeholder mapping
             placeholder_map = context.extra_info.get("placeholder_map", {})
 
             # Check if we have Oracle numeric keys in merged_params
@@ -291,9 +291,9 @@ class ParameterStyleValidator(ProcessorProtocol):
 
             if all_numeric_keys:
                 # Parameters were provided as list and converted to Oracle numeric dict {"1": val1, "2": val2}
-                for i, _p in enumerate(param_info):
-                    normalized_name = f"param_{i}"
-                    original_key = placeholder_map.get(normalized_name)
+                for i in range(len(param_info)):
+                    converted_name = f"param_{i}"
+                    original_key = placeholder_map.get(converted_name)
 
                     if original_key is not None:
                         # Check using the original key (e.g., "1", "2" for Oracle)
@@ -309,11 +309,11 @@ class ParameterStyleValidator(ProcessorProtocol):
 
                 if all_param_keys:
                     # This was originally a list converted to dict with param_N keys
-                    for i, _p in enumerate(param_info):
-                        normalized_name = f"param_{i}"
-                        if normalized_name not in merged_params or merged_params[normalized_name] is None:
+                    for i in range(len(param_info)):
+                        converted_name = f"param_{i}"
+                        if converted_name not in merged_params or merged_params[converted_name] is None:
                             # Get original parameter style from placeholder map
-                            original_key = placeholder_map.get(normalized_name)
+                            original_key = placeholder_map.get(converted_name)
                             if original_key is not None:
                                 original_key_str = str(original_key)
                                 if original_key_str.isdigit():
@@ -322,16 +322,16 @@ class ParameterStyleValidator(ProcessorProtocol):
                                     missing.append(f":{original_key}")
                 else:
                     # Mixed parameter names, check using placeholder map
-                    for i, _p in enumerate(param_info):
-                        normalized_name = f"param_{i}"
-                        original_key = placeholder_map.get(normalized_name)
+                    for i in range(len(param_info)):
+                        converted_name = f"param_{i}"
+                        original_key = placeholder_map.get(converted_name)
 
                         if original_key is not None:
-                            # For mixed params, check both normalized and original keys
+                            # For mixed params, check both converted and original keys
                             original_key_str = str(original_key)
 
-                            # First check with normalized name
-                            found = normalized_name in merged_params and merged_params[normalized_name] is not None
+                            # First check with converted name
+                            found = converted_name in merged_params and merged_params[converted_name] is not None
 
                             # If not found, check with original key
                             if not found:

sqlspec/statement/pipelines/validators/_performance.py

@@ -601,11 +601,7 @@ class PerformanceValidator(ProcessorProtocol):
                 ),
                 ("join_optimization", optimize_joins.optimize_joins, "Optimize join order and conditions"),
                 ("simplification", simplify.simplify, "Simplify expressions and conditions"),
-                (
-                    "identifier_normalization",
-                    normalize_identifiers.normalize_identifiers,
-                    "Normalize identifier casing",
-                ),
+                ("identifier_conversion", normalize_identifiers.normalize_identifiers, "Normalize identifier casing"),
             ]
 
             best_optimized = expression.copy()