Type Converters¶

Output and input type converters for transforming database values. Used by drivers to convert between Python types and database-native representations.

Base Classes¶

class sqlspec.core.type_converter.BaseTypeConverter[source]¶

Bases: object

Universal type detection and conversion for all adapters.

detect_type(value)[source]¶

Detect special types from string values.

Parameters:: value¶ (str) – String value to analyze.
Return type:: str | None
Returns:: Type name if detected, None otherwise.

convert_value(value, detected_type)[source]¶

Convert string value to appropriate Python type.

Parameters:

value¶ (str) – String value to convert.
detected_type¶ (str) – Detected type name.

Return type:

typing.Any

Returns:

Converted value in appropriate Python type.

convert_if_detected(value)[source]¶

Convert value only if special type detected, else return original.

Parameters:: value¶ (typing.Any) – Value to potentially convert.
Return type:: typing.Any
Returns:: Converted value if special type detected, original value otherwise.

class sqlspec.core.type_converter.CachedOutputConverter[source]¶

Bases: BaseTypeConverter

Base class for converting database results to Python types.

__init__(special_chars=None, cache_size=5000)[source]¶

Initialize converter with caching.

Parameters:

special_chars¶ (frozenset[str] | None) – Characters that trigger type detection.
cache_size¶ (int) – Maximum entries in LRU cache.

convert(value)[source]¶

Convert value using cached detection and conversion.

Parameters:: value¶ (typing.Any) – Value to potentially convert.
Return type:: typing.Any
Returns:: Converted value if string with special type, original otherwise.

class sqlspec.core.type_converter.BaseInputConverter[source]¶

Bases: object

Base class for converting Python params to database format.

convert_params(params)[source]¶

Convert parameters for database execution.

Parameters:: params¶ (dict[str, typing.Any] | None) – Dictionary of parameters to convert.
Return type:: dict[str, typing.Any] | None
Returns:: Converted parameters dictionary, or None if input was None.

convert_value(value)[source]¶

Convert a single parameter value.

Parameters:: value¶ (typing.Any) – Value to convert.
Return type:: typing.Any
Returns:: Converted value.

Built-in Converters¶

sqlspec.core.type_converter.convert_decimal(value)[source]¶

Convert string to Decimal for precise arithmetic.

Parameters:: value¶ (str) – Decimal string.
Return type:: Decimal
Returns:: Decimal object.

sqlspec.core.type_converter.convert_iso_date(value)[source]¶

Convert ISO date string to date object.

Parameters:: value¶ (str) – ISO date string.
Return type:: date
Returns:: date object.

sqlspec.core.type_converter.convert_iso_datetime(value)[source]¶

Convert ISO 8601 datetime string to datetime object.

Parameters:: value¶ (str) – ISO datetime string.
Return type:: datetime
Returns:: datetime object.

sqlspec.core.type_converter.convert_iso_time(value)[source]¶

Convert ISO time string to time object.

Parameters:: value¶ (str) – ISO time string.
Return type:: time
Returns:: time object.

sqlspec.core.type_converter.convert_json(value)[source]¶

Convert JSON string to Python object.

Parameters:: value¶ (str) – JSON string.
Return type:: typing.Any
Returns:: Decoded Python object.

sqlspec.core.type_converter.convert_uuid(value)[source]¶

Convert UUID string to UUID object.

Parameters:: value¶ (str) – UUID string.
Return type:: UUID
Returns:: UUID object.

sqlspec.core.type_converter.format_datetime_rfc3339(dt)[source]¶

Format datetime as RFC 3339 compliant string.

Parameters:: dt¶ (datetime) – datetime object.
Return type:: str
Returns:: RFC 3339 formatted datetime string.

sqlspec.core.type_converter.parse_datetime_rfc3339(dt_str)[source]¶

Parse RFC 3339 datetime string.

Parameters:: dt_str¶ (str) – RFC 3339 datetime string.
Return type:: datetime
Returns:: datetime object.