sqlspec 0.36.0__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/core/type_converter.py

@@ -0,0 +1,339 @@
+"""Base classes and detection for adapter type conversion."""
+
+import re
+from collections.abc import Callable
+from datetime import date, datetime, time, timezone
+from decimal import Decimal
+from functools import lru_cache
+from typing import Any, Final
+from uuid import UUID
+
+from mypy_extensions import mypyc_attr
+
+from sqlspec._serialization import decode_json
+
+__all__ = (
+    "DEFAULT_CACHE_SIZE",
+    "DEFAULT_SPECIAL_CHARS",
+    "BaseInputConverter",
+    "BaseTypeConverter",
+    "CachedOutputConverter",
+    "convert_decimal",
+    "convert_iso_date",
+    "convert_iso_datetime",
+    "convert_iso_time",
+    "convert_json",
+    "convert_uuid",
+    "format_datetime_rfc3339",
+    "parse_datetime_rfc3339",
+)
+
+DEFAULT_SPECIAL_CHARS: Final[frozenset[str]] = frozenset({"{", "[", "-", ":", "T", "."})
+DEFAULT_CACHE_SIZE: Final[int] = 5000
+DEFAULT_DETECTION_CHARS: Final[frozenset[str]] = frozenset({"{", "[", "-", ":", "T"})
+
+SPECIAL_TYPE_REGEX: Final[re.Pattern[str]] = re.compile(
+    r"^(?:"
+    r"(?P<uuid>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})|"
+    r"(?P<iso_datetime>\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)|"
+    r"(?P<iso_date>\d{4}-\d{2}-\d{2})|"
+    r"(?P<iso_time>\d{2}:\d{2}:\d{2}(?:\.\d+)?)|"
+    r"(?P<json>[\[{].*[\]}])|"
+    r"(?P<ipv4>(?:\d{1,3}\.){3}\d{1,3})|"
+    r"(?P<ipv6>(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4})|"
+    r"(?P<mac>(?:[0-9a-f]{2}:){5}[0-9a-f]{2})"
+    r")$",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def convert_uuid(value: str) -> "UUID":
+    """Convert UUID string to UUID object.
+
+    Args:
+        value: UUID string.
+
+    Returns:
+        UUID object.
+    """
+    return UUID(value)
+
+
+def convert_iso_datetime(value: str) -> "datetime":
+    """Convert ISO 8601 datetime string to datetime object.
+
+    Args:
+        value: ISO datetime string.
+
+    Returns:
+        datetime object.
+    """
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+
+    if " " in value and "T" not in value:
+        value = value.replace(" ", "T")
+
+    return datetime.fromisoformat(value)
+
+
+def convert_iso_date(value: str) -> "date":
+    """Convert ISO date string to date object.
+
+    Args:
+        value: ISO date string.
+
+    Returns:
+        date object.
+    """
+    return date.fromisoformat(value)
+
+
+def convert_iso_time(value: str) -> "time":
+    """Convert ISO time string to time object.
+
+    Args:
+        value: ISO time string.
+
+    Returns:
+        time object.
+    """
+    return time.fromisoformat(value)
+
+
+def convert_json(value: str) -> "Any":
+    """Convert JSON string to Python object.
+
+    Args:
+        value: JSON string.
+
+    Returns:
+        Decoded Python object.
+    """
+    return decode_json(value)
+
+
+def convert_decimal(value: str) -> "Decimal":
+    """Convert string to Decimal for precise arithmetic.
+
+    Args:
+        value: Decimal string.
+
+    Returns:
+        Decimal object.
+    """
+    return Decimal(value)
+
+
+def format_datetime_rfc3339(dt: "datetime") -> str:
+    """Format datetime as RFC 3339 compliant string.
+
+    Args:
+        dt: datetime object.
+
+    Returns:
+        RFC 3339 formatted datetime string.
+    """
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.isoformat()
+
+
+def parse_datetime_rfc3339(dt_str: str) -> "datetime":
+    """Parse RFC 3339 datetime string.
+
+    Args:
+        dt_str: RFC 3339 datetime string.
+
+    Returns:
+        datetime object.
+    """
+    if dt_str.endswith("Z"):
+        dt_str = dt_str[:-1] + "+00:00"
+    return datetime.fromisoformat(dt_str)
+
+
+_TYPE_CONVERTERS: Final[dict[str, Callable[[str], Any]]] = {
+    "uuid": convert_uuid,
+    "iso_datetime": convert_iso_datetime,
+    "iso_date": convert_iso_date,
+    "iso_time": convert_iso_time,
+    "json": convert_json,
+}
+
+
+class _CachedConverter:
+    __slots__ = ("_cached", "_converter", "_special_chars")
+
+    def __init__(self, converter: "CachedOutputConverter", special_chars: "frozenset[str]", cache_size: int) -> None:
+        self._converter = converter
+        self._special_chars = special_chars
+        self._cached = lru_cache(maxsize=cache_size)(self._convert)
+
+    def _convert(self, value: str) -> "Any":
+        if not value or not any(c in value for c in self._special_chars):
+            return value
+        detected_type = self._converter.detect_type(value)
+        if detected_type:
+            return self._converter._convert_detected(value, detected_type)  # pyright: ignore[reportPrivateUsage]
+        return value
+
+    def __call__(self, value: str) -> "Any":
+        return self._cached(value)
+
+
+def _make_cached_converter(
+    converter: "CachedOutputConverter", special_chars: "frozenset[str]", cache_size: int
+) -> "Callable[[str], Any]":
+    """Create a cached conversion function for an output converter.
+
+    Args:
+        converter: The output converter instance to use for type detection/conversion.
+        special_chars: Characters that trigger type detection.
+        cache_size: Maximum entries in the LRU cache.
+
+    Returns:
+        A cached function that converts string values.
+    """
+
+    return _CachedConverter(converter, special_chars, cache_size)
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+class BaseTypeConverter:
+    """Universal type detection and conversion for all adapters."""
+
+    __slots__ = ()
+
+    def detect_type(self, value: str) -> str | None:
+        """Detect special types from string values.
+
+        Args:
+            value: String value to analyze.
+
+        Returns:
+            Type name if detected, None otherwise.
+        """
+        if not isinstance(value, str):  # pyright: ignore
+            return None
+        if not value:
+            return None
+
+        match = SPECIAL_TYPE_REGEX.match(value)
+        if not match:
+            return None
+
+        return next((key for key, match_value in match.groupdict().items() if match_value), None)
+
+    def convert_value(self, value: str, detected_type: str) -> "Any":
+        """Convert string value to appropriate Python type.
+
+        Args:
+            value: String value to convert.
+            detected_type: Detected type name.
+
+        Returns:
+            Converted value in appropriate Python type.
+        """
+        converter = _TYPE_CONVERTERS.get(detected_type)
+        if converter:
+            return converter(value)
+        return value
+
+    def convert_if_detected(self, value: "Any") -> "Any":
+        """Convert value only if special type detected, else return original.
+
+        Args:
+            value: Value to potentially convert.
+
+        Returns:
+            Converted value if special type detected, original value otherwise.
+        """
+        if not isinstance(value, str):
+            return value
+
+        if not any(c in value for c in DEFAULT_DETECTION_CHARS):
+            return value
+
+        detected_type = self.detect_type(value)
+        if detected_type:
+            try:
+                return self.convert_value(value, detected_type)
+            except Exception:
+                return value
+        return value
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+class CachedOutputConverter(BaseTypeConverter):
+    """Base class for converting database results to Python types."""
+
+    __slots__ = ("_convert_cache", "_special_chars")
+
+    def __init__(self, special_chars: "frozenset[str] | None" = None, cache_size: int = DEFAULT_CACHE_SIZE) -> None:
+        """Initialize converter with caching.
+
+        Args:
+            special_chars: Characters that trigger type detection.
+            cache_size: Maximum entries in LRU cache.
+        """
+        super().__init__()
+        self._special_chars = special_chars if special_chars is not None else DEFAULT_SPECIAL_CHARS
+        self._convert_cache = _make_cached_converter(self, self._special_chars, cache_size)
+
+    def _convert_detected(self, value: str, detected_type: str) -> "Any":
+        """Convert value with detected type. Override for adapter-specific logic.
+
+        Args:
+            value: String value to convert.
+            detected_type: Detected type name from detect_type().
+
+        Returns:
+            Converted value, or original value on conversion failure.
+        """
+        try:
+            return self.convert_value(value, detected_type)
+        except Exception:
+            return value
+
+    def convert(self, value: "Any") -> "Any":
+        """Convert value using cached detection and conversion.
+
+        Args:
+            value: Value to potentially convert.
+
+        Returns:
+            Converted value if string with special type, original otherwise.
+        """
+        if not isinstance(value, str):
+            return value
+        return self._convert_cache(value)
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+class BaseInputConverter:
+    """Base class for converting Python params to database format."""
+
+    __slots__ = ()
+
+    def convert_params(self, params: "dict[str, Any] | None") -> "dict[str, Any] | None":
+        """Convert parameters for database execution.
+
+        Args:
+            params: Dictionary of parameters to convert.
+
+        Returns:
+            Converted parameters dictionary, or None if input was None.
+        """
+        return params
+
+    def convert_value(self, value: "Any") -> "Any":
+        """Convert a single parameter value.
+
+        Args:
+            value: Value to convert.
+
+        Returns:
+            Converted value.
+        """
+        return value

sqlspec/data_dictionary/__init__.py

@@ -0,0 +1,22 @@
+"""Centralized data dictionary helpers."""
+
+from sqlspec.data_dictionary._loader import DataDictionaryLoader, get_data_dictionary_loader
+from sqlspec.data_dictionary._registry import (
+    get_dialect_config,
+    list_registered_dialects,
+    normalize_dialect_name,
+    register_dialect,
+)
+from sqlspec.data_dictionary._types import DialectConfig, FeatureFlags, FeatureVersions
+
+__all__ = (
+    "DataDictionaryLoader",
+    "DialectConfig",
+    "FeatureFlags",
+    "FeatureVersions",
+    "get_data_dictionary_loader",
+    "get_dialect_config",
+    "list_registered_dialects",
+    "normalize_dialect_name",
+    "register_dialect",
+)

sqlspec/data_dictionary/_loader.py

@@ -0,0 +1,123 @@
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sqlspec.data_dictionary._registry import get_dialect_config
+from sqlspec.exceptions import SQLFileNotFoundError
+from sqlspec.loader import SQLFileLoader
+
+if TYPE_CHECKING:
+    from sqlspec.core.statement import SQL
+    from sqlspec.data_dictionary._types import DialectConfig
+
+__all__ = ("DataDictionaryLoader", "get_data_dictionary_loader")
+
+
+SQL_DIR = Path(__file__).parent / "sql"
+
+
+class DataDictionaryLoader:
+    """Loads and manages data dictionary SQL for all dialects."""
+
+    __slots__ = ("_loaded_dialects", "_sql_loaders")
+
+    def __init__(self) -> None:
+        """Initialize the data dictionary loader."""
+        self._sql_loaders: dict[str, SQLFileLoader] = {}
+        self._loaded_dialects: set[str] = set()
+
+    def _get_loader(self, dialect: str) -> "SQLFileLoader":
+        """Return or create a SQL loader for a dialect.
+
+        Args:
+            dialect: Dialect name.
+
+        Returns:
+            SQLFileLoader instance.
+        """
+        loader = self._sql_loaders.get(dialect)
+        if loader is None:
+            loader = SQLFileLoader()
+            self._sql_loaders[dialect] = loader
+        return loader
+
+    def _ensure_dialect_loaded(self, dialect: str) -> None:
+        """Lazy load SQL files for a dialect.
+
+        Args:
+            dialect: Dialect name.
+
+        Raises:
+            SQLFileNotFoundError: When the dialect SQL directory is missing.
+        """
+        if dialect in self._loaded_dialects:
+            return
+        dialect_path = SQL_DIR / dialect
+        if not dialect_path.exists():
+            raise SQLFileNotFoundError(str(dialect_path))
+        loader = self._get_loader(dialect)
+        loader.load_sql(dialect_path)
+        self._loaded_dialects.add(dialect)
+
+    def get_query(self, dialect: str, query_name: str) -> "SQL":
+        """Get SQL query for a specific dialect and operation.
+
+        Args:
+            dialect: Dialect name.
+            query_name: Query name to fetch.
+
+        Returns:
+            SQL object for the named query.
+        """
+        self._ensure_dialect_loaded(dialect)
+        loader = self._get_loader(dialect)
+        return loader.get_sql(query_name)
+
+    def get_query_text(self, dialect: str, query_name: str) -> str:
+        """Get raw SQL text for a specific dialect and operation.
+
+        Args:
+            dialect: Dialect name.
+            query_name: Query name to fetch.
+
+        Returns:
+            Raw SQL text for the named query.
+        """
+        self._ensure_dialect_loaded(dialect)
+        loader = self._get_loader(dialect)
+        return loader.get_query_text(query_name)
+
+    def get_dialect_config(self, dialect: str) -> "DialectConfig":
+        """Get static configuration for a dialect.
+
+        Args:
+            dialect: Dialect name.
+
+        Returns:
+            DialectConfig for the dialect.
+        """
+        return get_dialect_config(dialect)
+
+    def list_dialects(self) -> "list[str]":
+        """List available SQL dialects.
+
+        Returns:
+            List of dialect names with SQL directories.
+        """
+        if not SQL_DIR.exists():
+            return []
+        return sorted([path.name for path in SQL_DIR.iterdir() if path.is_dir()])
+
+
+_loader_instance: DataDictionaryLoader | None = None
+
+
+def get_data_dictionary_loader() -> DataDictionaryLoader:
+    """Get singleton data dictionary loader instance.
+
+    Returns:
+        DataDictionaryLoader singleton.
+    """
+    global _loader_instance
+    if _loader_instance is None:
+        _loader_instance = DataDictionaryLoader()
+    return _loader_instance

sqlspec/data_dictionary/_registry.py

@@ -0,0 +1,74 @@
+import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sqlspec.data_dictionary._types import DialectConfig
+
+__all__ = ("get_dialect_config", "list_registered_dialects", "normalize_dialect_name", "register_dialect")
+
+
+_DIALECT_CONFIGS: dict[str, "DialectConfig"] = {}
+_DIALECTS_LOADED = False
+
+DIALECT_ALIASES: dict[str, str] = {"postgresql": "postgres", "mariadb": "mysql", "cockroach": "cockroachdb"}
+
+
+def normalize_dialect_name(dialect: str) -> str:
+    """Normalize dialect names to canonical registry keys.
+
+    Args:
+        dialect: Input dialect name.
+
+    Returns:
+        Canonical dialect key.
+    """
+    normalized = dialect.lower()
+    return DIALECT_ALIASES.get(normalized, normalized)
+
+
+def _load_default_dialects() -> None:
+    """Load built-in dialect configurations."""
+    global _DIALECTS_LOADED
+    if _DIALECTS_LOADED:
+        return
+    importlib.import_module("sqlspec.data_dictionary.dialects")
+    _DIALECTS_LOADED = True  # pyright: ignore
+
+
+def register_dialect(config: "DialectConfig") -> None:
+    """Register a dialect configuration.
+
+    Args:
+        config: Dialect configuration to register.
+    """
+    _DIALECT_CONFIGS[config.name] = config
+
+
+def get_dialect_config(dialect: str) -> "DialectConfig":
+    """Get configuration for a dialect.
+
+    Args:
+        dialect: Dialect name.
+
+    Returns:
+        DialectConfig for the requested dialect.
+
+    Raises:
+        ValueError: When the dialect is unknown.
+    """
+    _load_default_dialects()
+    normalized = normalize_dialect_name(dialect)
+    if normalized not in _DIALECT_CONFIGS:
+        msg = f"Unknown dialect: {dialect}. Available: {', '.join(sorted(_DIALECT_CONFIGS.keys()))}"
+        raise ValueError(msg)
+    return _DIALECT_CONFIGS[normalized]
+
+
+def list_registered_dialects() -> "list[str]":
+    """Return registered dialect names.
+
+    Returns:
+        List of registered dialect names.
+    """
+    _load_default_dialects()
+    return sorted(_DIALECT_CONFIGS.keys())

sqlspec/data_dictionary/_types.py

@@ -0,0 +1,121 @@
+from typing import TYPE_CHECKING, TypedDict, cast
+
+if TYPE_CHECKING:
+    from re import Pattern
+
+    from sqlspec.typing import VersionInfo
+
+__all__ = ("DialectConfig", "FeatureFlags", "FeatureVersions")
+
+
+class FeatureFlags(TypedDict, total=False):
+    """Typed feature flags for data dictionary dialects."""
+
+    supports_arrays: bool
+    supports_clustering: bool
+    supports_cte: bool
+    supports_generators: bool
+    supports_geography: bool
+    supports_in_memory: bool
+    supports_index_clustering: bool
+    supports_interleaved_tables: bool
+    supports_json: bool
+    supports_maps: bool
+    supports_partitioning: bool
+    supports_prepared_statements: bool
+    supports_returning: bool
+    supports_schemas: bool
+    supports_structs: bool
+    supports_transactions: bool
+    supports_upsert: bool
+    supports_uuid: bool
+    supports_window_functions: bool
+
+
+class FeatureVersions(TypedDict, total=False):
+    """Typed feature version requirements for data dictionary dialects."""
+
+    supports_cte: "VersionInfo"
+    supports_json: "VersionInfo"
+    supports_jsonb: "VersionInfo"
+    supports_partitioning: "VersionInfo"
+    supports_returning: "VersionInfo"
+    supports_upsert: "VersionInfo"
+    supports_window_functions: "VersionInfo"
+
+
+class DialectConfig:
+    """Static configuration for a database dialect."""
+
+    __slots__ = (
+        "default_schema",
+        "feature_flags",
+        "feature_versions",
+        "name",
+        "parameter_style",
+        "type_mappings",
+        "version_pattern",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        feature_versions: "FeatureVersions",
+        feature_flags: "FeatureFlags",
+        type_mappings: "dict[str, str]",
+        version_pattern: "Pattern[str]",
+        default_schema: "str | None" = None,
+        parameter_style: str = "named",
+    ) -> None:
+        """Initialize a dialect configuration.
+
+        Args:
+            name: Dialect name used for lookups.
+            feature_versions: Minimum versions required for features.
+            feature_flags: Static boolean feature flags.
+            type_mappings: Logical type to dialect type mapping.
+            version_pattern: Regex used to parse version strings.
+            default_schema: Default schema for dialect.
+            parameter_style: Default parameter style for dialect SQL.
+        """
+        self.name: str = name
+        self.feature_versions: FeatureVersions = feature_versions
+        self.feature_flags: FeatureFlags = feature_flags
+        self.type_mappings: dict[str, str] = type_mappings
+        self.version_pattern: Pattern[str] = version_pattern
+        self.default_schema: str | None = default_schema
+        self.parameter_style: str = parameter_style
+
+    def get_feature_flag(self, feature: str) -> "bool | None":
+        """Return a feature flag value if defined.
+
+        Args:
+            feature: Feature flag name.
+
+        Returns:
+            Feature flag value or None if unknown.
+        """
+        return cast("bool | None", self.feature_flags.get(feature))
+
+    def get_feature_version(self, feature: str) -> "VersionInfo | None":
+        """Return required version for a feature if defined.
+
+        Args:
+            feature: Feature version name.
+
+        Returns:
+            VersionInfo if defined, otherwise None.
+        """
+        return cast("VersionInfo | None", self.feature_versions.get(feature))
+
+    def get_optimal_type(self, logical_type: str) -> str:
+        """Return the dialect-specific type for a logical type.
+
+        Args:
+            logical_type: Logical type name.
+
+        Returns:
+            Dialect-specific type string.
+        """
+        default_type = self.type_mappings.get("text", "TEXT")
+        return self.type_mappings.get(logical_type, default_type)