sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/adapters/oracledb/type_converter.py

@@ -0,0 +1,211 @@
+"""Oracle-specific type conversion with LOB optimization.
+
+Provides specialized type handling for Oracle databases, including
+efficient LOB (Large Object) processing and JSON storage detection.
+"""
+
+import array
+import re
+from datetime import datetime
+from typing import Any, Final
+
+from sqlspec.core.type_converter import CachedOutputConverter
+from sqlspec.typing import NUMPY_INSTALLED
+from sqlspec.utils.sync_tools import ensure_async_
+from sqlspec.utils.type_guards import is_readable
+
+__all__ = ("ORACLE_JSON_STORAGE_REGEX", "ORACLE_SPECIAL_CHARS", "OracleOutputConverter")
+
+ORACLE_JSON_STORAGE_REGEX: Final[re.Pattern[str]] = re.compile(
+    r"^(?:"
+    r"(?P<json_type>JSON)|"
+    r"(?P<blob_oson>BLOB.*OSON)|"
+    r"(?P<blob_json>BLOB.*JSON)|"
+    r"(?P<clob_json>CLOB.*JSON)"
+    r")$",
+    re.IGNORECASE,
+)
+
+ORACLE_SPECIAL_CHARS: Final[frozenset[str]] = frozenset({"{", "[", "-", ":", "T", "."})
+
+
+class OracleOutputConverter(CachedOutputConverter):
+    """Oracle-specific output conversion with LOB optimization.
+
+    Extends CachedOutputConverter with Oracle-specific functionality
+    including streaming LOB support and JSON storage type detection.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, cache_size: int = 5000) -> None:
+        """Initialize converter with Oracle-specific options.
+
+        Args:
+            cache_size: Maximum number of string values to cache (default: 5000)
+        """
+        super().__init__(special_chars=ORACLE_SPECIAL_CHARS, cache_size=cache_size)
+
+    def _convert_detected(self, value: str, detected_type: str) -> Any:
+        """Convert value with Oracle-specific handling.
+
+        Args:
+            value: String value to convert.
+            detected_type: Detected type name.
+
+        Returns:
+            Converted value, or original on failure.
+        """
+        try:
+            return self.convert_value(value, detected_type)
+        except Exception:
+            return value
+
+    async def process_lob(self, value: Any) -> Any:
+        """Process Oracle LOB objects efficiently.
+
+        Args:
+            value: Potential LOB object or regular value.
+
+        Returns:
+            LOB content if value is a LOB, original value otherwise.
+        """
+        if not is_readable(value):
+            return value
+
+        read_func = ensure_async_(value.read)
+        return await read_func()
+
+    def detect_json_storage_type(self, column_info: "dict[str, Any]") -> bool:
+        """Detect if column stores JSON data.
+
+        Args:
+            column_info: Database column metadata.
+
+        Returns:
+            True if column is configured for JSON storage.
+        """
+        type_name = column_info.get("type_name", "").upper()
+        return bool(ORACLE_JSON_STORAGE_REGEX.match(type_name))
+
+    def format_datetime_for_oracle(self, dt: datetime) -> str:
+        """Format datetime for Oracle TO_DATE function.
+
+        Args:
+            dt: datetime object to format.
+
+        Returns:
+            Oracle TO_DATE SQL expression.
+        """
+        return f"TO_DATE('{dt.strftime('%Y-%m-%d %H:%M:%S')}', 'YYYY-MM-DD HH24:MI:SS')"
+
+    def handle_large_lob(self, lob_obj: Any, chunk_size: int = 1024 * 1024) -> bytes:
+        """Handle large LOB objects with streaming.
+
+        Args:
+            lob_obj: Oracle LOB object.
+            chunk_size: Size of chunks to read at a time.
+
+        Returns:
+            Complete LOB content as bytes.
+        """
+        if not is_readable(lob_obj):
+            return lob_obj if isinstance(lob_obj, bytes) else str(lob_obj).encode("utf-8")
+
+        first_chunk = lob_obj.read(chunk_size)
+        if not first_chunk:
+            return b""
+
+        if isinstance(first_chunk, bytes):
+            chunks: list[bytes] = [first_chunk]
+            while True:
+                chunk = lob_obj.read(chunk_size)
+                if not chunk:
+                    break
+                if isinstance(chunk, bytes):
+                    chunks.append(chunk)
+                else:
+                    chunks.append(str(chunk).encode("utf-8"))
+            return b"".join(chunks)
+
+        text_chunks: list[str] = [str(first_chunk)]
+        while True:
+            chunk = lob_obj.read(chunk_size)
+            if not chunk:
+                break
+            text_chunks.append(str(chunk))
+        return "".join(text_chunks).encode("utf-8")
+
+    def convert_oracle_value(self, value: Any, column_info: "dict[str, Any]") -> Any:
+        """Convert Oracle-specific value with column context.
+
+        Args:
+            value: Value to convert.
+            column_info: Column metadata for context.
+
+        Returns:
+            Converted value appropriate for the column type.
+        """
+        if is_readable(value):
+            if self.detect_json_storage_type(column_info):
+                content = self.handle_large_lob(value)
+                content_str = content.decode("utf-8") if isinstance(content, bytes) else content
+                return self.convert(content_str)
+            return self.handle_large_lob(value)
+
+        if isinstance(value, str):
+            return self.convert(value)
+
+        return value
+
+    def convert_vector_to_numpy(self, value: Any) -> Any:
+        """Convert Oracle VECTOR to NumPy array.
+
+        Provides manual conversion API for users who need explicit control
+        over vector transformations or have disabled automatic handlers.
+
+        Args:
+            value: Oracle VECTOR value (array.array) or other value.
+
+        Returns:
+            NumPy ndarray if value is array.array and NumPy is installed,
+            otherwise original value.
+        """
+        if not NUMPY_INSTALLED:
+            return value
+
+        if isinstance(value, array.array):
+            from sqlspec.adapters.oracledb._vector_handlers import (  # pyright: ignore[reportPrivateUsage]
+                numpy_converter_out,
+            )
+
+            return numpy_converter_out(value)
+
+        return value
+
+    def convert_numpy_to_vector(self, value: Any) -> Any:
+        """Convert NumPy array to Oracle VECTOR format.
+
+        Provides manual conversion API for users who need explicit control
+        over vector transformations or have disabled automatic handlers.
+
+        Args:
+            value: NumPy ndarray or other value.
+
+        Returns:
+            array.array compatible with Oracle VECTOR if value is ndarray,
+            otherwise original value.
+        """
+        if not NUMPY_INSTALLED:
+            return value
+
+        import numpy as np
+
+        if isinstance(value, np.ndarray):
+            from sqlspec.adapters.oracledb._vector_handlers import (  # pyright: ignore[reportPrivateUsage]
+                numpy_converter_in,
+            )
+
+            return numpy_converter_in(value)
+
+        return value

sqlspec/adapters/psqlpy/__init__.py

@@ -0,0 +1,18 @@
+"""Psqlpy adapter for SQLSpec."""
+
+from sqlspec.adapters.psqlpy._typing import PsqlpyConnection, PsqlpyCursor
+from sqlspec.adapters.psqlpy.config import PsqlpyConfig, PsqlpyConnectionParams, PsqlpyPoolParams
+from sqlspec.adapters.psqlpy.core import default_statement_config
+from sqlspec.adapters.psqlpy.driver import PsqlpyDriver, PsqlpyExceptionHandler
+from sqlspec.dialects import postgres  # noqa: F401
+
+__all__ = (
+    "PsqlpyConfig",
+    "PsqlpyConnection",
+    "PsqlpyConnectionParams",
+    "PsqlpyCursor",
+    "PsqlpyDriver",
+    "PsqlpyExceptionHandler",
+    "PsqlpyPoolParams",
+    "default_statement_config",
+)

sqlspec/adapters/psqlpy/_typing.py

@@ -0,0 +1,121 @@
+"""Psqlpy adapter type definitions.
+
+This module contains type aliases and classes that are excluded from mypyc
+compilation to avoid ABI boundary issues.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from psqlpy import Connection as _PsqlpyConnection
+from psqlpy import Listener as _PsqlpyListener
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from types import TracebackType
+    from typing import TypeAlias
+
+    from sqlspec.adapters.psqlpy.driver import PsqlpyDriver
+    from sqlspec.core import StatementConfig
+
+    PsqlpyConnection: TypeAlias = _PsqlpyConnection
+    PsqlpyListener: TypeAlias = _PsqlpyListener
+
+if not TYPE_CHECKING:
+    PsqlpyConnection = _PsqlpyConnection
+    PsqlpyListener = _PsqlpyListener
+
+
+class PsqlpyCursor:
+    """Context manager for psqlpy cursor management."""
+
+    __slots__ = ("_in_use", "connection")
+
+    def __init__(self, connection: "PsqlpyConnection") -> None:
+        self.connection = connection
+        self._in_use = False
+
+    async def __aenter__(self) -> "PsqlpyConnection":
+        """Enter cursor context.
+
+        Returns:
+            Psqlpy connection object
+        """
+        self._in_use = True
+        return self.connection
+
+    async def __aexit__(self, *_: Any) -> None:
+        """Exit cursor context.
+
+        Args:
+            exc_type: Exception type
+            exc_val: Exception value
+            exc_tb: Exception traceback
+        """
+        self._in_use = False
+
+    def is_in_use(self) -> bool:
+        """Check if cursor is currently in use.
+
+        Returns:
+            True if cursor is in use, False otherwise
+        """
+        return self._in_use
+
+
+class PsqlpySessionContext:
+    """Async context manager for psqlpy 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 | Callable[[], StatementConfig]",
+        driver_features: "dict[str, Any]",
+        prepare_driver: "Callable[[PsqlpyDriver], PsqlpyDriver]",
+    ) -> 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: PsqlpyDriver | None = None
+
+    async def __aenter__(self) -> "PsqlpyDriver":
+        from sqlspec.adapters.psqlpy.driver import PsqlpyDriver
+
+        self._connection = await self._acquire_connection()
+        statement_config = self._statement_config() if callable(self._statement_config) else self._statement_config
+        self._driver = PsqlpyDriver(
+            connection=self._connection, statement_config=statement_config, driver_features=self._driver_features
+        )
+        return self._prepare_driver(self._driver)
+
+    async def __aexit__(
+        self, exc_type: "type[BaseException] | None", exc_val: "BaseException | None", exc_tb: "TracebackType | None"
+    ) -> "bool | None":
+        if self._connection is not None:
+            await self._release_connection(self._connection)
+            self._connection = None
+        return None
+
+
+__all__ = ("PsqlpyConnection", "PsqlpyCursor", "PsqlpyListener", "PsqlpySessionContext")

sqlspec/adapters/psqlpy/adk/__init__.py

@@ -0,0 +1,5 @@
+"""Psqlpy ADK store module."""
+
+from sqlspec.adapters.psqlpy.adk.store import PsqlpyADKMemoryStore, PsqlpyADKStore
+
+__all__ = ("PsqlpyADKMemoryStore", "PsqlpyADKStore")