sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/adapters/oracledb/_param_types.py

@@ -0,0 +1,46 @@
+"""Typed parameter wrappers for explicit Oracle LOB / JSON binding.
+
+These slot-based wrappers are an opt-in escape hatch for power users who need
+deterministic LOB or JSON routing regardless of the size-based heuristics in
+:func:`coerce_large_parameters_sync` / :func:`coerce_large_parameters_async`.
+
+Wrap a parameter value to express explicit intent:
+
+* :class:`OracleClob` — bind as ``DB_TYPE_CLOB`` regardless of length.
+* :class:`OracleBlob` — bind as ``DB_TYPE_BLOB`` regardless of length.
+* :class:`OracleJson` — bind as native JSON; defers to the C1 input handler.
+
+The wrappers themselves perform no validation — type discipline lives at the
+routing site so error messages can include database-context detail.
+"""
+
+from typing import Any
+
+__all__ = ("OracleBlob", "OracleClob", "OracleJson")
+
+
+class OracleClob:
+    """Mark a value to be bound as ``DB_TYPE_CLOB`` regardless of length."""
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: "str | bytes") -> None:
+        self.value = value
+
+
+class OracleBlob:
+    """Mark a value to be bound as ``DB_TYPE_BLOB`` regardless of length."""
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: "bytes | str") -> None:
+        self.value = value
+
+
+class OracleJson:
+    """Mark a value to be bound as native ``DB_TYPE_JSON`` regardless of detected version."""
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: Any) -> None:
+        self.value = value

sqlspec/adapters/oracledb/_typing.py

@@ -0,0 +1,258 @@
+"""Oracle adapter type definitions.
+
+This module contains type aliases and classes that are excluded from mypyc
+compilation to avoid ABI boundary issues.
+"""
+
+import contextlib
+from typing import TYPE_CHECKING, Any, Protocol
+
+import oracledb as _oracledb
+from oracledb import (
+    DB_TYPE_BLOB,
+    DB_TYPE_CLOB,
+    DB_TYPE_JSON,
+    DB_TYPE_RAW,
+    AsyncConnection,
+    AsyncCursor,
+    Connection,
+    Cursor,
+    DatabaseError,
+)
+from oracledb.pool import AsyncConnectionPool, ConnectionPool
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from types import TracebackType
+    from typing import TypeAlias
+
+    from oracledb import DB_TYPE_VECTOR  # pyright: ignore[reportUnknownVariableType]
+
+    from sqlspec.adapters.oracledb.driver import OracleAsyncDriver, OracleSyncDriver
+    from sqlspec.builder import QueryBuilder
+    from sqlspec.core import SQL, Statement, StatementConfig
+
+    OracleSyncConnection: TypeAlias = Connection
+    OracleAsyncConnection: TypeAlias = AsyncConnection
+    OracleSyncConnectionPool: TypeAlias = ConnectionPool
+    OracleAsyncConnectionPool: TypeAlias = AsyncConnectionPool
+    OracleSyncRawCursor: TypeAlias = Cursor
+    OracleAsyncRawCursor: TypeAlias = AsyncCursor
+    OracleVectorType: TypeAlias = int
+
+if not TYPE_CHECKING:
+    try:
+        from oracledb import DB_TYPE_VECTOR
+
+        OracleVectorType = int
+    except ImportError:
+        DB_TYPE_VECTOR = None
+        OracleVectorType = int
+
+    OracleSyncConnection = Connection
+    OracleAsyncConnection = AsyncConnection
+    OracleSyncConnectionPool = ConnectionPool
+    OracleAsyncConnectionPool = AsyncConnectionPool
+    OracleSyncRawCursor = Cursor
+    OracleAsyncRawCursor = AsyncCursor
+
+AQDequeueOptions: Any | None = getattr(_oracledb, "AQDequeueOptions", None)
+AQMSG_VISIBLE: int | None = getattr(_oracledb, "AQMSG_VISIBLE", None)
+AQMSG_INVISIBLE: int | None = getattr(_oracledb, "AQMSG_INVISIBLE", None)
+AQMSG_PAYLOAD_TYPE_JSON: Any | None = getattr(_oracledb, "AQMSG_PAYLOAD_TYPE_JSON", None)
+
+
+class OracleSyncCursor:
+    """Sync context manager for Oracle cursor management."""
+
+    __slots__ = ("connection", "cursor")
+
+    def __init__(self, connection: OracleSyncConnection) -> None:
+        self.connection = connection
+        self.cursor: OracleSyncRawCursor | None = None
+
+    def __enter__(self) -> "OracleSyncRawCursor":
+        self.cursor = self.connection.cursor()
+        return self.cursor
+
+    def __exit__(self, *_: object) -> None:
+        if self.cursor is not None:
+            self.cursor.close()
+
+
+class OracleAsyncCursor:
+    """Async context manager for Oracle cursor management."""
+
+    __slots__ = ("connection", "cursor")
+
+    def __init__(self, connection: OracleAsyncConnection) -> None:
+        self.connection = connection
+        self.cursor: OracleAsyncRawCursor | None = None
+
+    async def __aenter__(self) -> "OracleAsyncRawCursor":
+        self.cursor = self.connection.cursor()
+        return self.cursor
+
+    async def __aexit__(
+        self, exc_type: "type[BaseException] | None", exc_val: "BaseException | None", exc_tb: "TracebackType | None"
+    ) -> None:
+        _ = (exc_type, exc_val, exc_tb)  # Mark as intentionally unused
+        if self.cursor is not None:
+            with contextlib.suppress(Exception):
+                # Oracle async cursors have a synchronous close method
+                # but we need to ensure proper cleanup in the event loop context
+                self.cursor.close()
+
+
+class OraclePipelineDriver(Protocol):
+    """Protocol for Oracle pipeline driver methods used in stack execution."""
+
+    statement_config: "StatementConfig"
+    driver_features: "dict[str, Any]"
+
+    def prepare_statement(
+        self,
+        statement: "str | Statement | QueryBuilder",
+        parameters: "tuple[Any, ...] | dict[str, Any] | None",
+        *,
+        statement_config: "StatementConfig | None" = None,
+        kwargs: "dict[str, Any] | None" = None,
+    ) -> "SQL": ...
+
+    def _get_compiled_sql(self, statement: "SQL", statement_config: "StatementConfig") -> "tuple[str, Any]": ...
+
+
+class OracleSyncSessionContext:
+    """Sync context manager for Oracle 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[[OracleSyncDriver], OracleSyncDriver]",
+    ) -> 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: OracleSyncDriver | None = None
+
+    def __enter__(self) -> "OracleSyncDriver":
+        from sqlspec.adapters.oracledb.driver import OracleSyncDriver
+
+        self._connection = self._acquire_connection()
+        self._driver = OracleSyncDriver(
+            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
+
+
+class OracleAsyncSessionContext:
+    """Async context manager for Oracle 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[[OracleAsyncDriver], OracleAsyncDriver]",
+    ) -> 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: OracleAsyncDriver | None = None
+
+    async def __aenter__(self) -> "OracleAsyncDriver":
+        from sqlspec.adapters.oracledb.driver import OracleAsyncDriver
+
+        self._connection = await self._acquire_connection()
+        self._driver = OracleAsyncDriver(
+            connection=self._connection, statement_config=self._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__ = (
+    "AQMSG_INVISIBLE",
+    "AQMSG_PAYLOAD_TYPE_JSON",
+    "AQMSG_VISIBLE",
+    "DB_TYPE_BLOB",
+    "DB_TYPE_CLOB",
+    "DB_TYPE_JSON",
+    "DB_TYPE_RAW",
+    "DB_TYPE_VECTOR",
+    "AQDequeueOptions",
+    "DatabaseError",
+    "OracleAsyncConnection",
+    "OracleAsyncConnectionPool",
+    "OracleAsyncCursor",
+    "OracleAsyncRawCursor",
+    "OracleAsyncSessionContext",
+    "OraclePipelineDriver",
+    "OracleSyncConnection",
+    "OracleSyncConnectionPool",
+    "OracleSyncCursor",
+    "OracleSyncRawCursor",
+    "OracleSyncSessionContext",
+    "OracleVectorType",
+)

sqlspec/adapters/oracledb/_uuid_handlers.py

@@ -0,0 +1,163 @@
+"""Oracle UUID type handlers for RAW(16) binary storage.
+
+Provides automatic conversion between Python UUID objects and Oracle RAW(16)
+via connection type handlers. Uses stdlib uuid (no external dependencies).
+"""
+
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.adapters.oracledb._typing import DB_TYPE_RAW
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from oracledb import AsyncConnection, AsyncCursor, Connection, Cursor
+
+__all__ = (
+    "register_uuid_handlers",
+    "uuid_converter_in",
+    "uuid_converter_out",
+    "uuid_input_type_handler",
+    "uuid_output_type_handler",
+)
+
+
+logger = get_logger(__name__)
+
+
+UUID_BINARY_SIZE = 16
+
+
+def uuid_converter_in(value: uuid.UUID) -> bytes:
+    """Convert Python UUID to 16-byte binary for Oracle RAW(16).
+
+    Args:
+        value: Python UUID object to convert.
+
+    Returns:
+        16-byte binary representation in big-endian format (RFC 4122).
+    """
+    return value.bytes
+
+
+def uuid_converter_out(value: bytes | None) -> "uuid.UUID | bytes | None":
+    """Convert 16-byte binary from Oracle RAW(16) to Python UUID.
+
+    Falls back to bytes if value is not valid UUID format.
+
+    Args:
+        value: 16-byte binary from Oracle RAW(16) column, or None.
+
+    Returns:
+        Python UUID object if valid, original bytes if invalid, None if NULL.
+    """
+    if value is None:
+        return None
+
+    if len(value) != UUID_BINARY_SIZE:
+        return value
+
+    try:
+        return uuid.UUID(bytes=value)
+    except (ValueError, TypeError):
+        logger.debug("RAW(16) value is not valid UUID format, returning as bytes", extra={"value_length": len(value)})
+        return value
+
+
+def _input_type_handler(cursor: "Cursor | AsyncCursor", value: Any, arraysize: int) -> Any:
+    """Oracle input type handler for UUID objects.
+
+    Detects Python UUID objects and converts them to RAW(16) binary format.
+
+    Args:
+        cursor: Oracle cursor (sync or async).
+        value: Value being inserted.
+        arraysize: Array size for the cursor variable.
+
+    Returns:
+        Cursor variable with UUID converter if value is UUID, None otherwise.
+    """
+    if isinstance(value, uuid.UUID):
+        return cursor.var(DB_TYPE_RAW, arraysize=arraysize, inconverter=uuid_converter_in)
+    return None
+
+
+def _output_type_handler(cursor: "Cursor | AsyncCursor", metadata: Any) -> Any:
+    """Oracle output type handler for RAW(16) columns.
+
+    Detects RAW(16) columns and converts them to Python UUID objects.
+
+    Args:
+        cursor: Oracle cursor (sync or async).
+        metadata: Column metadata tuple (name, type_code, display_size, internal_size, precision, scale, null_ok).
+
+    Returns:
+        Cursor variable with UUID converter if column is RAW(16), None otherwise.
+    """
+    _name, type_code, _display_size, internal_size, _precision, _scale, _null_ok = metadata
+
+    if type_code is DB_TYPE_RAW and internal_size == UUID_BINARY_SIZE:
+        return cursor.var(type_code, arraysize=cursor.arraysize, outconverter=uuid_converter_out)
+    return None
+
+
+def uuid_input_type_handler(cursor: "Cursor | AsyncCursor", value: Any, arraysize: int) -> Any:
+    """Public input type handler for UUID values."""
+    return _input_type_handler(cursor, value, arraysize)
+
+
+def uuid_output_type_handler(cursor: "Cursor | AsyncCursor", metadata: Any) -> Any:
+    """Public output type handler for RAW(16) UUID values."""
+    return _output_type_handler(cursor, metadata)
+
+
+def register_uuid_handlers(connection: "Connection | AsyncConnection") -> None:
+    """Register UUID type handlers with chaining support.
+
+    Chains to existing type handlers (e.g., NumPy vectors) to avoid conflicts.
+    Works for both sync and async connections.
+
+    Args:
+        connection: Oracle connection (sync or async).
+    """
+    try:
+        existing_input = connection.inputtypehandler
+    except AttributeError:
+        existing_input = None
+    try:
+        existing_output = connection.outputtypehandler
+    except AttributeError:
+        existing_output = None
+
+    connection.inputtypehandler = _UuidInputHandler(existing_input)
+    connection.outputtypehandler = _UuidOutputHandler(existing_output)
+
+
+class _UuidInputHandler:
+    __slots__ = ("_fallback",)
+
+    def __init__(self, fallback: "Any | None") -> None:
+        self._fallback = fallback
+
+    def __call__(self, cursor: "Cursor | AsyncCursor", value: Any, arraysize: int) -> Any:
+        result = _input_type_handler(cursor, value, arraysize)
+        if result is not None:
+            return result
+        if self._fallback is not None:
+            return self._fallback(cursor, value, arraysize)
+        return None
+
+
+class _UuidOutputHandler:
+    __slots__ = ("_fallback",)
+
+    def __init__(self, fallback: "Any | None") -> None:
+        self._fallback = fallback
+
+    def __call__(self, cursor: "Cursor | AsyncCursor", metadata: Any) -> Any:
+        result = _output_type_handler(cursor, metadata)
+        if result is not None:
+            return result
+        if self._fallback is not None:
+            return self._fallback(cursor, metadata)
+        return None

sqlspec/adapters/oracledb/_vector_handlers.py

@@ -0,0 +1,228 @@
+"""Oracle vector type handlers for the DB_TYPE_VECTOR data type.
+
+Provides automatic conversion between Python sequence-of-numbers
+(``numpy.ndarray``, ``array.array``, ``list``, ``tuple``) and Oracle VECTOR
+columns. Requires Oracle Database 23ai or higher.
+
+Public symbols keep the historical ``numpy_*`` prefix for backwards-compat with
+sqlspec ``__all__`` consumers; the user-facing rename to ``vector_*`` is tracked
+as a follow-up.
+"""
+
+import array
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.adapters.oracledb._typing import DB_TYPE_VECTOR
+from sqlspec.typing import NUMPY_INSTALLED
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from oracledb import AsyncConnection, AsyncCursor, Connection, Cursor
+
+__all__ = (
+    "DTYPE_TO_ARRAY_CODE",
+    "numpy_converter_in",
+    "numpy_converter_out",
+    "numpy_input_type_handler",
+    "numpy_output_type_handler",
+    "register_numpy_handlers",
+)
+
+
+logger = get_logger(__name__)
+
+
+_TYPECODE_FLOAT64 = "d"
+_TYPECODE_FLOAT32 = "f"
+_TYPECODE_FLOAT16 = "e"
+_TYPECODE_UINT8 = "B"
+_TYPECODE_INT8 = "b"
+_TYPECODE_INT16 = "h"
+_TYPECODE_INT32 = "i"
+
+_INT8_MIN = -128
+_INT8_MAX = 127
+
+_VECTOR_RETURN_NUMPY = "numpy"
+_VECTOR_RETURN_LIST = "list"
+_VECTOR_RETURN_ARRAY = "array"
+_VECTOR_RETURN_FORMATS = frozenset({_VECTOR_RETURN_NUMPY, _VECTOR_RETURN_LIST, _VECTOR_RETURN_ARRAY})
+
+DTYPE_TO_ARRAY_CODE: "dict[str, str]" = {
+    "float64": _TYPECODE_FLOAT64,
+    "float32": _TYPECODE_FLOAT32,
+    "uint8": _TYPECODE_UINT8,
+    "int8": _TYPECODE_INT8,
+    "int16": _TYPECODE_INT16,
+    "int32": _TYPECODE_INT32,
+}
+try:
+    array.array(_TYPECODE_FLOAT16)
+except ValueError:
+    pass
+else:
+    DTYPE_TO_ARRAY_CODE["float16"] = _TYPECODE_FLOAT16
+
+
+def numpy_converter_in(value: Any) -> "array.array[Any]":
+    """Convert NumPy array to Oracle array for VECTOR insertion.
+
+    Args:
+        value: NumPy ndarray to convert.
+
+    Returns:
+        Python array.array compatible with Oracle VECTOR type.
+
+    Raises:
+        ImportError: If NumPy is not installed.
+        TypeError: If NumPy dtype is not supported for Oracle VECTOR.
+    """
+    if not NUMPY_INSTALLED:
+        msg = "NumPy is not installed - cannot convert vectors"
+        raise ImportError(msg)
+
+    dtype_name = value.dtype.name
+    array_code = DTYPE_TO_ARRAY_CODE.get(dtype_name)
+
+    if not array_code:
+        supported = ", ".join(DTYPE_TO_ARRAY_CODE.keys())
+        msg = f"Unsupported NumPy dtype for Oracle VECTOR: {dtype_name}. Supported: {supported}"
+        raise TypeError(msg)
+
+    return array.array(array_code, value)
+
+
+def numpy_converter_out(value: "array.array[Any]") -> Any:
+    """Convert Oracle array to NumPy array for VECTOR retrieval.
+
+    Args:
+        value: Oracle array.array from VECTOR column.
+
+    Returns:
+        NumPy ndarray with appropriate dtype, or original value if NumPy not installed.
+    """
+    if not NUMPY_INSTALLED:
+        return value
+
+    import numpy as np
+
+    return np.array(value, copy=True, dtype=value.typecode)
+
+
+def _is_vector_payload(value: Any) -> bool:
+    """Return True if the value should be claimed by the vector input handler.
+
+    Mirrors the C1 ``_is_json_payload`` predicate but inverted: claims sequences
+    of numbers (vector embeddings); rejects ``dict`` / ``list[dict]`` which the
+    JSON handler owns. ``bool`` is excluded explicitly because it is a subclass
+    of ``int`` but is owned by the JSON path.
+    """
+    if isinstance(value, array.array):
+        return True
+    if NUMPY_INSTALLED:
+        import numpy as np
+
+        if isinstance(value, np.ndarray):
+            return True
+    if isinstance(value, (list, tuple)) and value:
+        first = value[0]
+        if isinstance(first, bool):
+            return False
+        return isinstance(first, (int, float))
+    return False
+
+
+def _pack_python_sequence(value: "list[Any] | tuple[Any, ...]") -> "array.array[Any]":
+    """Pack a Python sequence into an ``array.array`` for VECTOR binding.
+
+    Integer sequences entirely within ``[-128, 127]`` use the int8 typecode for
+    a cheaper bind; everything else falls back to float32 (the 23ai default and
+    the most common LLM embedding dtype).
+    """
+    if all(isinstance(v, int) and not isinstance(v, bool) and _INT8_MIN <= v <= _INT8_MAX for v in value):
+        return array.array(_TYPECODE_INT8, value)
+    return array.array(_TYPECODE_FLOAT32, [float(v) for v in value])
+
+
+def _input_type_handler(cursor: "Cursor | AsyncCursor", value: Any, arraysize: int) -> Any:
+    """Oracle input type handler for vector payloads.
+
+    Args:
+        cursor: Oracle cursor (sync or async).
+        value: Value being inserted.
+        arraysize: Array size for the cursor variable.
+
+    Returns:
+        Cursor variable for VECTOR binding when ``value`` is a vector payload,
+        otherwise ``None`` so the next handler in the chain can claim it.
+    """
+    if not _is_vector_payload(value):
+        return None
+
+    if NUMPY_INSTALLED:
+        import numpy as np
+
+        if isinstance(value, np.ndarray):
+            return cursor.var(DB_TYPE_VECTOR, arraysize=arraysize, inconverter=numpy_converter_in)
+
+    if isinstance(value, array.array):
+        return cursor.var(DB_TYPE_VECTOR, arraysize=arraysize)
+
+    packed = _pack_python_sequence(value)
+    return cursor.var(DB_TYPE_VECTOR, arraysize=arraysize, inconverter=lambda _v: packed)
+
+
+def _output_type_handler(cursor: "Cursor | AsyncCursor", metadata: Any) -> Any:
+    """Oracle output type handler for VECTOR columns.
+
+    Reads ``connection._sqlspec_vector_return_format`` (set by the session
+    callback in ``config._init_connection``) to dispatch to the requested
+    return type. Falls back to ``"numpy"`` when NumPy is installed and
+    ``"list"`` otherwise so consumers without the connection-level setting
+    still get sensible behavior.
+    """
+    if metadata.type_code is not DB_TYPE_VECTOR:
+        return None
+
+    fmt = getattr(cursor.connection, "_sqlspec_vector_return_format", None)
+    if fmt is None:
+        fmt = _VECTOR_RETURN_NUMPY if NUMPY_INSTALLED else _VECTOR_RETURN_LIST
+
+    if fmt == _VECTOR_RETURN_NUMPY:
+        if not NUMPY_INSTALLED:
+            msg = (
+                "vector_return_format='numpy' requires numpy; install with "
+                "`pip install sqlspec[oracle,numpy]` or set vector_return_format='list'."
+            )
+            raise RuntimeError(msg)
+        return cursor.var(metadata.type_code, arraysize=cursor.arraysize, outconverter=numpy_converter_out)
+    if fmt == _VECTOR_RETURN_LIST:
+        return cursor.var(metadata.type_code, arraysize=cursor.arraysize, outconverter=list)
+    if fmt == _VECTOR_RETURN_ARRAY:
+        return None
+
+    msg = f"Invalid vector_return_format: {fmt!r}; expected one of {sorted(_VECTOR_RETURN_FORMATS)}"
+    raise ValueError(msg)
+
+
+def numpy_input_type_handler(cursor: "Cursor | AsyncCursor", value: Any, arraysize: int) -> Any:
+    """Public input type handler for vector payloads."""
+    return _input_type_handler(cursor, value, arraysize)
+
+
+def numpy_output_type_handler(cursor: "Cursor | AsyncCursor", metadata: Any) -> Any:
+    """Public output type handler for VECTOR columns."""
+    return _output_type_handler(cursor, metadata)
+
+
+def register_numpy_handlers(connection: "Connection | AsyncConnection") -> None:
+    """Register vector type handlers on an Oracle connection.
+
+    Enables automatic conversion between Python sequence types and Oracle
+    VECTOR columns. Works for both sync and async connections.
+
+    Args:
+        connection: Oracle connection (sync or async).
+    """
+    connection.inputtypehandler = numpy_input_type_handler
+    connection.outputtypehandler = numpy_output_type_handler