sqlspec 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

sqlspec/__init__.py

@@ -2,7 +2,6 @@
 
 from sqlspec import adapters, base, builder, core, driver, exceptions, extensions, loader, migrations, typing, utils
 from sqlspec.__metadata__ import __version__
-from sqlspec._sql import SQLFactory, sql
 from sqlspec.base import SQLSpec
 from sqlspec.builder import (
     Column,
@@ -15,7 +14,9 @@ from sqlspec.builder import (
     Merge,
     QueryBuilder,
     Select,
+    SQLFactory,
     Update,
+    sql,
 )
 from sqlspec.config import AsyncDatabaseConfig, SyncDatabaseConfig
 from sqlspec.core import (
@@ -34,16 +35,10 @@ from sqlspec.core import (
 from sqlspec.core import filters as filters
 from sqlspec.driver import AsyncDriverAdapterBase, ExecutionResult, SyncDriverAdapterBase
 from sqlspec.loader import SQLFile, SQLFileLoader
-from sqlspec.typing import (
-    ConnectionT,
-    DictRow,
-    ModelDTOT,
-    ModelT,
-    PoolT,
-    RowT,
-    StatementParameters,
-    SupportedSchemaModel,
-)
+from sqlspec.typing import ConnectionT, PoolT, SchemaT, StatementParameters, SupportedSchemaModel
+from sqlspec.utils.logging import suppress_erroneous_sqlglot_log_messages
+
+suppress_erroneous_sqlglot_log_messages()
 
 __all__ = (
     "SQL",
@@ -57,26 +52,23 @@ __all__ = (
     "ConnectionT",
     "CreateTable",
     "Delete",
-    "DictRow",
     "DropTable",
     "ExecutionResult",
     "FunctionColumn",
     "Insert",
     "Merge",
-    "ModelDTOT",
-    "ModelT",
     "ParameterConverter",
     "ParameterProcessor",
     "ParameterStyle",
     "ParameterStyleConfig",
     "PoolT",
     "QueryBuilder",
-    "RowT",
     "SQLFactory",
     "SQLFile",
     "SQLFileLoader",
     "SQLResult",
     "SQLSpec",
+    "SchemaT",
     "Select",
     "Statement",
     "StatementConfig",

sqlspec/_serialization.py

@@ -2,6 +2,9 @@
 
 Provides a Protocol-based serialization system that users can extend.
 Supports msgspec, orjson, and standard library JSON with automatic fallback.
+
+Features optional numpy array serialization when numpy is installed.
+Arrays are automatically converted to lists during JSON encoding.
 """
 
 import contextlib
@@ -9,19 +12,25 @@ import datetime
 import enum
 import json
 from abc import ABC, abstractmethod
-from typing import Any, Final, Literal, Optional, Protocol, Union, overload
+from typing import Any, Final, Literal, Protocol, overload
 
+from sqlspec._typing import NUMPY_INSTALLED
 from sqlspec.typing import MSGSPEC_INSTALLED, ORJSON_INSTALLED, PYDANTIC_INSTALLED, BaseModel
 
 
-def _type_to_string(value: Any) -> str:  # pragma: no cover
+def _type_to_string(value: Any) -> Any:  # pragma: no cover
     """Convert special types to strings for JSON serialization.
 
+    Handles datetime, date, enums, Pydantic models, and numpy arrays.
+
     Args:
         value: Value to convert.
 
     Returns:
-        String representation of the value.
+        Serializable representation of the value (string, list, dict, etc.).
+
+    Raises:
+        TypeError: If value cannot be serialized.
     """
     if isinstance(value, datetime.datetime):
         return convert_datetime_to_gmt_iso(value)
@@ -31,10 +40,16 @@ def _type_to_string(value: Any) -> str:  # pragma: no cover
         return str(value.value)
     if PYDANTIC_INSTALLED and isinstance(value, BaseModel):
         return value.model_dump_json()
+    if NUMPY_INSTALLED:
+        import numpy as np
+
+        if isinstance(value, np.ndarray):
+            return value.tolist()
     try:
         return str(value)
     except Exception as exc:
-        raise TypeError from exc
+        msg = f"Cannot serialize {type(value).__name__}"
+        raise TypeError(msg) from exc
 
 
 class JSONSerializer(Protocol):
@@ -43,7 +58,7 @@ class JSONSerializer(Protocol):
     Users can implement this protocol to create custom serializers.
     """
 
-    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+    def encode(self, data: Any, *, as_bytes: bool = False) -> str | bytes:
         """Encode data to JSON.
 
         Args:
@@ -55,7 +70,7 @@ class JSONSerializer(Protocol):
         """
         ...
 
-    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+    def decode(self, data: str | bytes, *, decode_bytes: bool = True) -> Any:
         """Decode from JSON.
 
         Args:
@@ -74,18 +89,18 @@ class BaseJSONSerializer(ABC):
     __slots__ = ()
 
     @abstractmethod
-    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+    def encode(self, data: Any, *, as_bytes: bool = False) -> str | bytes:
         """Encode data to JSON."""
         ...
 
     @abstractmethod
-    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+    def decode(self, data: str | bytes, *, decode_bytes: bool = True) -> Any:
         """Decode from JSON."""
         ...
 
 
 class MsgspecSerializer(BaseJSONSerializer):
-    """Msgspec-based JSON serializer for optimal performance."""
+    """Msgspec-based JSON serializer."""
 
     __slots__ = ("_decoder", "_encoder")
 
@@ -96,7 +111,7 @@ class MsgspecSerializer(BaseJSONSerializer):
         self._encoder: Final[Encoder] = Encoder(enc_hook=_type_to_string)
         self._decoder: Final[Decoder] = Decoder()
 
-    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+    def encode(self, data: Any, *, as_bytes: bool = False) -> str | bytes:
         """Encode data using msgspec."""
         try:
             if as_bytes:
@@ -107,7 +122,7 @@ class MsgspecSerializer(BaseJSONSerializer):
                 return OrjsonSerializer().encode(data, as_bytes=as_bytes)
             return StandardLibSerializer().encode(data, as_bytes=as_bytes)
 
-    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+    def decode(self, data: str | bytes, *, decode_bytes: bool = True) -> Any:
         """Decode data using msgspec."""
         if isinstance(data, bytes):
             if decode_bytes:
@@ -128,25 +143,40 @@ class MsgspecSerializer(BaseJSONSerializer):
 
 
 class OrjsonSerializer(BaseJSONSerializer):
-    """Orjson-based JSON serializer with native datetime/UUID support."""
+    """Orjson-based JSON serializer with native datetime/UUID support.
+
+    Automatically enables numpy serialization if numpy is installed.
+    """
 
     __slots__ = ()
 
-    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
-        """Encode data using orjson."""
+    def encode(self, data: Any, *, as_bytes: bool = False) -> str | bytes:
+        """Encode data using orjson.
+
+        Args:
+            data: Data to encode.
+            as_bytes: Whether to return bytes instead of string.
+
+        Returns:
+            JSON string or bytes depending on as_bytes parameter.
+        """
         from orjson import (
             OPT_NAIVE_UTC,  # pyright: ignore[reportUnknownVariableType]
-            OPT_SERIALIZE_NUMPY,  # pyright: ignore[reportUnknownVariableType]
             OPT_SERIALIZE_UUID,  # pyright: ignore[reportUnknownVariableType]
         )
         from orjson import dumps as _orjson_dumps  # pyright: ignore[reportMissingImports]
 
-        result = _orjson_dumps(
-            data, default=_type_to_string, option=OPT_SERIALIZE_NUMPY | OPT_NAIVE_UTC | OPT_SERIALIZE_UUID
-        )
+        options = OPT_NAIVE_UTC | OPT_SERIALIZE_UUID
+
+        if NUMPY_INSTALLED:
+            from orjson import OPT_SERIALIZE_NUMPY  # pyright: ignore[reportUnknownVariableType]
+
+            options |= OPT_SERIALIZE_NUMPY
+
+        result = _orjson_dumps(data, default=_type_to_string, option=options)
         return result if as_bytes else result.decode("utf-8")
 
-    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+    def decode(self, data: str | bytes, *, decode_bytes: bool = True) -> Any:
         """Decode data using orjson."""
         from orjson import loads as _orjson_loads  # pyright: ignore[reportMissingImports]
 
@@ -162,12 +192,12 @@ class StandardLibSerializer(BaseJSONSerializer):
 
     __slots__ = ()
 
-    def encode(self, data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
+    def encode(self, data: Any, *, as_bytes: bool = False) -> str | bytes:
         """Encode data using standard library json."""
         json_str = json.dumps(data, default=_type_to_string)
         return json_str.encode("utf-8") if as_bytes else json_str
 
-    def decode(self, data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+    def decode(self, data: str | bytes, *, decode_bytes: bool = True) -> Any:
         """Decode data using standard library json."""
         if isinstance(data, bytes):
             if decode_bytes:
@@ -176,7 +206,7 @@ class StandardLibSerializer(BaseJSONSerializer):
         return json.loads(data)
 
 
-_default_serializer: Optional[JSONSerializer] = None
+_default_serializer: JSONSerializer | None = None
 
 
 def get_default_serializer() -> JSONSerializer:
@@ -213,8 +243,8 @@ def encode_json(data: Any, *, as_bytes: Literal[False] = ...) -> str: ...  # pra
 def encode_json(data: Any, *, as_bytes: Literal[True]) -> bytes: ...  # pragma: no cover
 
 
-def encode_json(data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
-    """Encode to JSON, optionally returning bytes for optimal performance.
+def encode_json(data: Any, *, as_bytes: bool = False) -> str | bytes:
+    """Encode to JSON, optionally returning bytes.
 
     Args:
         data: The data to encode.
@@ -226,7 +256,7 @@ def encode_json(data: Any, *, as_bytes: bool = False) -> Union[str, bytes]:
     return get_default_serializer().encode(data, as_bytes=as_bytes)
 
 
-def decode_json(data: Union[str, bytes], *, decode_bytes: bool = True) -> Any:
+def decode_json(data: str | bytes, *, decode_bytes: bool = True) -> Any:
     """Decode from JSON string or bytes efficiently.
 
     Args:

sqlspec/_typing.py

@@ -6,9 +6,9 @@ from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
 from enum import Enum
 from importlib.util import find_spec
-from typing import Any, ClassVar, Final, Optional, Protocol, Union, cast, runtime_checkable
+from typing import Any, ClassVar, Final, Literal, Protocol, cast, runtime_checkable
 
-from typing_extensions import Literal, TypeVar, dataclass_transform
+from typing_extensions import TypeVar, dataclass_transform
 
 
 @runtime_checkable
@@ -38,15 +38,15 @@ class BaseModelStub:
         self,
         /,
         *,
-        include: "Optional[Any]" = None,  # noqa: ARG002
-        exclude: "Optional[Any]" = None,  # noqa: ARG002
-        context: "Optional[Any]" = None,  # noqa: ARG002
+        include: "Any | None" = None,  # noqa: ARG002
+        exclude: "Any | None" = None,  # noqa: ARG002
+        context: "Any | None" = None,  # noqa: ARG002
         by_alias: bool = False,  # noqa: ARG002
         exclude_unset: bool = False,  # noqa: ARG002
         exclude_defaults: bool = False,  # noqa: ARG002
         exclude_none: bool = False,  # noqa: ARG002
         round_trip: bool = False,  # noqa: ARG002
-        warnings: "Union[bool, Literal['none', 'warn', 'error']]" = True,  # noqa: ARG002
+        warnings: "bool | Literal['none', 'warn', 'error']" = True,  # noqa: ARG002
         serialize_as_any: bool = False,  # noqa: ARG002
     ) -> "dict[str, Any]":
         """Placeholder implementation."""
@@ -56,15 +56,15 @@ class BaseModelStub:
         self,
         /,
         *,
-        include: "Optional[Any]" = None,  # noqa: ARG002
-        exclude: "Optional[Any]" = None,  # noqa: ARG002
-        context: "Optional[Any]" = None,  # noqa: ARG002
+        include: "Any | None" = None,  # noqa: ARG002
+        exclude: "Any | None" = None,  # noqa: ARG002
+        context: "Any | None" = None,  # noqa: ARG002
         by_alias: bool = False,  # noqa: ARG002
         exclude_unset: bool = False,  # noqa: ARG002
         exclude_defaults: bool = False,  # noqa: ARG002
         exclude_none: bool = False,  # noqa: ARG002
         round_trip: bool = False,  # noqa: ARG002
-        warnings: "Union[bool, Literal['none', 'warn', 'error']]" = True,  # noqa: ARG002
+        warnings: "bool | Literal['none', 'warn', 'error']" = True,  # noqa: ARG002
         serialize_as_any: bool = False,  # noqa: ARG002
     ) -> str:
         """Placeholder implementation."""
@@ -78,9 +78,9 @@ class TypeAdapterStub:
         self,
         type: Any,  # noqa: A002
         *,
-        config: "Optional[Any]" = None,  # noqa: ARG002
+        config: "Any | None" = None,  # noqa: ARG002
         _parent_depth: int = 2,  # noqa: ARG002
-        module: "Optional[str]" = None,  # noqa: ARG002
+        module: "str | None" = None,  # noqa: ARG002
     ) -> None:
         """Initialize."""
         self._type = type
@@ -90,10 +90,10 @@ class TypeAdapterStub:
         object: Any,
         /,
         *,
-        strict: "Optional[bool]" = None,  # noqa: ARG002
-        from_attributes: "Optional[bool]" = None,  # noqa: ARG002
-        context: "Optional[dict[str, Any]]" = None,  # noqa: ARG002
-        experimental_allow_partial: "Union[bool, Literal['off', 'on', 'trailing-strings']]" = False,  # noqa: ARG002
+        strict: "bool | None" = None,  # noqa: ARG002
+        from_attributes: "bool | None" = None,  # noqa: ARG002
+        context: "dict[str, Any] | None" = None,  # noqa: ARG002
+        experimental_allow_partial: "bool | Literal['off', 'on', 'trailing-strings']" = False,  # noqa: ARG002
     ) -> Any:
         """Validate Python object."""
         return object
@@ -143,8 +143,8 @@ def convert_stub(  # noqa: PLR0913
     *,
     strict: bool = True,  # noqa: ARG001
     from_attributes: bool = False,  # noqa: ARG001
-    dec_hook: "Optional[Any]" = None,  # noqa: ARG001
-    builtin_types: "Optional[Any]" = None,  # noqa: ARG001
+    dec_hook: "Any | None" = None,  # noqa: ARG001
+    builtin_types: "Any | None" = None,  # noqa: ARG001
     str_keys: bool = False,  # noqa: ARG001
 ) -> Any:
     """Placeholder implementation."""
@@ -308,7 +308,7 @@ class EmptyEnum(Enum):
     EMPTY = 0
 
 
-EmptyType = Union[Literal[EmptyEnum.EMPTY], UnsetType]
+EmptyType = Literal[EmptyEnum.EMPTY] | UnsetType
 Empty: Final = EmptyEnum.EMPTY
 
 
@@ -336,18 +336,18 @@ class ArrowTableResult(Protocol):
     def from_arrays(
         self,
         arrays: list[Any],
-        names: "Optional[list[str]]" = None,
-        schema: "Optional[Any]" = None,
-        metadata: "Optional[Mapping[str, Any]]" = None,
+        names: "list[str] | None" = None,
+        schema: "Any | None" = None,
+        metadata: "Mapping[str, Any] | None" = None,
     ) -> Any:
         return None
 
     def from_pydict(
-        self, mapping: dict[str, Any], schema: "Optional[Any]" = None, metadata: "Optional[Mapping[str, Any]]" = None
+        self, mapping: dict[str, Any], schema: "Any | None" = None, metadata: "Mapping[str, Any] | None" = None
     ) -> Any:
         return None
 
-    def from_batches(self, batches: Iterable[Any], schema: Optional[Any] = None) -> Any:
+    def from_batches(self, batches: Iterable[Any], schema: Any | None = None) -> Any:
         return None
 
 
@@ -373,22 +373,123 @@ class ArrowRecordBatchResult(Protocol):
     def column(self, i: int) -> Any:
         return None
 
-    def slice(self, offset: int = 0, length: "Optional[int]" = None) -> Any:
+    def slice(self, offset: int = 0, length: "int | None" = None) -> Any:
         return None
 
 
+@runtime_checkable
+class ArrowSchemaProtocol(Protocol):
+    """Typed shim for pyarrow.Schema."""
+
+    def field(self, i: int) -> Any:
+        """Get field by index."""
+        ...
+
+    @property
+    def names(self) -> "list[str]":
+        """Get list of field names."""
+        ...
+
+    def __len__(self) -> int:
+        """Get number of fields."""
+        return 0
+
+
+@runtime_checkable
+class ArrowRecordBatchReaderProtocol(Protocol):
+    """Typed shim for pyarrow.RecordBatchReader."""
+
+    def read_all(self) -> Any:
+        """Read all batches into a table."""
+        ...
+
+    def read_next_batch(self) -> Any:
+        """Read next batch."""
+        ...
+
+    def __iter__(self) -> "Iterable[Any]":
+        """Iterate over batches."""
+        ...
+
+
 try:
     from pyarrow import RecordBatch as ArrowRecordBatch
+    from pyarrow import RecordBatchReader as ArrowRecordBatchReader
+    from pyarrow import Schema as ArrowSchema
     from pyarrow import Table as ArrowTable
 
     PYARROW_INSTALLED = True
 except ImportError:
     ArrowTable = ArrowTableResult  # type: ignore[assignment,misc]
     ArrowRecordBatch = ArrowRecordBatchResult  # type: ignore[assignment,misc]
+    ArrowSchema = ArrowSchemaProtocol  # type: ignore[assignment,misc]
+    ArrowRecordBatchReader = ArrowRecordBatchReaderProtocol  # type: ignore[assignment,misc]
 
     PYARROW_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
 
 
+@runtime_checkable
+class PandasDataFrameProtocol(Protocol):
+    """Typed shim for pandas.DataFrame."""
+
+    def __len__(self) -> int:
+        """Get number of rows."""
+        ...
+
+    def __getitem__(self, key: Any) -> Any:
+        """Get column or row."""
+        ...
+
+
+@runtime_checkable
+class PolarsDataFrameProtocol(Protocol):
+    """Typed shim for polars.DataFrame."""
+
+    def __len__(self) -> int:
+        """Get number of rows."""
+        ...
+
+    def __getitem__(self, key: Any) -> Any:
+        """Get column or row."""
+        ...
+
+
+try:
+    from pandas import DataFrame as PandasDataFrame
+
+    PANDAS_INSTALLED = True
+except ImportError:
+    PandasDataFrame = PandasDataFrameProtocol  # type: ignore[assignment,misc]
+    PANDAS_INSTALLED = False
+
+
+try:
+    from polars import DataFrame as PolarsDataFrame
+
+    POLARS_INSTALLED = True
+except ImportError:
+    PolarsDataFrame = PolarsDataFrameProtocol  # type: ignore[assignment,misc]
+    POLARS_INSTALLED = False
+
+
+@runtime_checkable
+class NumpyArrayStub(Protocol):
+    """Protocol stub for numpy.ndarray when numpy is not installed.
+
+    Provides minimal interface for type checking and serialization support.
+    """
+
+    def tolist(self) -> "list[Any]":
+        """Convert array to Python list."""
+        ...
+
+
+try:
+    from numpy import ndarray as NumpyArray  # noqa: N812
+except ImportError:
+    NumpyArray = NumpyArrayStub  # type: ignore[assignment,misc]
+
+
 try:
     from opentelemetry import trace  # pyright: ignore[reportMissingImports, reportAssignmentType]
     from opentelemetry.trace import (  # pyright: ignore[reportMissingImports, reportAssignmentType]
@@ -409,16 +510,16 @@ except ImportError:
         def record_exception(
             self,
             exception: "Exception",
-            attributes: "Optional[Mapping[str, Any]]" = None,
-            timestamp: "Optional[int]" = None,
+            attributes: "Mapping[str, Any] | None" = None,
+            timestamp: "int | None" = None,
             escaped: bool = False,
         ) -> None:
             return None
 
-        def set_status(self, status: Any, description: "Optional[str]" = None) -> None:
+        def set_status(self, status: Any, description: "str | None" = None) -> None:
             return None
 
-        def end(self, end_time: "Optional[int]" = None) -> None:
+        def end(self, end_time: "int | None" = None) -> None:
             return None
 
         def __enter__(self) -> "Span":
@@ -445,8 +546,8 @@ except ImportError:
         def get_tracer(
             self,
             instrumenting_module_name: str,
-            instrumenting_library_version: "Optional[str]" = None,
-            schema_url: "Optional[str]" = None,
+            instrumenting_library_version: "str | None" = None,
+            schema_url: "str | None" = None,
             tracer_provider: Any = None,
         ) -> Tracer:
             return Tracer()  # type: ignore[abstract] # pragma: no cover
@@ -522,9 +623,6 @@ try:
     from aiosql.types import (  # pyright: ignore[reportMissingImports, reportAssignmentType]
         AsyncDriverAdapterProtocol as AiosqlAsyncProtocol,  # pyright: ignore[reportMissingImports, reportAssignmentType]
     )
-    from aiosql.types import (  # pyright: ignore[reportMissingImports, reportAssignmentType]
-        DriverAdapterProtocol as AiosqlProtocol,  # pyright: ignore[reportMissingImports, reportAssignmentType]
-    )
     from aiosql.types import ParamType as AiosqlParamType  # pyright: ignore[reportMissingImports, reportAssignmentType]
     from aiosql.types import (
         SQLOperationType as AiosqlSQLOperationType,  # pyright: ignore[reportMissingImports, reportAssignmentType]
@@ -553,7 +651,7 @@ except ImportError:
     aiosql = _AiosqlShim()  # type: ignore[assignment]
 
     # Placeholder types for aiosql protocols
-    AiosqlParamType = Union[dict[str, Any], list[Any], tuple[Any, ...], None]  # type: ignore[misc]
+    AiosqlParamType = Any  # type: ignore[misc]
 
     class AiosqlSQLOperationType(Enum):  # type: ignore[no-redef]
         """Enumeration of aiosql operation types."""
@@ -566,12 +664,6 @@ except ImportError:
         SELECT_ONE = 5
         SELECT_VALUE = 6
 
-    @runtime_checkable
-    class AiosqlProtocol(Protocol):  # type: ignore[no-redef]
-        """Placeholder for aiosql DriverAdapterProtocol"""
-
-        def process_sql(self, query_name: str, op_type: Any, sql: str) -> str: ...
-
     @runtime_checkable
     class AiosqlSyncProtocol(Protocol):  # type: ignore[no-redef]
         """Placeholder for aiosql SyncDriverAdapterProtocol"""
@@ -580,16 +672,16 @@ except ImportError:
 
         def process_sql(self, query_name: str, op_type: Any, sql: str) -> str: ...
         def select(
-            self, conn: Any, query_name: str, sql: str, parameters: Any, record_class: "Optional[Any]" = None
+            self, conn: Any, query_name: str, sql: str, parameters: Any, record_class: "Any | None" = None
         ) -> Any: ...
         def select_one(
-            self, conn: Any, query_name: str, sql: str, parameters: Any, record_class: "Optional[Any]" = None
-        ) -> "Optional[Any]": ...
-        def select_value(self, conn: Any, query_name: str, sql: str, parameters: Any) -> "Optional[Any]": ...
+            self, conn: Any, query_name: str, sql: str, parameters: Any, record_class: "Any | None" = None
+        ) -> "Any | None": ...
+        def select_value(self, conn: Any, query_name: str, sql: str, parameters: Any) -> "Any | None": ...
         def select_cursor(self, conn: Any, query_name: str, sql: str, parameters: Any) -> Any: ...
         def insert_update_delete(self, conn: Any, query_name: str, sql: str, parameters: Any) -> int: ...
         def insert_update_delete_many(self, conn: Any, query_name: str, sql: str, parameters: Any) -> int: ...
-        def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: Any) -> "Optional[Any]": ...
+        def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: Any) -> "Any | None": ...
 
     @runtime_checkable
     class AiosqlAsyncProtocol(Protocol):  # type: ignore[no-redef]
@@ -599,16 +691,16 @@ except ImportError:
 
         def process_sql(self, query_name: str, op_type: Any, sql: str) -> str: ...
         async def select(
-            self, conn: Any, query_name: str, sql: str, parameters: Any, record_class: "Optional[Any]" = None
+            self, conn: Any, query_name: str, sql: str, parameters: Any, record_class: "Any | None" = None
         ) -> Any: ...
         async def select_one(
-            self, conn: Any, query_name: str, sql: str, parameters: Any, record_class: "Optional[Any]" = None
-        ) -> "Optional[Any]": ...
-        async def select_value(self, conn: Any, query_name: str, sql: str, parameters: Any) -> "Optional[Any]": ...
+            self, conn: Any, query_name: str, sql: str, parameters: Any, record_class: "Any | None" = None
+        ) -> "Any | None": ...
+        async def select_value(self, conn: Any, query_name: str, sql: str, parameters: Any) -> "Any | None": ...
         async def select_cursor(self, conn: Any, query_name: str, sql: str, parameters: Any) -> Any: ...
         async def insert_update_delete(self, conn: Any, query_name: str, sql: str, parameters: Any) -> None: ...
         async def insert_update_delete_many(self, conn: Any, query_name: str, sql: str, parameters: Any) -> None: ...
-        async def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: Any) -> "Optional[Any]": ...
+        async def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: Any) -> "Any | None": ...
 
     AIOSQL_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]  # pyright: ignore[reportConstantRedefinition]
 
@@ -630,7 +722,9 @@ __all__ = (
     "OBSTORE_INSTALLED",
     "OPENTELEMETRY_INSTALLED",
     "ORJSON_INSTALLED",
+    "PANDAS_INSTALLED",
     "PGVECTOR_INSTALLED",
+    "POLARS_INSTALLED",
     "PROMETHEUS_INSTALLED",
     "PYARROW_INSTALLED",
     "PYDANTIC_INSTALLED",
@@ -638,11 +732,14 @@ __all__ = (
     "UNSET_STUB",
     "AiosqlAsyncProtocol",
     "AiosqlParamType",
-    "AiosqlProtocol",
     "AiosqlSQLOperationType",
     "AiosqlSyncProtocol",
     "ArrowRecordBatch",
+    "ArrowRecordBatchReader",
+    "ArrowRecordBatchReaderProtocol",
     "ArrowRecordBatchResult",
+    "ArrowSchema",
+    "ArrowSchemaProtocol",
     "ArrowTable",
     "ArrowTableResult",
     "AttrsInstance",
@@ -660,6 +757,12 @@ __all__ = (
     "FailFastStub",
     "Gauge",
     "Histogram",
+    "NumpyArray",
+    "NumpyArrayStub",
+    "PandasDataFrame",
+    "PandasDataFrameProtocol",
+    "PolarsDataFrame",
+    "PolarsDataFrameProtocol",
     "Span",
     "Status",
     "StatusCode",

sqlspec/adapters/adbc/_types.py

@@ -4,7 +4,7 @@ from typing import TYPE_CHECKING
 from adbc_driver_manager.dbapi import Connection
 
 if TYPE_CHECKING:
-    from typing_extensions import TypeAlias
+    from typing import TypeAlias
 
     AdbcConnection: TypeAlias = Connection
 else:

sqlspec/adapters/adbc/adk/__init__.py

@@ -0,0 +1,5 @@
+"""ADBC ADK integration for Google Agent Development Kit."""
+
+from sqlspec.adapters.adbc.adk.store import AdbcADKStore
+
+__all__ = ("AdbcADKStore",)