sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/adapters/spanner/type_converter.py

@@ -0,0 +1,342 @@
+"""Spanner type conversion - output and input handling.
+
+Combines output conversion (database results → Python) and input conversion
+(Python params → Spanner format) in a single module. Designed for mypyc
+compilation with no nested functions.
+
+Output conversion handles:
+- UUID detection and conversion from strings/bytes
+- JSON detection and deserialization
+
+Input conversion handles:
+- UUID → base64-encoded bytes
+- bytes → base64-encoded bytes
+- datetime timezone awareness
+- dict/list → JsonObject wrapping
+- param_types inference
+"""
+
+import base64
+from datetime import date, datetime, timezone
+from typing import TYPE_CHECKING, Any, cast
+from uuid import UUID
+
+from sqlspec._typing import UUID_UTILS_INSTALLED
+from sqlspec.core.type_converter import CachedOutputConverter, convert_uuid
+from sqlspec.utils.serializers import from_json
+from sqlspec.utils.type_converters import should_json_encode_sequence
+
+_UUID_TYPES: "tuple[type[Any], ...]" = (UUID,)
+if UUID_UTILS_INSTALLED:
+    try:
+        import uuid_utils as _uuid_utils  # pyright: ignore[reportMissingImports]
+
+        _UUID_TYPES = (UUID, _uuid_utils.UUID)
+    except ImportError:
+        pass
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sqlspec.protocols import SpannerParamTypesProtocol
+
+__all__ = (
+    "SPANNER_SPECIAL_CHARS",
+    "SpannerOutputConverter",
+    "bytes_to_spanner",
+    "coerce_params_for_spanner",
+    "infer_spanner_param_types",
+    "spanner_json",
+    "spanner_to_bytes",
+    "spanner_to_uuid",
+    "uuid_to_spanner",
+)
+
+SPANNER_SPECIAL_CHARS: "frozenset[str]" = frozenset({"{", "[", "-", ":", "T", "."})
+UUID_BYTE_LENGTH: int = 16
+_SPANNER_PARAM_TYPES: "SpannerParamTypesProtocol | None" = None
+_JSON_OBJECT_TYPE: "type[Any] | None" = None
+
+
+def _get_param_types() -> "SpannerParamTypesProtocol":
+    global _SPANNER_PARAM_TYPES
+    if _SPANNER_PARAM_TYPES is None:
+        from google.cloud.spanner_v1 import param_types
+
+        _SPANNER_PARAM_TYPES = cast("SpannerParamTypesProtocol", param_types)
+    return _SPANNER_PARAM_TYPES
+
+
+def _get_json_object_type() -> "type[Any]":
+    global _JSON_OBJECT_TYPE
+    if _JSON_OBJECT_TYPE is None:
+        from google.cloud.spanner_v1 import JsonObject
+
+        _JSON_OBJECT_TYPE = JsonObject
+    return _JSON_OBJECT_TYPE
+
+
+class SpannerOutputConverter(CachedOutputConverter):
+    """Spanner-specific output conversion with UUID and JSON support.
+
+    Extends CachedOutputConverter with Spanner-specific functionality
+    including UUID bytes handling and JSON deserialization.
+    """
+
+    __slots__ = ("_enable_uuid_conversion", "_json_deserializer")
+
+    def __init__(
+        self,
+        cache_size: int = 5000,
+        enable_uuid_conversion: bool = True,
+        json_deserializer: "Callable[[str], Any] | None" = None,
+    ) -> None:
+        """Initialize converter with Spanner-specific options.
+
+        Args:
+            cache_size: Maximum number of string values to cache (default: 5000)
+            enable_uuid_conversion: Enable automatic UUID conversion (default: True)
+            json_deserializer: Custom JSON deserializer (default: from_json)
+        """
+        super().__init__(special_chars=SPANNER_SPECIAL_CHARS, cache_size=cache_size)
+        self._enable_uuid_conversion = enable_uuid_conversion
+        self._json_deserializer = json_deserializer if json_deserializer is not None else from_json
+
+    def _convert_detected(self, value: str, detected_type: str) -> Any:
+        """Convert value with Spanner-specific handling.
+
+        Args:
+            value: String value to convert.
+            detected_type: Detected type name.
+
+        Returns:
+            Converted value according to Spanner requirements.
+        """
+        if detected_type == "uuid":
+            if not self._enable_uuid_conversion:
+                return value
+            try:
+                return convert_uuid(value)
+            except ValueError:
+                return value
+        if detected_type == "json":
+            try:
+                return self._json_deserializer(value)
+            except (ValueError, TypeError):
+                return value
+        return value
+
+    def convert(self, value: Any) -> Any:
+        """Convert value with Spanner-specific byte UUID handling.
+
+        Args:
+            value: Value to potentially convert.
+
+        Returns:
+            Converted value or original value.
+        """
+        if self._enable_uuid_conversion and isinstance(value, bytes) and len(value) == UUID_BYTE_LENGTH:
+            try:
+                return UUID(bytes=value)
+            except ValueError:
+                return value
+
+        if not isinstance(value, str):
+            return value
+        return self._convert_cache(value)
+
+
+def _json_param_type() -> Any:
+    """Get Spanner JSON param type with fallback to STRING.
+
+    Returns:
+        JSON param type or STRING as fallback.
+    """
+    param_types = _get_param_types()
+    try:
+        return param_types.JSON
+    except AttributeError:
+        return param_types.STRING
+
+
+def bytes_to_spanner(value: "bytes | None") -> "bytes | None":
+    """Convert Python bytes to Spanner BYTES format.
+
+    The Spanner Python client requires base64-encoded bytes when
+    param_types.BYTES is specified.
+
+    Args:
+        value: Python bytes or None.
+
+    Returns:
+        Base64-encoded bytes or None.
+    """
+    if value is None:
+        return None
+    return base64.b64encode(value)
+
+
+def spanner_to_bytes(value: Any) -> "bytes | None":
+    """Convert Spanner BYTES result to Python bytes.
+
+    Handles both raw bytes and base64-encoded bytes.
+
+    Args:
+        value: Value from Spanner (bytes or None).
+
+    Returns:
+        Python bytes or None.
+    """
+    if value is None:
+        return None
+    if isinstance(value, (bytes, str)):
+        return base64.b64decode(value)
+    return None
+
+
+def uuid_to_spanner(value: UUID) -> bytes:
+    """Convert Python UUID to 16-byte binary for Spanner BYTES(16).
+
+    Args:
+        value: Python UUID object.
+
+    Returns:
+        16-byte binary representation (RFC 4122 big-endian).
+    """
+    return value.bytes
+
+
+def spanner_to_uuid(value: "bytes | None") -> "UUID | bytes | None":
+    """Convert 16-byte binary from Spanner to Python UUID.
+
+    Falls back to bytes if value is not valid UUID format.
+
+    Args:
+        value: 16-byte binary from Spanner or None.
+
+    Returns:
+        Python UUID if valid, original bytes if invalid, None if NULL.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, bytes):
+        return None
+    if len(value) != UUID_BYTE_LENGTH:
+        return value
+    try:
+        return UUID(bytes=value)
+    except (ValueError, TypeError):
+        return value
+
+
+def spanner_json(value: Any) -> Any:
+    """Wrap JSON values for Spanner JSON parameters.
+
+    Args:
+        value: JSON-compatible value (dict, list, tuple, or scalar).
+
+    Returns:
+        JsonObject wrapper when available, otherwise the original value.
+    """
+    json_type = _get_json_object_type()
+    if isinstance(value, json_type):
+        return value
+    return json_type(value)
+
+
+def coerce_params_for_spanner(
+    params: "dict[str, Any] | None", json_serializer: "Callable[[Any], str] | None" = None
+) -> "dict[str, Any] | None":
+    """Coerce Python types to Spanner-compatible formats.
+
+    Handles:
+    - UUID → base64-encoded bytes
+    - bytes → base64-encoded bytes
+    - datetime timezone awareness
+    - dict → JsonObject for JSON columns
+    - nested sequences → JsonObject for JSON arrays
+
+    Args:
+        params: Parameter dictionary or None.
+        json_serializer: Optional JSON serializer (unused for JSON dicts).
+
+    Returns:
+        Coerced parameter dictionary or None.
+    """
+    if params is None:
+        return None
+
+    json_object_type = _get_json_object_type()
+    coerced: dict[str, Any] = {}
+    for key, value in params.items():
+        if isinstance(value, _UUID_TYPES):
+            std_uuid = value if isinstance(value, UUID) else UUID(bytes=value.bytes)
+            coerced[key] = bytes_to_spanner(uuid_to_spanner(std_uuid))
+        elif isinstance(value, bytes):
+            coerced[key] = bytes_to_spanner(value)
+        elif isinstance(value, datetime) and value.tzinfo is None:
+            coerced[key] = value.replace(tzinfo=timezone.utc)
+        elif isinstance(value, json_object_type):
+            coerced[key] = value
+        elif isinstance(value, dict):
+            coerced[key] = spanner_json(value)
+        elif isinstance(value, (list, tuple)):
+            if should_json_encode_sequence(value):
+                coerced[key] = spanner_json(list(value))
+            else:
+                coerced[key] = list(value) if isinstance(value, tuple) else value
+        else:
+            coerced[key] = value
+    return coerced
+
+
+def infer_spanner_param_types(params: "dict[str, Any] | None") -> "dict[str, Any]":
+    """Infer Spanner param_types from Python values.
+
+    Args:
+        params: Parameter dictionary or None.
+
+    Returns:
+        Dictionary mapping parameter names to Spanner param_types.
+    """
+    if not params:
+        return {}
+
+    param_types = _get_param_types()
+    json_object_type = _get_json_object_type()
+    types: dict[str, Any] = {}
+    json_type = _json_param_type()
+    for key, value in params.items():
+        if isinstance(value, bool):
+            types[key] = param_types.BOOL
+        elif isinstance(value, int):
+            types[key] = param_types.INT64
+        elif isinstance(value, float):
+            types[key] = param_types.FLOAT64
+        elif isinstance(value, str):
+            types[key] = param_types.STRING
+        elif isinstance(value, bytes):
+            types[key] = param_types.BYTES
+        elif isinstance(value, datetime):
+            types[key] = param_types.TIMESTAMP
+        elif isinstance(value, date):
+            types[key] = param_types.DATE
+        elif isinstance(value, (dict, json_object_type)):
+            types[key] = json_type
+        elif isinstance(value, (list, tuple)):
+            if should_json_encode_sequence(value):
+                types[key] = json_type
+                continue
+            sequence = list(value)
+            if not sequence:
+                continue
+            first = sequence[0]
+            if isinstance(first, int):
+                types[key] = param_types.Array(param_types.INT64)
+            elif isinstance(first, str):
+                types[key] = param_types.Array(param_types.STRING)
+            elif isinstance(first, float):
+                types[key] = param_types.Array(param_types.FLOAT64)
+            elif isinstance(first, bool):
+                types[key] = param_types.Array(param_types.BOOL)
+    return types

sqlspec/adapters/sqlite/__init__.py

@@ -0,0 +1,19 @@
+"""SQLite adapter for SQLSpec."""
+
+from sqlspec.adapters.sqlite._typing import SqliteConnection, SqliteCursor
+from sqlspec.adapters.sqlite.config import SqliteConfig, SqliteConnectionParams, SqliteDriverFeatures
+from sqlspec.adapters.sqlite.core import default_statement_config
+from sqlspec.adapters.sqlite.driver import SqliteDriver, SqliteExceptionHandler
+from sqlspec.adapters.sqlite.pool import SqliteConnectionPool
+
+__all__ = (
+    "SqliteConfig",
+    "SqliteConnection",
+    "SqliteConnectionParams",
+    "SqliteConnectionPool",
+    "SqliteCursor",
+    "SqliteDriver",
+    "SqliteDriverFeatures",
+    "SqliteExceptionHandler",
+    "default_statement_config",
+)

sqlspec/adapters/sqlite/_typing.py

@@ -0,0 +1,123 @@
+"""SQLite adapter type definitions.
+
+This module contains type aliases and classes that are excluded from mypyc
+compilation to avoid ABI boundary issues.
+"""
+
+import contextlib
+import sqlite3
+from typing import TYPE_CHECKING, Any
+
+_SqliteConnection = sqlite3.Connection
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from types import TracebackType
+    from typing import TypeAlias
+
+    from sqlspec.adapters.sqlite.driver import SqliteDriver
+    from sqlspec.core import StatementConfig
+
+    SqliteConnection: TypeAlias = _SqliteConnection
+    SqliteRawCursor: TypeAlias = sqlite3.Cursor
+
+if not TYPE_CHECKING:
+    SqliteConnection = _SqliteConnection
+    SqliteRawCursor = sqlite3.Cursor
+
+
+class SqliteCursor:
+    """Context manager for SQLite cursor management.
+
+    Provides automatic cursor creation and cleanup for SQLite database operations.
+    """
+
+    __slots__ = ("connection", "cursor")
+
+    def __init__(self, connection: "SqliteConnection") -> None:
+        """Initialize cursor manager.
+
+        Args:
+            connection: SQLite database connection
+        """
+        self.connection = connection
+        self.cursor: SqliteRawCursor | None = None
+
+    def __enter__(self) -> "SqliteRawCursor":
+        """Create and return a new cursor.
+
+        Returns:
+            Active SQLite cursor object
+        """
+        self.cursor = self.connection.cursor()
+        return self.cursor
+
+    def __exit__(self, *_: Any) -> None:
+        """Clean up cursor resources.
+
+        Args:
+            exc_type: Exception type if an exception occurred
+            exc_val: Exception value if an exception occurred
+            exc_tb: Exception traceback if an exception occurred
+        """
+        if self.cursor is not None:
+            with contextlib.suppress(Exception):
+                self.cursor.close()
+
+
+class SqliteSessionContext:
+    """Sync context manager for SQLite sessions.
+
+    This class is intentionally excluded from mypyc compilation to avoid ABI
+    boundary issues. It receives callables from uncompiled config classes and
+    instantiates compiled Driver objects, acting as a bridge between compiled
+    and uncompiled code.
+
+    Uses callable-based connection management to decouple from config implementation.
+    """
+
+    __slots__ = (
+        "_acquire_connection",
+        "_connection",
+        "_driver",
+        "_driver_features",
+        "_prepare_driver",
+        "_release_connection",
+        "_statement_config",
+    )
+
+    def __init__(
+        self,
+        acquire_connection: "Callable[[], Any]",
+        release_connection: "Callable[[Any], Any]",
+        statement_config: "StatementConfig",
+        driver_features: "dict[str, Any]",
+        prepare_driver: "Callable[[SqliteDriver], SqliteDriver]",
+    ) -> None:
+        self._acquire_connection = acquire_connection
+        self._release_connection = release_connection
+        self._statement_config = statement_config
+        self._driver_features = driver_features
+        self._prepare_driver = prepare_driver
+        self._connection: Any = None
+        self._driver: SqliteDriver | None = None
+
+    def __enter__(self) -> "SqliteDriver":
+        from sqlspec.adapters.sqlite.driver import SqliteDriver
+
+        self._connection = self._acquire_connection()
+        self._driver = SqliteDriver(
+            connection=self._connection, statement_config=self._statement_config, driver_features=self._driver_features
+        )
+        return self._prepare_driver(self._driver)
+
+    def __exit__(
+        self, exc_type: "type[BaseException] | None", exc_val: "BaseException | None", exc_tb: "TracebackType | None"
+    ) -> "bool | None":
+        if self._connection is not None:
+            self._release_connection(self._connection)
+            self._connection = None
+        return None
+
+
+__all__ = ("SqliteConnection", "SqliteCursor", "SqliteRawCursor", "SqliteSessionContext")

sqlspec/adapters/sqlite/adk/__init__.py

@@ -0,0 +1,5 @@
+"""SQLite ADK integration for Google Agent Development Kit."""
+
+from sqlspec.adapters.sqlite.adk.store import SqliteADKMemoryStore, SqliteADKStore
+
+__all__ = ("SqliteADKMemoryStore", "SqliteADKStore")