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.ParameterProcessor[source]#

Bases: object

Parameter processing engine coordinating conversion phases.

__init__(*, converter=None, validator=None, cache_max_size=None, validator_cache_max_size=None)[source]#
clear_cache()[source]#

Clear cached processing results and reset stats.

Return type:

None

cache_stats()[source]#

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)[source]#

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.

transform_cached_parameters(parameters, cached_profile, config, *, input_named_parameters, is_many, apply_wrap_types)[source]#

Apply parameter transformations for a cache hit.

Uses cached metadata to efficiently transform parameters without re-parsing SQL. This ensures new parameter values undergo the same transformations as the original cached request (type wrapping, coercion, named-to-positional mapping).

Parameters:

  • parameters (sqlspec.core.parameters.ParameterPayload) -- New parameter payload to transform.

  • cached_profile (ParameterProfile) -- Cached ParameterProfile with execution parameter metadata.

  • config (ParameterStyleConfig) -- Parameter style configuration.

  • input_named_parameters (tuple[str, ...]) -- Cached input named parameter order.

  • is_many (bool) -- Whether this is execute_many.

  • apply_wrap_types (bool) -- Whether to wrap parameters with type metadata.

Return type:

dict[str, typing.Any] | list[typing.Any] | tuple[typing.Any, ...] | object | None

Returns:

Transformed parameters matching the cached SQL's placeholder format.

ParameterConverter#

class sqlspec.core.parameters.ParameterConverter[source]#

Bases: object

Parameter style conversion helper.

__init__(validator=None)[source]#

ParameterValidator#

class sqlspec.core.parameters.ParameterValidator[source]#

Bases: object

Extracts placeholder metadata and dialect compatibility information.

__init__(cache_max_size=5000)[source]#
set_cache_max_size(cache_max_size)[source]#

Update the maximum cache size for parameter metadata.

Return type:

None

clear_cache()[source]#

Clear cached parameter metadata and reset stats.

Return type:

None

cache_stats()[source]#

Return cache statistics.

Return type:

dict[str, int]

extract_parameters(sql)[source]#

Extract ordered parameter metadata from SQL text.

Return type:

list[ParameterInfo]

Types and Profiles#

class sqlspec.core.parameters.ParameterStyle[source]#

Bases: str, Enum

Enumeration of supported SQL parameter placeholder styles.

__new__(value)#
class sqlspec.core.parameters.ParameterStyleConfig[source]#

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)[source]#
__reduce__()[source]#

Reconstruct via the public ctor so copy/pickle work on mypyc native classes.

Return type:

tuple[typing.Any, ...]

with_json_serializers(serializer, *, tuple_strategy='list', deserializer=None)[source]#

Return a copy configured with JSON serializers for complex parameters.

Return type:

ParameterStyleConfig

class sqlspec.core.parameters.TypedParameter[source]#

Bases: object

Wrapper that preserves original parameter type information.

__init__(value, original_type=None, semantic_name=None)[source]#
__reduce__()[source]#

Reconstruct via TypedParameter(value, original_type, semantic_name).

Return type:

tuple[typing.Any, ...]

class sqlspec.core.parameters.ParameterInfo[source]#

Bases: object

Metadata describing a single detected SQL parameter.

__init__(name, style, position, ordinal, placeholder_text)[source]#
__reduce__()[source]#

Reconstruct via ParameterInfo(name, style, position, ordinal, placeholder_text).

Return type:

tuple[typing.Any, ...]

class sqlspec.core.parameters.DriverParameterProfile[source]#

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)[source]#
__reduce__()[source]#

Reconstruct via the public ctor so copy/pickle work on mypyc native classes.

Return type:

tuple[typing.Any, ...]

class sqlspec.core.parameters.ParameterProfile[source]#

Bases: object

Aggregate metadata describing detected parameters.

__init__(parameters=None)[source]#
__reduce__()[source]#

Reconstruct via ParameterProfile(parameters) — fully rebuilds derived state.

Return type:

tuple[typing.Any, ...]

class sqlspec.core.parameters.ParameterProcessingResult[source]#

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)[source]#
__reduce__()[source]#

Reconstruct via the public ctor so copy/pickle work on mypyc native classes.

Return type:

tuple[typing.Any, ...]

class sqlspec.core.parameters.ParameterDeclaration[source]#

Bases: object

A single parameter declared in a SQL file header.

__init__(name, type_str, description=None, *, required=True)[source]#

Profile Management#

sqlspec.core.parameters.get_driver_profile(adapter_key)[source]#

Return the registered parameter profile for the specified adapter.

Parameters:

adapter_key (str) -- Adapter identifier (case-insensitive).

Return type:

DriverParameterProfile

Returns:

Registered DriverParameterProfile instance.

Raises:

ImproperConfigurationError -- If the adapter does not have a profile.

sqlspec.core.parameters.register_driver_profile(adapter_key, profile, *, allow_override=False)[source]#

Register a driver profile under the canonical adapter key.

Parameters:

  • adapter_key (str) -- Adapter identifier (case-insensitive).

  • profile (DriverParameterProfile) -- Profile describing parameter behaviour.

  • allow_override (bool) -- Whether to replace an existing entry.

Raises:

ImproperConfigurationError -- If attempting to register a duplicate profile.

Return type:

None

sqlspec.core.parameters.build_statement_config_from_profile(profile, *, parameter_overrides=None, statement_overrides=None, json_serializer=None, json_deserializer=None)[source]#

Construct a StatementConfig seeded from a driver profile.

Parameters:

  • profile (DriverParameterProfile) -- Driver profile providing default parameter behaviour.

  • parameter_overrides (dict[str, typing.Any] | None) -- Optional overrides for parameter config fields.

  • statement_overrides (dict[str, typing.Any] | None) -- Optional overrides for resulting statement config.

  • json_serializer (typing.Callable[[MyTypeAliasForwardRef('typing.Any')], str] | None) -- Optional JSON serializer supplied by the adapter.

  • json_deserializer (typing.Callable[[<class 'str'>], typing.Any] | None) -- Optional JSON deserializer supplied by the adapter.

Return type:

StatementConfig

Returns:

New StatementConfig instance with merged configuration.

Parameter Helpers#

sqlspec.core.parameters.validate_parameter_alignment(parameter_profile, parameters, *, is_many=False)[source]#

Ensure provided parameters align with detected placeholders.

Parameters:

  • parameter_profile (ParameterProfile | None) -- Placeholder metadata extracted from the statement.

  • parameters (Any) -- Parameter payload the adapter will execute with.

  • is_many (bool) -- Whether the call explicitly targets execute_many.

Raises:

SQLSpecError -- If counts or identifiers differ between placeholders and payload.

Return type:

None

sqlspec.core.parameters.normalize_parameter_key(key)[source]#

Normalize a parameter key into an (kind, value) tuple.

Parameters:

key (Any) -- Key supplied by the caller (index, name, or adapter-specific token).

Return type:

tuple[str, int | str]

Returns:

Tuple identifying the key type and canonical value for alignment checks.

sqlspec.core.parameters.is_iterable_parameters(obj)[source]#

Return True when the object behaves like an iterable parameter payload.

Return type:

bool

sqlspec.core.parameters.wrap_with_type(value, semantic_name=None)[source]#

Wrap value with TypedParameter if it benefits downstream processing.

Return type:

Any

sqlspec.core.parameters.register_param_type(name, py_type)[source]#

Register or override a declared-type-string matcher.

Parameters:

  • name (str) -- The declared type string as written in -- param: (case-insensitive).

  • py_type (type | tuple[type, ...] | Callable[[object], bool]) -- The Python type, tuple of types, or predicate used for validation.

Return type:

None

sqlspec.core.parameters.resolve_param_type(type_str)[source]#

Resolve a declared type string to a matcher, or None if unknown.

Unknown type strings are documentation-only and skipped during validation. The declared string is looked up, never evaluated. Parameterized containers (list[int]) resolve to their origin type (list).

Parameters:

type_str (str) -- The declared type string from a -- param: directive.

Return type:

type | tuple[type, ...] | Callable[[object], bool] | None

Returns:

The resolved matcher, or None when not in the registry.

sqlspec.core.parameters.matches_param_type(type_str, value)[source]#

Return whether a value satisfies a declared type string.

Unknown type strings are documentation-only and always match. None is handled by the driver as SQL NULL before this helper is called.

Return type:

bool