sqlspec 0.25.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/core/statement.py

@@ -1,21 +1,22 @@
 """SQL statement and configuration management."""
 
-from typing import TYPE_CHECKING, Any, Callable, Final, Optional, Union
+from typing import TYPE_CHECKING, Any, Final, Optional, TypeAlias
 
 import sqlglot
 from mypy_extensions import mypyc_attr
 from sqlglot import exp
 from sqlglot.errors import ParseError
-from typing_extensions import TypeAlias
 
+import sqlspec.exceptions
 from sqlspec.core.compiler import OperationType, SQLProcessor
 from sqlspec.core.parameters import ParameterConverter, ParameterStyle, ParameterStyleConfig, ParameterValidator
-from sqlspec.exceptions import SQLSpecError
 from sqlspec.typing import Empty, EmptyEnum
 from sqlspec.utils.logging import get_logger
 from sqlspec.utils.type_guards import is_statement_filter, supports_where
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from sqlglot.dialects.dialect import DialectType
 
     from sqlspec.core.cache import FiltersView
@@ -59,6 +60,7 @@ PROCESSED_STATE_SLOTS: Final = (
     "execution_parameters",
     "parsed_expression",
     "operation_type",
+    "parameter_casts",
     "validation_errors",
     "is_many",
 )
@@ -79,15 +81,17 @@ class ProcessedState:
         self,
         compiled_sql: str,
         execution_parameters: Any,
-        parsed_expression: "Optional[exp.Expression]" = None,
+        parsed_expression: "exp.Expression | None" = None,
         operation_type: "OperationType" = "UNKNOWN",
-        validation_errors: "Optional[list[str]]" = None,
+        parameter_casts: "dict[int, str] | None" = None,
+        validation_errors: "list[str] | None" = None,
         is_many: bool = False,
     ) -> None:
         self.compiled_sql = compiled_sql
         self.execution_parameters = execution_parameters
         self.parsed_expression = parsed_expression
         self.operation_type = operation_type
+        self.parameter_casts = parameter_casts or {}
         self.validation_errors = validation_errors or []
         self.is_many = is_many
 
@@ -120,10 +124,10 @@ class SQL:
 
     def __init__(
         self,
-        statement: "Union[str, exp.Expression, 'SQL']",
-        *parameters: "Union[Any, StatementFilter, list[Union[Any, StatementFilter]]]",
+        statement: "str | exp.Expression | 'SQL'",
+        *parameters: "Any | StatementFilter | list[Any | StatementFilter]",
         statement_config: Optional["StatementConfig"] = None,
-        is_many: Optional[bool] = None,
+        is_many: bool | None = None,
         **kwargs: Any,
     ) -> None:
         """Initialize SQL statement.
@@ -138,8 +142,8 @@ class SQL:
         config = statement_config or self._create_auto_config(statement, parameters, kwargs)
         self._statement_config = config
         self._dialect = self._normalize_dialect(config.dialect)
-        self._processed_state: Union[EmptyEnum, ProcessedState] = Empty
-        self._hash: Optional[int] = None
+        self._processed_state: EmptyEnum | ProcessedState = Empty
+        self._hash: int | None = None
         self._filters: list[StatementFilter] = []
         self._named_parameters: dict[str, Any] = {}
         self._positional_parameters: list[Any] = []
@@ -162,7 +166,7 @@ class SQL:
         self._process_parameters(*parameters, **kwargs)
 
     def _create_auto_config(
-        self, _statement: "Union[str, exp.Expression, 'SQL']", _parameters: tuple, _kwargs: dict[str, Any]
+        self, _statement: "str | exp.Expression | 'SQL'", _parameters: tuple, _kwargs: dict[str, Any]
     ) -> "StatementConfig":
         """Create default StatementConfig when none provided.
 
@@ -176,7 +180,7 @@ class SQL:
         """
         return get_default_config()
 
-    def _normalize_dialect(self, dialect: "Optional[DialectType]") -> "Optional[str]":
+    def _normalize_dialect(self, dialect: "DialectType | None") -> "str | None":
         """Convert dialect to string representation.
 
         Args:
@@ -221,7 +225,7 @@ class SQL:
                 return len(param_list) > 1
         return False
 
-    def _process_parameters(self, *parameters: Any, dialect: Optional[str] = None, **kwargs: Any) -> None:
+    def _process_parameters(self, *parameters: Any, dialect: str | None = None, **kwargs: Any) -> None:
         """Process and organize parameters and filters.
 
         Args:
@@ -315,7 +319,7 @@ class SQL:
         return self._statement_config
 
     @property
-    def expression(self) -> "Optional[exp.Expression]":
+    def expression(self) -> "exp.Expression | None":
         """SQLGlot expression."""
         if self._processed_state is not Empty:
             return self._processed_state.parsed_expression
@@ -346,17 +350,17 @@ class SQL:
         return self._processed_state
 
     @property
-    def dialect(self) -> "Optional[str]":
+    def dialect(self) -> "str | None":
         """SQL dialect."""
         return self._dialect
 
     @property
-    def _statement(self) -> "Optional[exp.Expression]":
+    def _statement(self) -> "exp.Expression | None":
         """Internal SQLGlot expression."""
         return self.expression
 
     @property
-    def statement_expression(self) -> "Optional[exp.Expression]":
+    def statement_expression(self) -> "exp.Expression | None":
         """Get parsed statement expression (public API).
 
         Returns:
@@ -447,10 +451,11 @@ class SQL:
                     execution_parameters=compiled_result.execution_parameters,
                     parsed_expression=compiled_result.expression,
                     operation_type=compiled_result.operation_type,
+                    parameter_casts=compiled_result.parameter_casts,
                     validation_errors=[],
                     is_many=self._is_many,
                 )
-            except SQLSpecError:
+            except sqlspec.exceptions.SQLSpecError:
                 raise
             except Exception as e:
                 logger.warning("Processing failed, using fallback: %s", e)
@@ -458,6 +463,7 @@ class SQL:
                     compiled_sql=self._raw_sql,
                     execution_parameters=self._named_parameters or self._positional_parameters,
                     operation_type="UNKNOWN",
+                    parameter_casts={},
                     is_many=self._is_many,
                 )
 
@@ -480,7 +486,7 @@ class SQL:
         return new_sql
 
     def copy(
-        self, statement: "Optional[Union[str, exp.Expression]]" = None, parameters: Optional[Any] = None, **kwargs: Any
+        self, statement: "str | exp.Expression | None" = None, parameters: Any | None = None, **kwargs: Any
     ) -> "SQL":
         """Create copy with modifications.
 
@@ -525,7 +531,7 @@ class SQL:
         new_sql._filters = self._filters.copy()
         return new_sql
 
-    def where(self, condition: "Union[str, exp.Expression]") -> "SQL":
+    def where(self, condition: "str | exp.Expression") -> "SQL":
         """Add WHERE condition to the SQL statement.
 
         Args:
@@ -618,7 +624,7 @@ class StatementConfig:
 
     def __init__(
         self,
-        parameter_config: "Optional[ParameterStyleConfig]" = None,
+        parameter_config: "ParameterStyleConfig | None" = None,
         enable_parsing: bool = True,
         enable_validation: bool = True,
         enable_transformations: bool = True,
@@ -626,14 +632,14 @@ class StatementConfig:
         enable_expression_simplification: bool = False,
         enable_parameter_type_wrapping: bool = True,
         enable_caching: bool = True,
-        parameter_converter: "Optional[ParameterConverter]" = None,
-        parameter_validator: "Optional[ParameterValidator]" = None,
-        dialect: "Optional[DialectType]" = None,
-        pre_process_steps: "Optional[list[Any]]" = None,
-        post_process_steps: "Optional[list[Any]]" = None,
-        execution_mode: "Optional[str]" = None,
-        execution_args: "Optional[dict[str, Any]]" = None,
-        output_transformer: "Optional[Callable[[str, Any], tuple[str, Any]]]" = None,
+        parameter_converter: "ParameterConverter | None" = None,
+        parameter_validator: "ParameterValidator | None" = None,
+        dialect: "DialectType | None" = None,
+        pre_process_steps: "list[Any] | None" = None,
+        post_process_steps: "list[Any] | None" = None,
+        execution_mode: "str | None" = None,
+        execution_args: "dict[str, Any] | None" = None,
+        output_transformer: "Callable[[str, Any], tuple[str, Any]] | None" = None,
     ) -> None:
         """Initialize StatementConfig.
 
@@ -800,4 +806,4 @@ def get_default_parameter_config() -> ParameterStyleConfig:
     )
 
 
-Statement: TypeAlias = Union[str, exp.Expression, SQL]
+Statement: TypeAlias = str | exp.Expression | SQL

sqlspec/core/type_conversion.py

@@ -0,0 +1,235 @@
+"""Centralized type conversion and detection for SQLSpec.
+
+Provides unified type detection and conversion utilities for all database
+adapters, with MyPyC-compatible optimizations.
+"""
+
+import re
+from collections.abc import Callable
+from datetime import date, datetime, time, timezone
+from decimal import Decimal
+from typing import Any, Final
+from uuid import UUID
+
+from sqlspec._serialization import decode_json
+
+# MyPyC-compatible pre-compiled patterns
+SPECIAL_TYPE_REGEX: Final[re.Pattern[str]] = re.compile(
+    r"^(?:"
+    r"(?P<uuid>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})|"
+    r"(?P<iso_datetime>\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)|"
+    r"(?P<iso_date>\d{4}-\d{2}-\d{2})|"
+    r"(?P<iso_time>\d{2}:\d{2}:\d{2}(?:\.\d+)?)|"
+    r"(?P<json>[\[{].*[\]}])|"
+    r"(?P<ipv4>(?:\d{1,3}\.){3}\d{1,3})|"
+    r"(?P<ipv6>(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4})|"
+    r"(?P<mac>(?:[0-9a-f]{2}:){5}[0-9a-f]{2})"
+    r")$",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+class BaseTypeConverter:
+    """Universal type detection and conversion for all adapters.
+
+    Provides centralized type detection and conversion functionality
+    that can be used across all database adapters to ensure consistent
+    behavior. Users can extend this class for custom type conversion needs.
+    """
+
+    __slots__ = ()
+
+    def detect_type(self, value: str) -> str | None:
+        """Detect special types from string values.
+
+        Args:
+            value: String value to analyze.
+
+        Returns:
+            Type name if detected, None otherwise.
+        """
+        if not isinstance(value, str):  # pyright: ignore
+            return None
+        if not value:
+            return None
+
+        match = SPECIAL_TYPE_REGEX.match(value)
+        if not match:
+            return None
+
+        return next((k for k, v in match.groupdict().items() if v), None)
+
+    def convert_value(self, value: str, detected_type: str) -> Any:
+        """Convert string value to appropriate Python type.
+
+        Args:
+            value: String value to convert.
+            detected_type: Detected type name.
+
+        Returns:
+            Converted value in appropriate Python type.
+        """
+        converter = _TYPE_CONVERTERS.get(detected_type)
+        if converter:
+            return converter(value)
+        return value
+
+    def convert_if_detected(self, value: Any) -> Any:
+        """Convert value only if special type detected, else return original.
+
+        This method provides performance optimization by avoiding expensive
+        regex operations on plain strings that don't contain special characters.
+
+        Args:
+            value: Value to potentially convert.
+
+        Returns:
+            Converted value if special type detected, original value otherwise.
+        """
+        if not isinstance(value, str):
+            return value
+
+        # Quick pre-check for performance - avoid regex on plain strings
+        if not any(c in value for c in ["{", "[", "-", ":", "T"]):
+            return value  # Skip regex entirely for "hello world" etc.
+
+        detected_type = self.detect_type(value)
+        if detected_type:
+            try:
+                return self.convert_value(value, detected_type)
+            except Exception:
+                # If conversion fails, return original value
+                return value
+        return value
+
+
+def convert_uuid(value: str) -> UUID:
+    """Convert UUID string to UUID object.
+
+    Args:
+        value: UUID string.
+
+    Returns:
+        UUID object.
+    """
+    return UUID(value)
+
+
+def convert_iso_datetime(value: str) -> datetime:
+    """Convert ISO 8601 datetime string to datetime object.
+
+    Args:
+        value: ISO datetime string.
+
+    Returns:
+        datetime object.
+    """
+    # Handle various ISO formats with timezone
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+
+    # Replace space with T for standard ISO format
+    if " " in value and "T" not in value:
+        value = value.replace(" ", "T")
+
+    return datetime.fromisoformat(value)
+
+
+def convert_iso_date(value: str) -> date:
+    """Convert ISO date string to date object.
+
+    Args:
+        value: ISO date string.
+
+    Returns:
+        date object.
+    """
+    return date.fromisoformat(value)
+
+
+def convert_iso_time(value: str) -> time:
+    """Convert ISO time string to time object.
+
+    Args:
+        value: ISO time string.
+
+    Returns:
+        time object.
+    """
+    return time.fromisoformat(value)
+
+
+def convert_json(value: str) -> Any:
+    """Convert JSON string to Python object.
+
+    Args:
+        value: JSON string.
+
+    Returns:
+        Decoded Python object.
+    """
+    return decode_json(value)
+
+
+def convert_decimal(value: str) -> Decimal:
+    """Convert string to Decimal for precise arithmetic.
+
+    Args:
+        value: Decimal string.
+
+    Returns:
+        Decimal object.
+    """
+    return Decimal(value)
+
+
+# Converter registry
+_TYPE_CONVERTERS: Final[dict[str, Callable[[str], Any]]] = {
+    "uuid": convert_uuid,
+    "iso_datetime": convert_iso_datetime,
+    "iso_date": convert_iso_date,
+    "iso_time": convert_iso_time,
+    "json": convert_json,
+}
+
+
+def format_datetime_rfc3339(dt: datetime) -> str:
+    """Format datetime as RFC 3339 compliant string.
+
+    Args:
+        dt: datetime object.
+
+    Returns:
+        RFC 3339 formatted datetime string.
+    """
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.isoformat()
+
+
+def parse_datetime_rfc3339(dt_str: str) -> datetime:
+    """Parse RFC 3339 datetime string.
+
+    Args:
+        dt_str: RFC 3339 datetime string.
+
+    Returns:
+        datetime object.
+    """
+    # Handle Z suffix
+    if dt_str.endswith("Z"):
+        dt_str = dt_str[:-1] + "+00:00"
+    return datetime.fromisoformat(dt_str)
+
+
+__all__ = (
+    "BaseTypeConverter",
+    "convert_decimal",
+    "convert_iso_date",
+    "convert_iso_datetime",
+    "convert_iso_time",
+    "convert_json",
+    "convert_uuid",
+    "format_datetime_rfc3339",
+    "parse_datetime_rfc3339",
+)

sqlspec/driver/__init__.py

@@ -1,19 +1,20 @@
 """Driver protocols and base classes for database adapters."""
 
-from typing import Union
-
 from sqlspec.driver import mixins
-from sqlspec.driver._async import AsyncDriverAdapterBase
-from sqlspec.driver._common import CommonDriverAttributesMixin, ExecutionResult
-from sqlspec.driver._sync import SyncDriverAdapterBase
+from sqlspec.driver._async import AsyncDataDictionaryBase, AsyncDriverAdapterBase
+from sqlspec.driver._common import CommonDriverAttributesMixin, ExecutionResult, VersionInfo
+from sqlspec.driver._sync import SyncDataDictionaryBase, SyncDriverAdapterBase
 
 __all__ = (
+    "AsyncDataDictionaryBase",
     "AsyncDriverAdapterBase",
     "CommonDriverAttributesMixin",
     "DriverAdapterProtocol",
     "ExecutionResult",
+    "SyncDataDictionaryBase",
     "SyncDriverAdapterBase",
+    "VersionInfo",
     "mixins",
 )
 
-DriverAdapterProtocol = Union[SyncDriverAdapterBase, AsyncDriverAdapterBase]
+DriverAdapterProtocol = SyncDriverAdapterBase | AsyncDriverAdapterBase