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

sqlspec/core/hashing.py

@@ -185,26 +185,24 @@ def hash_sql_statement(statement: "SQL") -> str:
     """
     from sqlspec.utils.type_guards import is_expression
 
-    if is_expression(statement._statement):
-        expr_hash = hash_expression(statement._statement)
-    else:
-        expr_hash = hash(statement._raw_sql)
+    stmt_expr = statement.statement_expression
+    expr_hash = hash_expression(stmt_expr) if is_expression(stmt_expr) else hash(statement.raw_sql)
 
     param_hash = hash_parameters(
-        positional_parameters=statement._positional_parameters,
-        named_parameters=statement._named_parameters,
-        original_parameters=statement._original_parameters,
+        positional_parameters=statement.positional_parameters,
+        named_parameters=statement.named_parameters,
+        original_parameters=statement.original_parameters,
     )
 
-    filter_hash = hash_filters(statement._filters)
+    filter_hash = hash_filters(statement.filters)
 
     state_components = [
         expr_hash,
         param_hash,
         filter_hash,
-        hash(statement._dialect),
-        hash(statement._is_many),
-        hash(statement._is_script),
+        hash(statement.dialect),
+        hash(statement.is_many),
+        hash(statement.is_script),
     ]
 
     return f"sql:{hash(tuple(state_components))}"

sqlspec/core/parameters.py

@@ -619,7 +619,9 @@ class ParameterConverter:
 
         return converted_sql
 
-    def _convert_sequence_to_dict(self, parameters: Sequence, param_info: "list[ParameterInfo]") -> "dict[str, Any]":
+    def _convert_sequence_to_dict(
+        self, parameters: "Sequence[Any]", param_info: "list[ParameterInfo]"
+    ) -> "dict[str, Any]":
         """Convert sequence parameters to dictionary for named styles.
 
         Args:
@@ -637,7 +639,7 @@ class ParameterConverter:
         return param_dict
 
     def _extract_param_value_mixed_styles(
-        self, param: ParameterInfo, parameters: Mapping, param_keys: "list[str]"
+        self, param: ParameterInfo, parameters: "Mapping[str, Any]", param_keys: "list[str]"
     ) -> "tuple[Any, bool]":
         """Extract parameter value for mixed style parameters.
 
@@ -670,7 +672,9 @@ class ParameterConverter:
 
         return None, False
 
-    def _extract_param_value_single_style(self, param: ParameterInfo, parameters: Mapping) -> "tuple[Any, bool]":
+    def _extract_param_value_single_style(
+        self, param: ParameterInfo, parameters: "Mapping[str, Any]"
+    ) -> "tuple[Any, bool]":
         """Extract parameter value for single style parameters.
 
         Args:
@@ -755,17 +759,30 @@ class ParameterConverter:
             parameter_styles = {p.style for p in param_info}
             has_mixed_styles = len(parameter_styles) > 1
 
+            # Build unique parameter mapping to avoid duplicates when same parameter appears multiple times
+            unique_params: dict[str, Any] = {}
+            param_order: list[str] = []
+
             if has_mixed_styles:
                 param_keys = list(parameters.keys())
                 for param in param_info:
-                    value, found = self._extract_param_value_mixed_styles(param, parameters, param_keys)
-                    if found:
-                        param_values.append(value)
+                    param_key = param.placeholder_text
+                    if param_key not in unique_params:
+                        value, found = self._extract_param_value_mixed_styles(param, parameters, param_keys)
+                        if found:
+                            unique_params[param_key] = value
+                            param_order.append(param_key)
             else:
                 for param in param_info:
-                    value, found = self._extract_param_value_single_style(param, parameters)
-                    if found:
-                        param_values.append(value)
+                    param_key = param.placeholder_text
+                    if param_key not in unique_params:
+                        value, found = self._extract_param_value_single_style(param, parameters)
+                        if found:
+                            unique_params[param_key] = value
+                            param_order.append(param_key)
+
+            # Build parameter values list from unique parameters in order
+            param_values = [unique_params[param_key] for param_key in param_order]
 
             if preserve_parameter_format and original_parameters is not None:
                 return self._preserve_original_format(param_values, original_parameters)
@@ -1064,7 +1081,7 @@ class ParameterProcessor:
 
         return processed_sql, processed_parameters
 
-    def _get_sqlglot_compatible_sql(
+    def get_sqlglot_compatible_sql(
         self, sql: str, parameters: Any, config: ParameterStyleConfig, dialect: Optional[str] = None
     ) -> "tuple[str, Any]":
         """Get SQL normalized for parsing only (Phase 1 only).

sqlspec/core/statement.py

@@ -18,6 +18,7 @@ from sqlspec.utils.type_guards import is_statement_filter, supports_where
 if TYPE_CHECKING:
     from sqlglot.dialects.dialect import DialectType
 
+    from sqlspec.core.cache import FiltersView
     from sqlspec.core.filters import StatementFilter
 
 
@@ -58,6 +59,7 @@ PROCESSED_STATE_SLOTS: Final = (
     "execution_parameters",
     "parsed_expression",
     "operation_type",
+    "parameter_casts",
     "validation_errors",
     "is_many",
 )
@@ -80,6 +82,7 @@ class ProcessedState:
         execution_parameters: Any,
         parsed_expression: "Optional[exp.Expression]" = None,
         operation_type: "OperationType" = "UNKNOWN",
+        parameter_casts: "Optional[dict[int, str]]" = None,
         validation_errors: "Optional[list[str]]" = None,
         is_many: bool = False,
     ) -> None:
@@ -87,6 +90,7 @@ class ProcessedState:
         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
 
@@ -161,14 +165,14 @@ 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: "Union[str, exp.Expression, 'SQL']", _parameters: tuple, _kwargs: dict[str, Any]
     ) -> "StatementConfig":
         """Create default StatementConfig when none provided.
 
         Args:
-            statement: The SQL statement
-            parameters: Statement parameters
-            kwargs: Additional keyword arguments
+            _statement: The SQL statement (unused)
+            _parameters: Statement parameters (unused)
+            _kwargs: Additional keyword arguments (unused)
 
         Returns:
             Default StatementConfig instance
@@ -196,14 +200,14 @@ class SQL:
         Args:
             sql_obj: Existing SQL object to copy from
         """
-        self._raw_sql = sql_obj._raw_sql
-        self._filters = sql_obj._filters.copy()
-        self._named_parameters = sql_obj._named_parameters.copy()
-        self._positional_parameters = sql_obj._positional_parameters.copy()
-        self._is_many = sql_obj._is_many
-        self._is_script = sql_obj._is_script
-        if sql_obj._processed_state is not Empty:
-            self._processed_state = sql_obj._processed_state
+        self._raw_sql = sql_obj.raw_sql
+        self._filters = sql_obj.filters.copy()
+        self._named_parameters = sql_obj.named_parameters.copy()
+        self._positional_parameters = sql_obj.positional_parameters.copy()
+        self._is_many = sql_obj.is_many
+        self._is_script = sql_obj.is_script
+        if sql_obj.is_processed:
+            self._processed_state = sql_obj.get_processed_state()
 
     def _should_auto_detect_many(self, parameters: tuple) -> bool:
         """Detect execute_many mode from parameter structure.
@@ -270,6 +274,15 @@ class SQL:
         """Get the raw SQL string."""
         return self._raw_sql
 
+    @property
+    def raw_sql(self) -> str:
+        """Get raw SQL string (public API).
+
+        Returns:
+            The raw SQL string
+        """
+        return self._raw_sql
+
     @property
     def parameters(self) -> Any:
         """Get the original parameters."""
@@ -277,6 +290,21 @@ class SQL:
             return self._named_parameters
         return self._positional_parameters or []
 
+    @property
+    def positional_parameters(self) -> "list[Any]":
+        """Get positional parameters (public API)."""
+        return self._positional_parameters or []
+
+    @property
+    def named_parameters(self) -> "dict[str, Any]":
+        """Get named parameters (public API)."""
+        return self._named_parameters
+
+    @property
+    def original_parameters(self) -> Any:
+        """Get original parameters (public API)."""
+        return self._original_parameters
+
     @property
     def operation_type(self) -> "OperationType":
         """SQL operation type."""
@@ -301,6 +329,25 @@ class SQL:
         """Applied filters."""
         return self._filters.copy()
 
+    def get_filters_view(self) -> "FiltersView":
+        """Get zero-copy filters view (public API).
+
+        Returns:
+            Read-only view of filters without copying
+        """
+        from sqlspec.core.cache import FiltersView
+
+        return FiltersView(self._filters)
+
+    @property
+    def is_processed(self) -> bool:
+        """Check if SQL has been processed (public API)."""
+        return self._processed_state is not Empty
+
+    def get_processed_state(self) -> Any:
+        """Get processed state (public API)."""
+        return self._processed_state
+
     @property
     def dialect(self) -> "Optional[str]":
         """SQL dialect."""
@@ -311,6 +358,17 @@ class SQL:
         """Internal SQLGlot expression."""
         return self.expression
 
+    @property
+    def statement_expression(self) -> "Optional[exp.Expression]":
+        """Get parsed statement expression (public API).
+
+        Returns:
+            Parsed SQLGlot expression or None if not parsed
+        """
+        if self._processed_state is not Empty:
+            return self._processed_state.parsed_expression
+        return None
+
     @property
     def is_many(self) -> bool:
         """Check if this is execute_many."""
@@ -392,6 +450,7 @@ 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,
                 )
@@ -403,6 +462,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,
                 )
 

sqlspec/core/type_conversion.py

@@ -0,0 +1,234 @@
+"""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 datetime import date, datetime, time, timezone
+from decimal import Decimal
+from typing import Any, Callable, Final, Optional
+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) -> Optional[str]:
+        """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

@@ -3,16 +3,19 @@
 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",
 )
 

sqlspec/driver/_async.py

@@ -1,10 +1,10 @@
 """Asynchronous driver protocol implementation."""
 
 from abc import abstractmethod
-from typing import TYPE_CHECKING, Any, Final, NoReturn, Optional, Union, cast, overload
+from typing import TYPE_CHECKING, Any, Final, NoReturn, Optional, TypeVar, Union, cast, overload
 
 from sqlspec.core import SQL, Statement
-from sqlspec.driver._common import CommonDriverAttributesMixin, ExecutionResult
+from sqlspec.driver._common import CommonDriverAttributesMixin, DataDictionaryMixin, ExecutionResult, VersionInfo
 from sqlspec.driver.mixins import SQLTranslatorMixin, ToSchemaMixin
 from sqlspec.exceptions import NotFoundError
 from sqlspec.utils.logging import get_logger
@@ -21,17 +21,28 @@ if TYPE_CHECKING:
 _LOGGER_NAME: Final[str] = "sqlspec"
 logger = get_logger(_LOGGER_NAME)
 
-__all__ = ("AsyncDriverAdapterBase",)
+__all__ = ("AsyncDataDictionaryBase", "AsyncDriverAdapterBase", "AsyncDriverT")
 
 
 EMPTY_FILTERS: Final["list[StatementFilter]"] = []
 
+AsyncDriverT = TypeVar("AsyncDriverT", bound="AsyncDriverAdapterBase")
+
 
 class AsyncDriverAdapterBase(CommonDriverAttributesMixin, SQLTranslatorMixin, ToSchemaMixin):
     """Base class for asynchronous database drivers."""
 
     __slots__ = ()
 
+    @property
+    @abstractmethod
+    def data_dictionary(self) -> "AsyncDataDictionaryBase":
+        """Get the data dictionary for this driver.
+
+        Returns:
+            Data dictionary instance for metadata queries
+        """
+
     async def dispatch_statement_execution(self, statement: "SQL", connection: "Any") -> "SQLResult":
         """Central execution dispatcher using the Template Method Pattern.
 
@@ -186,10 +197,10 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin, SQLTranslatorMixin, To
         config = statement_config or self.statement_config
 
         if isinstance(statement, SQL):
-            sql_statement = SQL(statement._raw_sql, parameters, statement_config=config, is_many=True, **kwargs)
+            sql_statement = SQL(statement.raw_sql, parameters, statement_config=config, is_many=True, **kwargs)
         else:
             base_statement = self.prepare_statement(statement, filters, statement_config=config, kwargs=kwargs)
-            sql_statement = SQL(base_statement._raw_sql, parameters, statement_config=config, is_many=True, **kwargs)
+            sql_statement = SQL(base_statement.raw_sql, parameters, statement_config=config, is_many=True, **kwargs)
 
         return await self.dispatch_statement_execution(statement=sql_statement, connection=self.connection)
 
@@ -487,3 +498,95 @@ class AsyncDriverAdapterBase(CommonDriverAttributesMixin, SQLTranslatorMixin, To
     def _raise_cannot_extract_value_from_row_type(self, type_name: str) -> NoReturn:
         msg = f"Cannot extract value from row type {type_name}"
         raise TypeError(msg)
+
+
+class AsyncDataDictionaryBase(DataDictionaryMixin):
+    """Base class for asynchronous data dictionary implementations."""
+
+    @abstractmethod
+    async def get_version(self, driver: "AsyncDriverAdapterBase") -> "Optional[VersionInfo]":
+        """Get database version information.
+
+        Args:
+            driver: Async database driver instance
+
+        Returns:
+            Version information or None if detection fails
+        """
+
+    @abstractmethod
+    async def get_feature_flag(self, driver: "AsyncDriverAdapterBase", feature: str) -> bool:
+        """Check if database supports a specific feature.
+
+        Args:
+            driver: Async database driver instance
+            feature: Feature name to check
+
+        Returns:
+            True if feature is supported, False otherwise
+        """
+
+    @abstractmethod
+    async def get_optimal_type(self, driver: "AsyncDriverAdapterBase", type_category: str) -> str:
+        """Get optimal database type for a category.
+
+        Args:
+            driver: Async database driver instance
+            type_category: Type category (e.g., 'json', 'uuid', 'boolean')
+
+        Returns:
+            Database-specific type name
+        """
+
+    async def get_tables(self, driver: "AsyncDriverAdapterBase", schema: "Optional[str]" = None) -> "list[str]":
+        """Get list of tables in schema.
+
+        Args:
+            driver: Async database driver instance
+            schema: Schema name (None for default)
+
+        Returns:
+            List of table names
+        """
+        _ = driver, schema
+        return []
+
+    async def get_columns(
+        self, driver: "AsyncDriverAdapterBase", table: str, schema: "Optional[str]" = None
+    ) -> "list[dict[str, Any]]":
+        """Get column information for a table.
+
+        Args:
+            driver: Async database driver instance
+            table: Table name
+            schema: Schema name (None for default)
+
+        Returns:
+            List of column metadata dictionaries
+        """
+        _ = driver, table, schema
+        return []
+
+    async def get_indexes(
+        self, driver: "AsyncDriverAdapterBase", table: str, schema: "Optional[str]" = None
+    ) -> "list[dict[str, Any]]":
+        """Get index information for a table.
+
+        Args:
+            driver: Async database driver instance
+            table: Table name
+            schema: Schema name (None for default)
+
+        Returns:
+            List of index metadata dictionaries
+        """
+        _ = driver, table, schema
+        return []
+
+    def list_available_features(self) -> "list[str]":
+        """List all features that can be checked via get_feature_flag.
+
+        Returns:
+            List of feature names this data dictionary supports
+        """
+        return self.get_default_features()