sqlspec 0.36.0__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/core/parameters/_registry.py

@@ -0,0 +1,206 @@
+"""Driver parameter profile registry and StatementConfig factory."""
+
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+import sqlspec.exceptions
+from sqlspec.core.parameters._types import DriverParameterProfile, ParameterStyleConfig
+from sqlspec.utils.serializers import from_json, to_json
+
+if TYPE_CHECKING:
+    from sqlspec.core.statement import StatementConfig
+
+__all__ = (
+    "DRIVER_PARAMETER_PROFILES",
+    "build_statement_config_from_profile",
+    "get_driver_profile",
+    "register_driver_profile",
+)
+
+_DEFAULT_JSON_SERIALIZER: Callable[[Any], str] = to_json
+_DEFAULT_JSON_DESERIALIZER: Callable[[str], Any] = from_json
+
+DRIVER_PARAMETER_PROFILES: "dict[str, DriverParameterProfile]" = {}
+
+
+def get_driver_profile(adapter_key: str) -> "DriverParameterProfile":
+    """Return the registered parameter profile for the specified adapter.
+
+    Args:
+        adapter_key: Adapter identifier (case-insensitive).
+
+    Returns:
+        Registered :class:`DriverParameterProfile` instance.
+
+    Raises:
+        ImproperConfigurationError: If the adapter does not have a profile.
+    """
+    key = adapter_key.lower()
+    try:
+        return DRIVER_PARAMETER_PROFILES[key]
+    except KeyError as exc:
+        msg = f"No driver parameter profile registered for adapter '{adapter_key}'."
+        raise sqlspec.exceptions.ImproperConfigurationError(msg) from exc
+
+
+def register_driver_profile(
+    adapter_key: str, profile: "DriverParameterProfile", *, allow_override: bool = False
+) -> None:
+    """Register a driver profile under the canonical adapter key.
+
+    Args:
+        adapter_key: Adapter identifier (case-insensitive).
+        profile: Profile describing parameter behaviour.
+        allow_override: Whether to replace an existing entry.
+
+    Raises:
+        ImproperConfigurationError: If attempting to register a duplicate profile.
+    """
+
+    key = adapter_key.lower()
+    if not allow_override and key in DRIVER_PARAMETER_PROFILES:
+        msg = f"Profile already registered for adapter '{adapter_key}'."
+        raise sqlspec.exceptions.ImproperConfigurationError(msg)
+    DRIVER_PARAMETER_PROFILES[key] = profile
+
+
+def _build_parameter_style_config_from_profile(
+    profile: "DriverParameterProfile",
+    parameter_overrides: "dict[str, Any] | None",
+    json_serializer: "Callable[[Any], str] | None",
+    json_deserializer: "Callable[[str], Any] | None",
+) -> "ParameterStyleConfig":
+    """Build a :class:`ParameterStyleConfig` instance from a driver profile.
+
+    Args:
+        profile: Source driver profile.
+        parameter_overrides: Optional overrides applied before instantiation.
+        json_serializer: Adapter-provided JSON serializer.
+        json_deserializer: Adapter-provided JSON deserializer.
+
+    Returns:
+        Configured :class:`ParameterStyleConfig` ready for statement construction.
+    """
+    overrides = dict(parameter_overrides or {})
+    supported_styles_override = overrides.pop("supported_parameter_styles", None)
+    execution_styles_override = overrides.pop("supported_execution_parameter_styles", None)
+    type_coercion_override = overrides.pop("type_coercion_map", None)
+    json_serializer_override = overrides.pop("json_serializer", None)
+    json_deserializer_override = overrides.pop("json_deserializer", None)
+    tuple_strategy_override = overrides.pop("json_tuple_strategy", None)
+
+    supported_styles = (
+        set(supported_styles_override) if supported_styles_override is not None else set(profile.supported_styles)
+    )
+    if execution_styles_override is None:
+        execution_supported = (
+            set(profile.supported_execution_styles) if profile.supported_execution_styles is not None else None
+        )
+    else:
+        execution_supported = set(execution_styles_override) if execution_styles_override is not None else None
+
+    type_map = (
+        dict(type_coercion_override) if type_coercion_override is not None else dict(profile.custom_type_coercions)
+    )
+
+    parameter_kwargs: dict[str, Any] = {
+        "default_parameter_style": overrides.pop("default_parameter_style", profile.default_style),
+        "supported_parameter_styles": supported_styles,
+        "supported_execution_parameter_styles": execution_supported,
+        "default_execution_parameter_style": overrides.pop(
+            "default_execution_parameter_style", profile.default_execution_style
+        ),
+        "type_coercion_map": type_map,
+        "has_native_list_expansion": overrides.pop("has_native_list_expansion", profile.has_native_list_expansion),
+        "needs_static_script_compilation": overrides.pop(
+            "needs_static_script_compilation", profile.needs_static_script_compilation
+        ),
+        "allow_mixed_parameter_styles": overrides.pop(
+            "allow_mixed_parameter_styles", profile.allow_mixed_parameter_styles
+        ),
+        "preserve_parameter_format": overrides.pop("preserve_parameter_format", profile.preserve_parameter_format),
+        "preserve_original_params_for_many": overrides.pop(
+            "preserve_original_params_for_many", profile.preserve_original_params_for_many
+        ),
+        "strict_named_parameters": overrides.pop("strict_named_parameters", profile.strict_named_parameters),
+        "output_transformer": overrides.pop("output_transformer", profile.default_output_transformer),
+        "ast_transformer": overrides.pop("ast_transformer", profile.default_ast_transformer),
+    }
+
+    parameter_kwargs = {k: v for k, v in parameter_kwargs.items() if v is not None}
+
+    strategy = profile.json_serializer_strategy
+    serializer_value = json_serializer_override or json_serializer
+    deserializer_value = json_deserializer_override or json_deserializer
+
+    if serializer_value is None:
+        serializer_value = profile.extras.get("default_json_serializer", _DEFAULT_JSON_SERIALIZER)
+    if deserializer_value is None:
+        deserializer_value = profile.extras.get("default_json_deserializer", _DEFAULT_JSON_DESERIALIZER)
+
+    serializer = cast("Callable[[Any], str]", serializer_value)
+    deserializer = cast("Callable[[str], Any] | None", deserializer_value)
+
+    if strategy == "driver":
+        parameter_kwargs["json_serializer"] = serializer
+        parameter_kwargs["json_deserializer"] = deserializer
+
+    parameter_kwargs.update(overrides)
+    parameter_config = ParameterStyleConfig(**parameter_kwargs)
+
+    if strategy == "helper":
+        tuple_strategy = tuple_strategy_override or profile.extras.get("json_tuple_strategy", "list")
+        tuple_strategy_literal = cast("Literal['list', 'tuple']", tuple_strategy)
+        parameter_config = parameter_config.with_json_serializers(
+            serializer, tuple_strategy=tuple_strategy_literal, deserializer=deserializer
+        )
+    elif strategy == "driver":
+        parameter_config = parameter_config.replace(json_serializer=serializer, json_deserializer=deserializer)
+
+    type_overrides = profile.extras.get("type_coercion_overrides")
+    if type_overrides:
+        coercion_overrides = cast("Mapping[type, Callable[[Any], Any]]", type_overrides)
+        updated_map: dict[type, Callable[[Any], Any]] = {}
+        updated_map.update(parameter_config.type_coercion_map)
+        updated_map.update(coercion_overrides)
+        parameter_config = parameter_config.replace(type_coercion_map=updated_map)
+
+    return parameter_config
+
+
+def build_statement_config_from_profile(
+    profile: "DriverParameterProfile",
+    *,
+    parameter_overrides: "dict[str, Any] | None" = None,
+    statement_overrides: "dict[str, Any] | None" = None,
+    json_serializer: "Callable[[Any], str] | None" = None,
+    json_deserializer: "Callable[[str], Any] | None" = None,
+) -> "StatementConfig":
+    """Construct a :class:`StatementConfig` seeded from a driver profile.
+
+    Args:
+        profile: Driver profile providing default parameter behaviour.
+        parameter_overrides: Optional overrides for parameter config fields.
+        statement_overrides: Optional overrides for resulting statement config.
+        json_serializer: Optional JSON serializer supplied by the adapter.
+        json_deserializer: Optional JSON deserializer supplied by the adapter.
+
+    Returns:
+        New :class:`StatementConfig` instance with merged configuration.
+    """
+    parameter_config = _build_parameter_style_config_from_profile(
+        profile, parameter_overrides, json_serializer, json_deserializer
+    )
+
+    from sqlspec.core.statement import StatementConfig as _StatementConfig
+
+    statement_kwargs: dict[str, Any] = {}
+    if profile.default_dialect is not None:
+        statement_kwargs["dialect"] = profile.default_dialect
+    if profile.statement_kwargs:
+        statement_kwargs.update(profile.statement_kwargs)
+    if statement_overrides:
+        statement_kwargs.update(statement_overrides)
+
+    filtered_statement_kwargs = {k: v for k, v in statement_kwargs.items() if v is not None}
+    return _StatementConfig(parameter_config=parameter_config, **filtered_statement_kwargs)

sqlspec/core/parameters/_transformers.py

@@ -0,0 +1,292 @@
+"""AST transformer helpers for parameter processing."""
+
+import bisect
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, cast
+
+from sqlglot import exp as _exp
+
+from sqlspec.core.parameters._alignment import (
+    collect_null_parameter_ordinals,
+    looks_like_execute_many,
+    normalize_parameter_key,
+    validate_parameter_alignment,
+)
+from sqlspec.core.parameters._types import ConvertedParameters, ParameterMapping, ParameterPayload, ParameterProfile
+from sqlspec.core.parameters._validator import ParameterValidator
+from sqlspec.utils.type_guards import get_value_attribute
+
+__all__ = (
+    "build_literal_inlining_transform",
+    "build_null_pruning_transform",
+    "replace_null_parameters_with_literals",
+    "replace_placeholders_with_literals",
+)
+
+_AST_TRANSFORMER_VALIDATOR: "ParameterValidator" = ParameterValidator()
+
+
+class _NullPruningTransform:
+    __slots__ = ("_dialect", "_validator")
+
+    def __init__(self, dialect: str, validator: "ParameterValidator | None") -> None:
+        self._dialect = dialect
+        self._validator = validator
+
+    def __call__(
+        self, expression: Any, parameters: "ParameterPayload", parameter_profile: "ParameterProfile"
+    ) -> "tuple[Any, ConvertedParameters]":
+        return replace_null_parameters_with_literals(
+            expression,
+            parameters,
+            dialect=self._dialect,
+            validator=self._validator,
+            parameter_profile=parameter_profile,
+        )
+
+
+class _LiteralInliningTransform:
+    __slots__ = ("_json_serializer",)
+
+    def __init__(self, json_serializer: "Callable[[Any], str]") -> None:
+        self._json_serializer = json_serializer
+
+    def __call__(
+        self, expression: Any, parameters: "ParameterPayload", _parameter_profile: "ParameterProfile"
+    ) -> "tuple[Any, object]":
+        literal_expression = replace_placeholders_with_literals(
+            expression, parameters, json_serializer=self._json_serializer
+        )
+        return literal_expression, parameters
+
+
+class _NullPlaceholderTransformer:
+    __slots__ = ("_null_positions", "_qmark_position", "_sorted_null_positions")
+
+    def __init__(self, null_positions: "set[int]", sorted_null_positions: "list[int]") -> None:
+        self._null_positions = null_positions
+        self._sorted_null_positions = sorted_null_positions
+        self._qmark_position = 0
+
+    def __call__(self, node: Any) -> Any:
+        if isinstance(node, _exp.Placeholder) and node.this is None:
+            current_position = self._qmark_position
+            self._qmark_position += 1
+            if current_position in self._null_positions:
+                return _exp.Null()
+            return node
+
+        if isinstance(node, _exp.Placeholder) and node.this is not None:
+            placeholder_text = str(node.this)
+            normalized_text = placeholder_text.lstrip("$")
+            if normalized_text.isdigit():
+                param_index = int(normalized_text) - 1
+                if param_index in self._null_positions:
+                    return _exp.Null()
+                shift = bisect.bisect_left(self._sorted_null_positions, param_index)
+                new_param_num = param_index - shift + 1
+                return _exp.Placeholder(this=f"${new_param_num}")
+            return node
+
+        if isinstance(node, _exp.Parameter) and node.this is not None:
+            parameter_text = str(node.this)
+            if parameter_text.isdigit():
+                param_index = int(parameter_text) - 1
+                if param_index in self._null_positions:
+                    return _exp.Null()
+                shift = bisect.bisect_left(self._sorted_null_positions, param_index)
+                new_param_num = param_index - shift + 1
+                return _exp.Parameter(this=str(new_param_num))
+            return node
+
+        return node
+
+
+class _PlaceholderLiteralTransformer:
+    __slots__ = ("_json_serializer", "_parameters", "_placeholder_index")
+
+    def __init__(self, parameters: "ParameterPayload", json_serializer: "Callable[[Any], str]") -> None:
+        self._parameters = parameters
+        self._json_serializer = json_serializer
+        self._placeholder_index = 0
+
+    def _resolve_mapping_value(self, param_name: str, payload: "ParameterMapping") -> object | None:
+        candidate_names = (param_name, f"@{param_name}", f":{param_name}", f"${param_name}", f"param_{param_name}")
+        for candidate in candidate_names:
+            if candidate in payload:
+                return cast("object", get_value_attribute(payload[candidate]))
+        normalized = param_name.lstrip("@:$")
+        if normalized in payload:
+            return cast("object", get_value_attribute(payload[normalized]))
+        return None
+
+    def __call__(self, node: Any) -> Any:
+        if (
+            isinstance(node, _exp.Placeholder)
+            and isinstance(self._parameters, Sequence)
+            and not isinstance(self._parameters, (str, bytes, bytearray))
+        ):
+            current_index = self._placeholder_index
+            self._placeholder_index += 1
+            if current_index < len(self._parameters):
+                literal_value = get_value_attribute(self._parameters[current_index])
+                return _create_literal_expression(literal_value, self._json_serializer)
+            return node
+
+        if isinstance(node, _exp.Parameter):
+            param_name = str(node.this) if node.this is not None else ""
+
+            if isinstance(self._parameters, Mapping):
+                resolved_value = self._resolve_mapping_value(param_name, self._parameters)
+                if resolved_value is not None:
+                    return _create_literal_expression(resolved_value, self._json_serializer)
+                return node
+
+            if isinstance(self._parameters, Sequence) and not isinstance(self._parameters, (str, bytes, bytearray)):
+                name = param_name
+                try:
+                    if name.startswith("param_"):
+                        index_value = int(name[6:])
+                        if 0 <= index_value < len(self._parameters):
+                            literal_value = get_value_attribute(self._parameters[index_value])
+                            return _create_literal_expression(literal_value, self._json_serializer)
+                    if name.isdigit():
+                        index_value = int(name)
+                        if 0 <= index_value < len(self._parameters):
+                            literal_value = get_value_attribute(self._parameters[index_value])
+                            return _create_literal_expression(literal_value, self._json_serializer)
+                except (ValueError, AttributeError):
+                    return node
+            return node
+
+        return node
+
+
+def build_null_pruning_transform(
+    *, dialect: str = "postgres", validator: "ParameterValidator | None" = None
+) -> "Callable[[Any, ParameterPayload, ParameterProfile], tuple[Any, ConvertedParameters]]":
+    """Return a callable that prunes NULL placeholders from an expression."""
+    return _NullPruningTransform(dialect, validator)
+
+
+def build_literal_inlining_transform(
+    *, json_serializer: "Callable[[Any], str]"
+) -> "Callable[[Any, ParameterPayload, ParameterProfile], tuple[Any, object]]":
+    """Return a callable that replaces placeholders with SQL literals."""
+    return _LiteralInliningTransform(json_serializer)
+
+
+def replace_null_parameters_with_literals(
+    expression: Any,
+    parameters: "ParameterPayload",
+    *,
+    dialect: str = "postgres",
+    validator: "ParameterValidator | None" = None,
+    parameter_profile: "ParameterProfile | None" = None,
+) -> "tuple[Any, ConvertedParameters]":
+    """Rewrite placeholders representing ``NULL`` values and prune parameters.
+
+    Args:
+        expression: SQLGlot expression tree to transform.
+        parameters: Parameter payload provided by the caller.
+        dialect: SQLGlot dialect for serializing the expression.
+        validator: Optional validator instance for parameter extraction.
+        parameter_profile: Optional parameter profile to reuse for validation.
+
+    Returns:
+        Tuple containing the transformed expression and updated parameters.
+    """
+    if not parameters:
+        if parameters is None:
+            return expression, None
+        if isinstance(parameters, dict):
+            return expression, parameters
+        if isinstance(parameters, (list, tuple)):
+            return expression, list(parameters) if isinstance(parameters, list) else tuple(parameters)
+        return expression, None
+
+    if looks_like_execute_many(parameters):
+        # For execute_many, convert to concrete type
+        if isinstance(parameters, dict):
+            return expression, parameters
+        if isinstance(parameters, (list, tuple)):
+            return expression, list(parameters) if isinstance(parameters, list) else tuple(parameters)
+        return expression, None
+
+    validator_instance = validator or _AST_TRANSFORMER_VALIDATOR
+    profile = parameter_profile
+    if profile is None:
+        parameter_info = validator_instance.extract_parameters(expression.sql(dialect=dialect))
+        profile = ParameterProfile(parameter_info)
+    validate_parameter_alignment(profile, parameters)
+
+    null_positions = collect_null_parameter_ordinals(parameters, profile)
+    if not null_positions:
+        # Convert to concrete type for return
+        if isinstance(parameters, dict):
+            return expression, parameters
+        if isinstance(parameters, (list, tuple)):
+            return expression, list(parameters) if isinstance(parameters, list) else tuple(parameters)
+        if isinstance(parameters, Mapping):
+            return expression, dict(parameters)
+        if isinstance(parameters, Sequence) and not isinstance(parameters, (str, bytes)):
+            return expression, list(parameters)
+        return expression, None
+
+    sorted_null_positions = sorted(null_positions)
+
+    transformer = _NullPlaceholderTransformer(null_positions, sorted_null_positions)
+    transformed_expression = expression.transform(transformer)
+
+    cleaned_parameters: ConvertedParameters
+    if isinstance(parameters, Sequence) and not isinstance(parameters, (str, bytes, bytearray)):
+        cleaned_list = [value for index, value in enumerate(parameters) if index not in null_positions]
+        cleaned_parameters = tuple(cleaned_list) if isinstance(parameters, tuple) else cleaned_list
+    elif isinstance(parameters, Mapping):
+        cleaned_dict: dict[str, Any] = {}
+        next_numeric_index = 1
+
+        for key, value in parameters.items():
+            if value is None:
+                continue
+            key_kind, normalized_key = normalize_parameter_key(key)
+            if key_kind == "index" and isinstance(normalized_key, int):
+                cleaned_dict[str(next_numeric_index)] = value
+                next_numeric_index += 1
+            else:
+                cleaned_dict[str(normalized_key)] = value
+        cleaned_parameters = cleaned_dict
+    else:
+        cleaned_parameters = None
+
+    return transformed_expression, cleaned_parameters
+
+
+def _create_literal_expression(value: Any, json_serializer: "Callable[[Any], str]") -> Any:
+    """Create a SQLGlot literal expression for the given value."""
+    if value is None:
+        return _exp.Null()
+    if isinstance(value, bool):
+        return _exp.Boolean(this=value)
+    if isinstance(value, (int, float)):
+        return _exp.Literal.number(str(value))
+    if isinstance(value, str):
+        return _exp.Literal.string(value)
+    if isinstance(value, (list, tuple)):
+        items = [_create_literal_expression(item, json_serializer) for item in value]
+        return _exp.Array(expressions=items)
+    if isinstance(value, dict):
+        json_value = json_serializer(value)
+        return _exp.Literal.string(json_value)
+    return _exp.Literal.string(str(value))
+
+
+def replace_placeholders_with_literals(
+    expression: Any, parameters: "ParameterPayload", *, json_serializer: "Callable[[Any], str]"
+) -> Any:
+    """Replace placeholders in an expression tree with literal values."""
+    if not parameters:
+        return expression
+
+    transformer = _PlaceholderLiteralTransformer(parameters, json_serializer)
+    return expression.transform(transformer)