Parameters

Type-safe parameter processing with automatic style detection and conversion. Supports QMARK (?), NAMED (:name), NUMERIC ($1), and FORMAT (%s) styles.

ParameterProcessor

class sqlspec.core.parameters._processor.ParameterProcessor

Bases: object

Parameter processing engine coordinating conversion phases.

__init__(*, converter=None, validator=None, cache_max_size=None, validator_cache_max_size=None)

clear_cache()

Clear cached processing results and reset stats.

Return type:

None

cache_stats()

Return cache statistics for parameter processing.

Return type:

dict[str, int]

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:

• sql (str) – SQL string to process.

• parameters (sqlspec.core.parameters.ParameterPayload) – Parameter payload.

• config (ParameterStyleConfig) – Parameter style configuration.

• dialect (str | None) – Optional SQL dialect.

• is_many (bool) – Whether this is execute_many.

• wrap_types (bool) – Whether to wrap parameters with type metadata.

• parsed_expression (Any) – Pre-parsed SQLGlot expression to preserve through pipeline.

• param_fingerprint (Any | None) – Pre-computed parameter fingerprint for cache key.

Return type:

ParameterProcessingResult

Returns:

ParameterProcessingResult with execution SQL and parameters.

ParameterConverter

class sqlspec.core.parameters._converter.ParameterConverter

Bases: object

Parameter style conversion helper.

__init__(validator=None)

ParameterValidator

class sqlspec.core.parameters._validator.ParameterValidator

Bases: object

Extracts placeholder metadata and dialect compatibility information.

__init__(cache_max_size=5000)

set_cache_max_size(cache_max_size)

Update the maximum cache size for parameter metadata.

Return type:

None

clear_cache()

Clear cached parameter metadata and reset stats.

Return type:

None

cache_stats()

Return cache statistics.

Return type:

dict[str, int]

extract_parameters(sql)

Extract ordered parameter metadata from SQL text.

Return type:

list[ParameterInfo]

Types

class sqlspec.core.parameters._types.ParameterStyle

Bases: str, Enum

Enumeration of supported SQL parameter placeholder styles.

__new__(value)

class sqlspec.core.parameters._types.ParameterStyleConfig

Bases: object

Configuration describing parameter behaviour for a statement.

__init__(default_parameter_style, supported_parameter_styles=None, supported_execution_parameter_styles=None, default_execution_parameter_style=None, type_coercion_map=None, has_native_list_expansion=False, needs_static_script_compilation=False, allow_mixed_parameter_styles=False, preserve_parameter_format=True, preserve_original_params_for_many=False, output_transformer=None, ast_transformer=None, json_serializer=None, json_deserializer=None, strict_named_parameters=True)

hash()

Return the hash value for caching compatibility.

Return type:

int

Returns:

Hash value matching hash() output for this config.

with_json_serializers(serializer, *, tuple_strategy='list', deserializer=None)

Return a copy configured with JSON serializers for complex parameters.

class sqlspec.core.parameters._types.TypedParameter

Bases: object

Wrapper that preserves original parameter type information.

__init__(value, original_type=None, semantic_name=None)

class sqlspec.core.parameters._types.ParameterInfo

Bases: object

Metadata describing a single detected SQL parameter.

__init__(name, style, position, ordinal, placeholder_text)

class sqlspec.core.parameters._types.DriverParameterProfile

Bases: object

Immutable adapter profile describing parameter defaults.

__init__(name, default_style, supported_styles, default_execution_style, supported_execution_styles, has_native_list_expansion, preserve_parameter_format, needs_static_script_compilation, allow_mixed_parameter_styles, preserve_original_params_for_many, json_serializer_strategy, custom_type_coercions=None, default_output_transformer=None, default_ast_transformer=None, extras=None, default_dialect=None, statement_kwargs=None, strict_named_parameters=True)

class sqlspec.core.parameters._types.ParameterProfile

Bases: object

Aggregate metadata describing detected parameters.

__init__(parameters=None)

class sqlspec.core.parameters._types.ParameterProcessingResult

Bases: object

Return container for parameter processing output.

__init__(sql, parameters, parameter_profile, sqlglot_sql=None, parsed_expression=None, input_named_parameters=None, applied_wrap_types=False)