"""Core parameter data structures and utilities."""
from collections.abc import Callable, Collection, Generator, Iterable, Mapping, Sequence
from datetime import date, datetime, time
from decimal import Decimal
from enum import Enum
from types import MappingProxyType
from typing import Any, Final, Literal, TypeAlias
from mypy_extensions import mypyc_attr
__all__ = (
"ConvertedParameters",
"DriverParameterProfile",
"NamedParameterOutput",
"ParameterInfo",
"ParameterMapping",
"ParameterPayload",
"ParameterProcessingResult",
"ParameterProfile",
"ParameterSequence",
"ParameterStyle",
"ParameterStyleConfig",
"PositionalParameterOutput",
"TypedParameter",
"is_iterable_parameters",
"wrap_with_type",
)
ParameterMapping: TypeAlias = "Mapping[str, object]"
"""Type alias for mapping-based parameter payloads."""
ParameterSequence: TypeAlias = "Sequence[object]"
"""Type alias for sequence-based parameter payloads."""
ParameterPayload: TypeAlias = "ParameterMapping | ParameterSequence | object | None"
"""Type alias for parameter payloads accepted by the processing pipeline."""
ConvertedParameters: TypeAlias = "dict[str, Any] | list[Any] | tuple[Any, ...] | object | None"
"""
Type alias for parameters after conversion to driver-consumable format.
This type represents the concrete output of parameter conversion functions.
Unlike :data:`ParameterPayload` (which represents inputs and can include abstract
Mapping/Sequence types), :data:`ConvertedParameters` includes concrete container
types and scalar objects that database drivers can directly consume.
The union includes:
- ``dict[str, Any]``: Named parameters
- ``list[Any]``: Positional parameters as list
- ``tuple[Any, ...]``: Positional parameters as tuple
- ``object``: Scalar parameter payloads after type coercion
- ``None``: When parameters are statically embedded in SQL string
"""
PositionalParameterOutput: TypeAlias = "list[Any] | tuple[Any, ...]"
"""Type alias for positional-only parameter outputs.
Used when a function is known to return only positional (not named) parameters.
This is narrower than :data:`ConvertedParameters` and excludes ``dict`` and ``None``.
"""
NamedParameterOutput: TypeAlias = "dict[str, Any]"
"""Type alias for named-only parameter outputs.
Used when a function is known to return only named (not positional) parameters.
This is narrower than :data:`ConvertedParameters` and excludes ``list``, ``tuple``, and ``None``.
"""
TYPED_PARAMETER_SLOTS: Final[tuple[str, ...]] = ("_hash", "original_type", "semantic_name", "value")
PARAMETER_INFO_SLOTS: Final[tuple[str, ...]] = ("name", "ordinal", "placeholder_text", "position", "style")
PARAMETER_STYLE_CONFIG_SLOTS: Final[tuple[str, ...]] = (
"_hash_cache",
"allow_mixed_parameter_styles",
"ast_transformer",
"default_execution_parameter_style",
"default_parameter_style",
"has_native_list_expansion",
"json_deserializer",
"json_serializer",
"needs_static_script_compilation",
"output_transformer",
"preserve_original_params_for_many",
"preserve_parameter_format",
"strict_named_parameters",
"supported_execution_parameter_styles",
"supported_parameter_styles",
"type_coercion_map",
)
DRIVER_PARAMETER_PROFILE_SLOTS: Final[tuple[str, ...]] = (
"allow_mixed_parameter_styles",
"custom_type_coercions",
"default_ast_transformer",
"default_dialect",
"default_execution_style",
"default_output_transformer",
"default_style",
"extras",
"has_native_list_expansion",
"json_serializer_strategy",
"name",
"needs_static_script_compilation",
"preserve_original_params_for_many",
"preserve_parameter_format",
"statement_kwargs",
"strict_named_parameters",
"supported_execution_styles",
"supported_styles",
)
PARAMETER_PROFILE_SLOTS: Final[tuple[str, ...]] = (
"_parameters",
"_placeholder_counts",
"named_parameters",
"reused_ordinals",
"styles",
)
PARAMETER_PROCESSING_RESULT_SLOTS: Final[tuple[str, ...]] = (
"applied_wrap_types",
"input_named_parameters",
"parameter_profile",
"parameters",
"parsed_expression",
"sql",
"sqlglot_sql",
)
@mypyc_attr(allow_interpreted_subclasses=False)
class ParameterStyle(str, Enum):
"""Enumeration of supported SQL parameter placeholder styles."""
NONE = "none"
STATIC = "static"
QMARK = "qmark"
NUMERIC = "numeric"
NAMED_COLON = "named_colon"
POSITIONAL_COLON = "positional_colon"
NAMED_AT = "named_at"
NAMED_DOLLAR = "named_dollar"
NAMED_PYFORMAT = "pyformat_named"
POSITIONAL_PYFORMAT = "pyformat_positional"