Parameters & Coercion¶

from sqlspec.core import (
    BaseInputConverter,
    DriverParameterProfile,
    ParameterConverter,
    ParameterDeclaration,
    ParameterInfo,
    ParameterProcessingResult,
    ParameterProcessor,
    ParameterProfile,
    ParameterStyle,
    ParameterStyleConfig,
    ParameterValidator,
    ParamTypeMatcher,
    TypeCoercionCapabilities,
    TypedParameter,
    get_driver_profile,
    register_driver_profile,
    register_param_type,
    wrap_with_type,
)

Parameter extraction, validation, placeholder style rewriting (?, $1, :name, @name, %(name)s), and runtime type coercion. See Parameters & Bindings for usage examples.

Parameter Styles & Profiles¶

ParameterStyle ¶

Bases: StrEnum

Enumeration of supported SQL parameter placeholder styles.

ParameterStyleConfig ¶

Configuration describing parameter behaviour for a statement.

default_parameter_style ¶

default_parameter_style = default_parameter_style

supported_parameter_styles ¶

supported_parameter_styles = frozenset(
    supported_parameter_styles or (default_parameter_style,)
)

default_execution_parameter_style ¶

default_execution_parameter_style = (
    default_execution_parameter_style or default_parameter_style
)

supported_execution_parameter_styles ¶

supported_execution_parameter_styles = (
    frozenset(supported_execution_parameter_styles)
    if supported_execution_parameter_styles
    else None
)

type_coercion_map ¶

type_coercion_map = dict(type_coercion_map or {})

has_native_list_expansion ¶

has_native_list_expansion = has_native_list_expansion

replace ¶

replace(**overrides)

DriverParameterProfile ¶

Immutable adapter profile describing parameter defaults.

ParameterProfile ¶

Aggregate metadata describing detected parameters.

TypeCoercionCapabilities ¶

Type coercion capabilities supported by a database adapter.

Processing, Validation & Conversion¶

ParameterProcessor ¶

Parameter processing engine coordinating conversion phases.

process ¶

process(
    sql,
    parameters,
    config,
    dialect=None,
    is_many=False,
    wrap_types=True,
    param_fingerprint=None,
)

process_for_execution ¶

process_for_execution(
    sql,
    parameters,
    config,
    dialect=None,
    is_many=False,
    wrap_types=True,
    parsed_expression=None,
    param_fingerprint=None,
)

Process parameters for execution without parse normalization.

Parameters:

Name	Type	Description	Default
`sql`	`str`	SQL string to process.	required
`parameters`	`ParameterPayload`	Parameter payload.	required
`config`	`ParameterStyleConfig`	Parameter style configuration.	required
`dialect`	`str \| None`	Optional SQL dialect.	`None`
`is_many`	`bool`	Whether this is execute_many.	`False`
`wrap_types`	`bool`	Whether to wrap parameters with type metadata.	`True`
`parsed_expression`	`Any`	Pre-parsed SQLGlot expression to preserve through pipeline.	`None`
`param_fingerprint`	`Any \| None`	Pre-computed parameter fingerprint for cache key.	`None`

Returns:

Type	Description
`ParameterProcessingResult`	ParameterProcessingResult with execution SQL and parameters.

clear_cache ¶

clear_cache()

Clear cached processing results and reset stats.

cache_stats ¶

cache_stats()

Return cache statistics for parameter processing.

ParameterConverter ¶

Parameter style conversion helper.

convert_placeholder_style ¶

convert_placeholder_style(
    sql,
    parameters,
    target_style,
    is_many=False,
    *,
    dialect=None,
    strict_named_parameters=True,
    param_info=None,
    precomputed_plan=None,
)

ParameterValidator ¶

Extracts placeholder metadata and dialect compatibility information.

extract_parameters ¶

extract_parameters(sql)

Extract ordered parameter metadata from SQL text.

ParameterProcessingResult ¶

Return container for parameter processing output.

ParameterInfo ¶

Metadata describing a single detected SQL parameter.

ParameterDeclaration ¶

A single parameter declared in a SQL file header.

Typed Parameters & Input Converters¶

TypedParameter ¶

Wrapper that preserves original parameter type information.

ParamTypeMatcher ¶

ParamTypeMatcher = type | tuple[type, ...] | Callable[[object], bool]

wrap_with_type ¶

wrap_with_type(value, semantic_name=None)

Wrap value with :class:TypedParameter if it benefits downstream processing.

register_param_type ¶

register_param_type(name, py_type)

Register or override a declared-type-string matcher.

Parameters:

Name	Type	Description	Default
`name`	`str`	The declared type string as written in `-- param:` (case-insensitive).	required
`py_type`	`ParamTypeMatcher`	The Python type, tuple of types, or predicate used for validation.	required

get_driver_profile ¶

get_driver_profile(adapter_key)

Return the registered parameter profile for the specified adapter.

Parameters:

Name	Type	Description	Default
`adapter_key`	`str`	Adapter identifier (case-insensitive).	required

Returns:

Name	Type	Description
`Registered`	`DriverParameterProfile`	class:`DriverParameterProfile` instance.

Raises:

Type	Description
`ImproperConfigurationError`	If the adapter does not have a profile.

register_driver_profile ¶

register_driver_profile(adapter_key, profile, *, allow_override=False)

Register a driver profile under the canonical adapter key.

Parameters:

Name	Type	Description	Default
`adapter_key`	`str`	Adapter identifier (case-insensitive).	required
`profile`	`DriverParameterProfile`	Profile describing parameter behaviour.	required
`allow_override`	`bool`	Whether to replace an existing entry.	`False`

Raises:

Type	Description
`ImproperConfigurationError`	If attempting to register a duplicate profile.

BaseInputConverter ¶

Base class for converting Python params to database format.