sqlspec 0.32.0__py3-none-any.whl

sqlspec/core/hashing.py

@@ -0,0 +1,274 @@
+"""Statement hashing utilities for cache key generation.
+
+Provides hashing functions for SQL statements, expressions, parameters,
+filters, and AST sub-expressions.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from sqlglot import exp
+
+from sqlspec.utils.type_guards import is_typed_parameter
+
+if TYPE_CHECKING:
+    from sqlspec.core.filters import StatementFilter
+    from sqlspec.core.statement import SQL
+
+__all__ = (
+    "hash_expression",
+    "hash_expression_node",
+    "hash_optimized_expression",
+    "hash_parameters",
+    "hash_sql_statement",
+)
+
+
+def hash_expression(expr: exp.Expression | None, _seen: set[int] | None = None) -> int:
+    """Generate hash from AST structure.
+
+    Args:
+        expr: SQLGlot Expression to hash
+        _seen: Set of seen object IDs to handle circular references
+
+    Returns:
+        Hash of the AST structure
+    """
+    if expr is None:
+        return hash(None)
+
+    if _seen is None:
+        _seen = set()
+
+    expr_id = id(expr)
+    if expr_id in _seen:
+        return hash(expr_id)
+
+    _seen.add(expr_id)
+
+    components: list[Any] = [type(expr).__name__]
+
+    for key, value in sorted(expr.args.items()):
+        components.extend((key, _hash_value(value, _seen)))
+
+    return hash(tuple(components))
+
+
+def _hash_value(value: Any, _seen: set[int]) -> int:
+    """Hash different value types.
+
+    Args:
+        value: Value to hash (can be Expression, list, dict, or primitive)
+        _seen: Set of seen object IDs to handle circular references
+
+    Returns:
+        Hash of the value
+    """
+    if isinstance(value, exp.Expression):
+        return hash_expression(value, _seen)
+    if isinstance(value, list):
+        return hash(tuple(_hash_value(v, _seen) for v in value))
+    if isinstance(value, dict):
+        items = sorted((k, _hash_value(v, _seen)) for k, v in value.items())
+        return hash(tuple(items))
+    if isinstance(value, tuple):
+        return hash(tuple(_hash_value(v, _seen) for v in value))
+
+    return hash(value)
+
+
+def hash_parameters(
+    positional_parameters: list[Any] | None = None,
+    named_parameters: dict[str, Any] | None = None,
+    original_parameters: Any | None = None,
+) -> int:
+    """Generate hash for SQL parameters.
+
+    Args:
+        positional_parameters: List of positional parameters
+        named_parameters: Dictionary of named parameters
+        original_parameters: Original parameters (for execute_many)
+
+    Returns:
+        Combined hash of all parameters
+    """
+    param_hash = 0
+
+    if positional_parameters:
+        from sqlspec.core.parameters import TypedParameter
+
+        hashable_parameters: list[tuple[Any, Any]] = []
+        for param in positional_parameters:
+            if isinstance(param, TypedParameter):
+                if isinstance(param.value, (list, dict)):
+                    hashable_parameters.append((repr(param.value), param.original_type))
+                else:
+                    hashable_parameters.append((param.value, param.original_type))
+            elif isinstance(param, (list, dict)):
+                hashable_parameters.append((repr(param), "unhashable"))
+            else:
+                try:
+                    hash(param)
+                    hashable_parameters.append((param, "primitive"))
+                except TypeError:
+                    hashable_parameters.append((repr(param), "unhashable_repr"))
+
+        param_hash ^= hash(tuple(hashable_parameters))
+
+    if named_parameters:
+        hashable_items = []
+        for key, value in sorted(named_parameters.items()):
+            if is_typed_parameter(value):
+                if isinstance(value.value, (list, dict)):
+                    hashable_items.append((key, (repr(value.value), value.original_type)))
+                else:
+                    hashable_items.append((key, (value.value, value.original_type)))
+            elif isinstance(value, (list, dict)):
+                hashable_items.append((key, (repr(value), "unhashable")))
+            else:
+                hashable_items.append((key, (value, "primitive")))
+        param_hash ^= hash(tuple(hashable_items))
+
+    if original_parameters is not None:
+        if isinstance(original_parameters, list):
+            param_hash ^= hash(("original_count", len(original_parameters)))
+            if original_parameters:
+                sample_size = min(3, len(original_parameters))
+                sample_hash = hash(repr(original_parameters[:sample_size]))
+                param_hash ^= hash(("original_sample", sample_hash))
+        else:
+            param_hash ^= hash(("original", repr(original_parameters)))
+
+    return param_hash
+
+
+def _hash_filter_value(value: Any) -> int:
+    try:
+        return hash(value)
+    except TypeError:
+        return hash(repr(value))
+
+
+def hash_filters(filters: list["StatementFilter"] | None = None) -> int:
+    """Generate hash for statement filters.
+
+    Args:
+        filters: List of statement filters
+
+    Returns:
+        Hash of the filters
+    """
+    if not filters:
+        return 0
+
+    filter_components = []
+    for f in filters:
+        components: list[Any] = [f.__class__.__name__]
+
+        filter_dict = getattr(f, "__dict__", None)
+        if filter_dict is not None:
+            for key, value in sorted(filter_dict.items()):
+                components.append((key, _hash_filter_value(value)))
+
+        filter_components.append(tuple(components))
+
+    return hash(tuple(filter_components))
+
+
+def hash_sql_statement(statement: "SQL") -> str:
+    """Generate cache key for a SQL statement.
+
+    Args:
+        statement: SQL statement object
+
+    Returns:
+        Cache key string
+    """
+    from sqlspec.utils.type_guards import is_expression
+
+    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,
+    )
+
+    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),
+    ]
+
+    return f"sql:{hash(tuple(state_components))}"
+
+
+def hash_expression_node(node: exp.Expression, include_children: bool = True, dialect: str | None = None) -> str:
+    """Generate cache key for an expression node.
+
+    Args:
+        node: The expression node to hash
+        include_children: Whether to include child nodes in the hash
+        dialect: SQL dialect for context-aware hashing
+
+    Returns:
+        Cache key string for the expression node
+    """
+    if include_children:
+        node_hash = hash_expression(node)
+    else:
+        components: list[Any] = [type(node).__name__]
+        for key, value in sorted(node.args.items()):
+            if not isinstance(value, (list, exp.Expression)):
+                components.extend((key, hash(value)))
+        node_hash = hash(tuple(components))
+
+    dialect_part = f":{dialect}" if dialect else ""
+    return f"expr{dialect_part}:{node_hash}"
+
+
+def hash_optimized_expression(
+    expr: exp.Expression,
+    dialect: str,
+    schema: dict[str, Any] | None = None,
+    optimizer_settings: dict[str, Any] | None = None,
+) -> str:
+    """Generate cache key for optimized expressions.
+
+    Creates a key that includes expression structure, dialect, schema
+    context, and optimizer settings.
+
+    Args:
+        expr: The unoptimized expression
+        dialect: Target SQL dialect
+        schema: Schema information
+        optimizer_settings: Additional optimizer configuration
+
+    Returns:
+        Cache key string for the optimized expression
+    """
+
+    expr_hash = hash_expression(expr)
+
+    schema_hash = 0
+    if schema:
+        schema_items = []
+        for table_name, table_schema in sorted(schema.items()):
+            if isinstance(table_schema, dict):
+                schema_items.append((table_name, len(table_schema)))
+            else:
+                schema_items.append((table_name, hash("unknown")))
+        schema_hash = hash(tuple(schema_items))
+
+    settings_hash = 0
+    if optimizer_settings:
+        settings_items = sorted(optimizer_settings.items())
+        settings_hash = hash(tuple(settings_items))
+
+    components = (expr_hash, dialect, schema_hash, settings_hash)
+    return f"opt:{hash(components)}"

sqlspec/core/metrics.py

@@ -0,0 +1,83 @@
+"""Telemetry helper objects for stack execution."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - imported for typing only
+    from sqlspec.observability import ObservabilityRuntime
+
+__all__ = ("StackExecutionMetrics",)
+
+
+class StackExecutionMetrics:
+    """Capture telemetry facts about a stack execution."""
+
+    __slots__ = (
+        "adapter",
+        "continue_on_error",
+        "duration_s",
+        "error_count",
+        "error_type",
+        "forced_disable",
+        "native_pipeline",
+        "statement_count",
+    )
+
+    def __init__(
+        self,
+        adapter: str,
+        statement_count: int,
+        *,
+        continue_on_error: bool,
+        native_pipeline: bool,
+        forced_disable: bool,
+    ) -> None:
+        self.adapter = adapter
+        self.statement_count = statement_count
+        self.continue_on_error = continue_on_error
+        self.native_pipeline = native_pipeline
+        self.forced_disable = forced_disable
+        self.duration_s = 0.0
+        self.error_type: str | None = None
+        self.error_count = 0
+
+    def record_duration(self, duration: float) -> None:
+        """Record execution duration in seconds."""
+
+        self.duration_s = duration
+
+    def record_operation_error(self, error: Exception) -> None:
+        """Record an operation error when continue-on-error is enabled."""
+
+        self.error_count += 1
+        if not self.continue_on_error and self.error_type is None:
+            self.error_type = type(error).__name__
+
+    def record_error(self, error: Exception) -> None:
+        """Record a terminal error."""
+
+        self.error_type = type(error).__name__
+        self.error_count = max(self.error_count, 1)
+
+    def emit(self, runtime: "ObservabilityRuntime") -> None:
+        """Emit collected metrics to the configured runtime."""
+
+        runtime.increment_metric("stack.execute.invocations")
+        runtime.increment_metric("stack.execute.statements", float(self.statement_count))
+
+        mode = "continue" if self.continue_on_error else "failfast"
+        runtime.increment_metric(f"stack.execute.mode.{mode}")
+
+        pipeline_label = "native" if self.native_pipeline else "sequential"
+        runtime.increment_metric(f"stack.execute.path.{pipeline_label}")
+
+        if self.forced_disable:
+            runtime.increment_metric("stack.execute.override.forced")
+
+        runtime.increment_metric("stack.execute.duration_ms", self.duration_s * 1000.0)
+
+        if self.error_type is not None:
+            runtime.increment_metric("stack.execute.errors")
+            runtime.increment_metric(f"stack.execute.errors.{self.error_type}")
+
+        if self.error_count and self.continue_on_error:
+            runtime.increment_metric("stack.execute.partial_errors", float(self.error_count))

sqlspec/core/parameters/__init__.py

@@ -0,0 +1,64 @@
+"""Parameter processing public API."""
+
+from sqlspec.core.parameters._alignment import (
+    EXECUTE_MANY_MIN_ROWS,
+    collect_null_parameter_ordinals,
+    looks_like_execute_many,
+    normalize_parameter_key,
+    validate_parameter_alignment,
+)
+from sqlspec.core.parameters._converter import ParameterConverter
+from sqlspec.core.parameters._processor import ParameterProcessor
+from sqlspec.core.parameters._registry import (
+    DRIVER_PARAMETER_PROFILES,
+    build_statement_config_from_profile,
+    get_driver_profile,
+    register_driver_profile,
+)
+from sqlspec.core.parameters._transformers import (
+    build_literal_inlining_transform,
+    build_null_pruning_transform,
+    replace_null_parameters_with_literals,
+    replace_placeholders_with_literals,
+)
+from sqlspec.core.parameters._types import (
+    DriverParameterProfile,
+    ParameterInfo,
+    ParameterProcessingResult,
+    ParameterProfile,
+    ParameterStyle,
+    ParameterStyleConfig,
+    TypedParameter,
+    is_iterable_parameters,
+    wrap_with_type,
+)
+from sqlspec.core.parameters._validator import PARAMETER_REGEX, ParameterValidator
+
+__all__ = (
+    "DRIVER_PARAMETER_PROFILES",
+    "EXECUTE_MANY_MIN_ROWS",
+    "PARAMETER_REGEX",
+    "DriverParameterProfile",
+    "ParameterConverter",
+    "ParameterInfo",
+    "ParameterProcessingResult",
+    "ParameterProcessor",
+    "ParameterProfile",
+    "ParameterStyle",
+    "ParameterStyleConfig",
+    "ParameterValidator",
+    "TypedParameter",
+    "build_literal_inlining_transform",
+    "build_null_pruning_transform",
+    "build_statement_config_from_profile",
+    "collect_null_parameter_ordinals",
+    "get_driver_profile",
+    "is_iterable_parameters",
+    "looks_like_execute_many",
+    "normalize_parameter_key",
+    "register_driver_profile",
+    "replace_null_parameters_with_literals",
+    "replace_placeholders_with_literals",
+    "validate_parameter_alignment",
+    "wrap_with_type",
+)

sqlspec/core/parameters/_alignment.py

@@ -0,0 +1,266 @@
+"""Parameter alignment and validation helpers."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+import sqlspec.exceptions
+from sqlspec.core.parameters._types import ParameterProfile, ParameterStyle
+
+__all__ = (
+    "EXECUTE_MANY_MIN_ROWS",
+    "collect_null_parameter_ordinals",
+    "looks_like_execute_many",
+    "normalize_parameter_key",
+    "validate_parameter_alignment",
+)
+
+EXECUTE_MANY_MIN_ROWS: int = 2
+
+
+def _is_sequence_like(value: Any) -> bool:
+    return isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray))
+
+
+def normalize_parameter_key(key: Any) -> "tuple[str, int | str]":
+    """Normalize a parameter key into an ``(kind, value)`` tuple.
+
+    Args:
+        key: Key supplied by the caller (index, name, or adapter-specific token).
+
+    Returns:
+        Tuple identifying the key type and canonical value for alignment checks.
+    """
+    if isinstance(key, str):
+        stripped_numeric = key.lstrip("$")
+        if stripped_numeric.isdigit():
+            return ("index", int(stripped_numeric) - 1)
+        if key.isdigit():
+            return ("index", int(key) - 1)
+        return ("named", key)
+    if isinstance(key, int):
+        if key > 0:
+            return ("index", key - 1)
+        return ("index", key)
+    return ("named", str(key))
+
+
+def looks_like_execute_many(parameters: Any) -> bool:
+    """Return ``True`` when the payload resembles an ``execute_many`` structure.
+
+    Args:
+        parameters: Potential parameter payload to inspect.
+
+    Returns:
+        ``True`` if the payload appears to be a sequence of parameter sets.
+    """
+    if not _is_sequence_like(parameters) or len(parameters) < EXECUTE_MANY_MIN_ROWS:
+        return False
+    return all(_is_sequence_like(entry) or isinstance(entry, Mapping) for entry in parameters)
+
+
+def collect_null_parameter_ordinals(parameters: Any, profile: "ParameterProfile") -> "set[int]":
+    """Identify placeholder ordinals whose provided values are ``None``.
+
+    Args:
+        parameters: Parameter payload supplied by the caller.
+        profile: Metadata describing detected placeholders.
+
+    Returns:
+        Set of ordinal indices corresponding to ``None`` values.
+    """
+    if parameters is None:
+        return set()
+
+    null_positions: set[int] = set()
+
+    if isinstance(parameters, Mapping):
+        name_lookup: dict[str, int] = {}
+        for parameter in profile.parameters:
+            if parameter.name:
+                name_lookup[parameter.name] = parameter.ordinal
+                stripped_name = parameter.name.lstrip("@")
+                name_lookup.setdefault(stripped_name, parameter.ordinal)
+                name_lookup.setdefault(f"@{stripped_name}", parameter.ordinal)
+
+        for key, value in parameters.items():
+            if value is not None:
+                continue
+            key_kind, normalized_key = normalize_parameter_key(key)
+            if key_kind == "index" and isinstance(normalized_key, int):
+                null_positions.add(normalized_key)
+                continue
+            if key_kind == "named":
+                ordinal = name_lookup.get(str(normalized_key))
+                if ordinal is not None:
+                    null_positions.add(ordinal)
+        return null_positions
+
+    if isinstance(parameters, Sequence) and not isinstance(parameters, (str, bytes, bytearray)):
+        for index, value in enumerate(parameters):
+            if value is None:
+                null_positions.add(index)
+        return null_positions
+
+    return null_positions
+
+
+def _collect_expected_identifiers(parameter_profile: "ParameterProfile") -> "set[tuple[str, int | str]]":
+    identifiers: set[tuple[str, int | str]] = set()
+    for parameter in parameter_profile.parameters:
+        style = parameter.style
+        name = parameter.name
+        if style in {
+            ParameterStyle.NAMED_COLON,
+            ParameterStyle.NAMED_AT,
+            ParameterStyle.NAMED_DOLLAR,
+            ParameterStyle.NAMED_PYFORMAT,
+        }:
+            identifiers.add(("named", name or f"param_{parameter.ordinal}"))
+        elif style in {ParameterStyle.NUMERIC, ParameterStyle.POSITIONAL_COLON}:
+            if name and name.isdigit():
+                identifiers.add(("index", int(name) - 1))
+            else:
+                identifiers.add(("index", parameter.ordinal))
+        else:
+            identifiers.add(("index", parameter.ordinal))
+    return identifiers
+
+
+def _collect_actual_identifiers(parameters: Any) -> "tuple[set[tuple[str, int | str]], int]":
+    if parameters is None:
+        return set(), 0
+    if isinstance(parameters, Mapping):
+        mapping_identifiers = {normalize_parameter_key(key) for key in parameters}
+        return mapping_identifiers, len(parameters)
+    if looks_like_execute_many(parameters):
+        aggregated_identifiers: set[tuple[str, int | str]] = set()
+        for entry in parameters:
+            entry_identifiers, _ = _collect_actual_identifiers(entry)
+            aggregated_identifiers.update(entry_identifiers)
+        return aggregated_identifiers, len(aggregated_identifiers)
+    if _is_sequence_like(parameters):
+        identifiers = {("index", cast("int | str", index)) for index in range(len(parameters))}
+        return identifiers, len(parameters)
+    identifiers = {("index", cast("int | str", 0))}
+    return identifiers, 1
+
+
+def _format_identifiers(identifiers: "set[tuple[str, int | str]]") -> str:
+    if not identifiers:
+        return "[]"
+    formatted: list[str] = []
+    for identifier in sorted(identifiers, key=lambda item: (item[0], str(item[1]))):
+        kind, value = identifier
+        if kind == "named":
+            formatted.append(str(value))
+        elif isinstance(value, int):
+            formatted.append(str(value + 1))
+        else:
+            formatted.append(str(value))
+    return "[" + ", ".join(formatted) + "]"
+
+
+def _normalize_index_identifiers(expected: "set[tuple[str, int | str]]", actual: "set[tuple[str, int | str]]") -> bool:
+    """Allow positional payloads to satisfy generated param_N identifiers."""
+
+    if not expected or not actual:
+        return False
+
+    expected_named = {value for kind, value in expected if kind == "named"}
+    actual_indexes = {value for kind, value in actual if kind == "index"}
+
+    if not expected_named or not actual_indexes:
+        return False
+
+    normalized_expected: set[int] = set()
+    for name in expected_named:
+        if not isinstance(name, str) or not name.startswith("param_"):
+            return False
+        suffix = name[6:]
+        if not suffix.isdigit():
+            return False
+        normalized_expected.add(int(suffix))
+
+    if not normalized_expected:
+        return False
+
+    if not all(isinstance(index, int) for index in actual_indexes):
+        return False
+
+    normalized_actual = {int(index) for index in actual_indexes}
+    return normalized_actual == normalized_expected
+
+
+def _validate_single_parameter_set(
+    parameter_profile: "ParameterProfile", parameters: Any, batch_index: "int | None" = None
+) -> None:
+    expected_identifiers = _collect_expected_identifiers(parameter_profile)
+    actual_identifiers, actual_count = _collect_actual_identifiers(parameters)
+    expected_count = len(expected_identifiers)
+
+    if expected_count == 0 and actual_count == 0:
+        return
+
+    prefix = "Parameter count mismatch"
+    if batch_index is not None:
+        prefix = f"{prefix} in batch {batch_index}"
+
+    if expected_count == 0 and actual_count > 0:
+        msg = f"{prefix}: statement does not accept parameters."
+        raise sqlspec.exceptions.SQLSpecError(msg)
+
+    if expected_count > 0 and actual_count == 0:
+        msg = f"{prefix}: expected {expected_count} parameters, received 0."
+        raise sqlspec.exceptions.SQLSpecError(msg)
+
+    if expected_count != actual_count:
+        msg = f"{prefix}: {actual_count} parameters provided but {expected_count} placeholders detected."
+        raise sqlspec.exceptions.SQLSpecError(msg)
+
+    identifiers_match = expected_identifiers == actual_identifiers or _normalize_index_identifiers(
+        expected_identifiers, actual_identifiers
+    )
+
+    if not identifiers_match:
+        msg = (
+            f"{prefix}: expected identifiers {_format_identifiers(expected_identifiers)}, "
+            f"received {_format_identifiers(actual_identifiers)}."
+        )
+        raise sqlspec.exceptions.SQLSpecError(msg)
+
+
+def validate_parameter_alignment(
+    parameter_profile: "ParameterProfile | None", parameters: Any, *, is_many: bool = False
+) -> None:
+    """Ensure provided parameters align with detected placeholders.
+
+    Args:
+        parameter_profile: Placeholder metadata extracted from the statement.
+        parameters: Parameter payload the adapter will execute with.
+        is_many: Whether the call explicitly targets ``execute_many``.
+
+    Raises:
+        SQLSpecError: If counts or identifiers differ between placeholders and payload.
+    """
+    profile = parameter_profile or ParameterProfile.empty()
+    if profile.total_count == 0:
+        return
+
+    effective_is_many = is_many or looks_like_execute_many(parameters)
+
+    if effective_is_many:
+        if parameters is None:
+            if profile.total_count == 0:
+                return
+            msg = "Parameter count mismatch: expected parameter sets for execute_many."
+            raise sqlspec.exceptions.SQLSpecError(msg)
+        if not _is_sequence_like(parameters):
+            msg = "Parameter count mismatch: expected sequence of parameter sets for execute_many."
+            raise sqlspec.exceptions.SQLSpecError(msg)
+        if len(parameters) == 0:
+            return
+        for index, param_set in enumerate(parameters):
+            _validate_single_parameter_set(profile, param_set, batch_index=index)
+        return
+
+    _validate_single_parameter_set(profile, parameters)