fix(core,adapters): improve driver lifecycle, query compilation, and adapter consistency

.pre-commit-config.yaml

@@ -18,7 +18,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.16.9"
+    rev: "v0.16.10"
     hooks:
       - id: ruff-check
         args: ["--fix"]

sqlspec/__init__.py

@@ -1,8 +1,6 @@
 """SQLSpec: Type-safe SQL query mapper for Python."""
 
 # ruff: noqa: E402
-# Suppress noisy Google library deprecation warnings about Python version support.
-# These are informational and clutter CLI output unnecessarily.
 import warnings as _warnings
 
 _warnings.filterwarnings(
@@ -166,6 +164,7 @@
     "adapters",
     "base",
     "builder",
+    "config",
     "core",
     "create_event",
     "create_statement_observer",
@@ -180,6 +179,7 @@
     "matches_param_type",
     "migrations",
     "nanoid",
+    "observability",
     "register_param_type",
     "resolve_param_type",
     "sql",
@@ -295,8 +295,6 @@ def __dir__() -> list[str]:
     return sorted(set(globals()) | _EXPORTS.keys())
 
 
-# Native cross-module initialization is not protected by Python import locks.
-# Retain eager exports in compiled wheels until mypyc supports lazy concurrency.
 if _COMPILED:
     for _name in __all__:
         if _name not in globals():

sqlspec/_typing.py

@@ -140,8 +140,6 @@ class DataclassProtocol(Protocol):
 
 T = TypeVar("T")
 
-# Always define stub types for type checking
-
 
 class BaseModelStub:
     """Placeholder implementation."""
@@ -193,6 +191,8 @@ def model_dump_json(  # noqa: PLR0913
 class TypeAdapterStub:
     """Placeholder implementation."""
 
+    __slots__ = ("_type",)
+
     def __init__(
         self,
         type: Any,  # noqa: A002
@@ -225,9 +225,6 @@ class FailFastStub:
     fail_fast: bool = True
 
 
-# Always define stub types for msgspec
-
-
 @dataclass_transform()
 class StructStub:
     """Placeholder implementation."""
@@ -241,7 +238,7 @@ def __init__(self, **kwargs: Any) -> None:
 
 
 def convert_stub(  # noqa: PLR0913
-    obj: Any,  # noqa: ARG001
+    obj: Any,
     type: Any,  # noqa: A002,ARG001
     *,
     strict: bool = True,  # noqa: ARG001
@@ -251,7 +248,7 @@ def convert_stub(  # noqa: PLR0913
     str_keys: bool = False,  # noqa: ARG001
 ) -> Any:
     """Placeholder implementation."""
-    return {}
+    return obj
 
 
 def msgspec_fields_stub(type_: Any, /) -> "tuple[Any, ...]":  # noqa: ARG001
@@ -265,7 +262,6 @@ class UnsetTypeStub(enum.Enum):
 
 UNSET_STUB = UnsetTypeStub.UNSET
 
-# Try to import real implementations at runtime
 try:
     from msgspec import UNSET as _REAL_UNSET
     from msgspec import Struct as _RealStruct
@@ -289,7 +285,6 @@ class UnsetTypeStub(enum.Enum):
     msgspec_fields = msgspec_fields_stub  # type: ignore[assignment]
 
 
-# Always define stub type for DTOData
 @runtime_checkable
 class DTODataStub(Protocol[T]):
     """Placeholder implementation."""
@@ -311,7 +306,6 @@ def as_builtins(self) -> Any:
         return {}
 
 
-# Always define stub types for attrs
 @dataclass_transform()
 class AttrsInstanceStub:
     """Placeholder Implementation for attrs classes"""
@@ -376,9 +370,6 @@ class EmptyEnum(Enum):
 class ArrowTableResult(Protocol):
     """This is a typed shim for pyarrow.Table."""
 
-    def to_batches(self, batch_size: int) -> Any:
-        return None
-
     @property
     def num_rows(self) -> int:
         return 0
@@ -387,6 +378,9 @@ def num_rows(self) -> int:
     def num_columns(self) -> int:
         return 0
 
+    def to_batches(self, batch_size: int) -> Any:
+        return None
+
     def to_pydict(self) -> dict[str, Any]:
         return {}
 
@@ -441,24 +435,28 @@ def slice(self, offset: int = 0, length: "int | None" = None) -> Any:
 class ArrowSchemaProtocol(Protocol):
     """Typed shim for pyarrow.Schema."""
 
-    def field(self, i: int) -> Any:
-        """Get field by index."""
-        ...
+    def __len__(self) -> int:
+        """Get number of fields."""
+        return 0
 
     @property
     def names(self) -> "list[str]":
         """Get list of field names."""
         ...
 
-    def __len__(self) -> int:
-        """Get number of fields."""
-        return 0
+    def field(self, i: int) -> Any:
+        """Get field by index."""
+        ...
 
 
 @runtime_checkable
 class ArrowRecordBatchReaderProtocol(Protocol):
     """Typed shim for pyarrow.RecordBatchReader."""
 
+    def __iter__(self) -> "Iterable[Any]":
+        """Iterate over batches."""
+        ...
+
     def read_all(self) -> Any:
         """Read all batches into a table."""
         ...
@@ -467,10 +465,6 @@ def read_next_batch(self) -> Any:
         """Read next batch."""
         ...
 
-    def __iter__(self) -> "Iterable[Any]":
-        """Iterate over batches."""
-        ...
-
 
 _ARROW_TABLE_SHIM = ArrowTableResult
 _ARROW_RECORD_BATCH_SHIM = ArrowRecordBatchResult
@@ -526,6 +520,14 @@ def tolist(self) -> "list[Any]":
 
 
 class _SpanShim:
+    __slots__ = ()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
+        return None
+
     def set_attribute(self, key: str, value: Any) -> None:
         return None
 
@@ -544,19 +546,15 @@ def set_status(self, status: Any, description: "str | None" = None) -> None:
     def end(self, end_time: "int | None" = None) -> None:
         return None
 
-    def __enter__(self) -> Self:
-        return self
-
-    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
-        return None
-
 
 _SPAN_SHIM = _SpanShim
 _SPAN_SHIM.__name__ = "Span"
 _SPAN_SHIM.__qualname__ = "Span"
 
 
 class _TracerShim:
+    __slots__ = ()
+
     def start_span(
         self,
         name: str,
@@ -577,6 +575,8 @@ def start_span(
 
 
 class _TraceModule:
+    __slots__ = ()
+
     def get_tracer(
         self,
         instrumenting_module_name: str,
@@ -589,17 +589,19 @@ def get_tracer(
     def get_tracer_provider(self) -> Any:  # pragma: no cover
         return None
 
-    TracerProvider = type(None)  # Shim for TracerProvider if needed elsewhere
-    StatusCode = type(None)  # Shim for StatusCode
-    Status = type(None)  # Shim for Status
+    TracerProvider = type(None)
+    StatusCode = type(None)
+    Status = type(None)
 
 
 _TRACE_SHIM = _TraceModule()
 _STATUS_CODE_SHIM = type(None)
 _STATUS_SHIM = type(None)
 
 
-class _Metric:  # Base shim for metrics
+class _Metric:
+    __slots__ = ()
+
     def __init__(
         self,
         name: str,
@@ -609,7 +611,7 @@ def __init__(
         subsystem: str = "",
         unit: str = "",
         registry: Any = None,
-        ejemplar_fn: Any = None,
+        exemplar_fn: Any = None,
         buckets: Any = None,
         **_: Any,
     ) -> None:
@@ -620,6 +622,8 @@ def labels(self, *labelvalues: str, **labelkwargs: str) -> "_MetricInstance":
 
 
 class _MetricInstance:
+    __slots__ = ()
+
     def inc(self, amount: float = 1) -> None:
         return None
 
@@ -634,6 +638,8 @@ def observe(self, amount: float) -> None:
 
 
 class _CounterShim(_Metric):
+    __slots__ = ()
+
     def labels(self, *labelvalues: str, **labelkwargs: str) -> "_MetricInstance":
         return _MetricInstance()  # pragma: no cover
 
@@ -644,6 +650,8 @@ def labels(self, *labelvalues: str, **labelkwargs: str) -> "_MetricInstance":
 
 
 class _GaugeShim(_Metric):
+    __slots__ = ()
+
     def labels(self, *labelvalues: str, **labelkwargs: str) -> "_MetricInstance":
         return _MetricInstance()  # pragma: no cover
 
@@ -654,6 +662,8 @@ def labels(self, *labelvalues: str, **labelkwargs: str) -> "_MetricInstance":
 
 
 class _HistogramShim(_Metric):
+    __slots__ = ()
+
     def labels(self, *labelvalues: str, **labelkwargs: str) -> "_MetricInstance":
         return _MetricInstance()  # pragma: no cover
 

sqlspec/adapters/__init__.py

@@ -0,0 +1,3 @@
+"""SQLSpec database adapters namespace package."""
+
+__all__ = ()

sqlspec/adapters/adbc/__init__.py

@@ -1,3 +1,5 @@
+"""ADBC adapter for SQLSpec."""
+
 from sqlspec.adapters.adbc._typing import AdbcConnection
 from sqlspec.adapters.adbc.config import AdbcConfig, AdbcConnectionParams, AdbcDriverFeatures
 from sqlspec.adapters.adbc.driver import AdbcCursor, AdbcDriver, AdbcExceptionHandler

sqlspec/adapters/adbc/_typing.py

@@ -1,40 +1,33 @@
-# pyright: reportCallIssue=false, reportAttributeAccessIssue=false, reportArgumentType=false
 """ADBC 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
+from typing import TYPE_CHECKING, Any, TypeAlias
 
 from adbc_driver_manager import Error as _AdbcNativeError
 from adbc_driver_manager import NotSupportedError as AdbcNotSupportedError
 from adbc_driver_manager import OperationalError as AdbcOperationalError
 from adbc_driver_manager.dbapi import Connection
 from adbc_driver_manager.dbapi import Cursor as _AdbcRawCursor
 
+from sqlspec.adapters.adbc.core import resolve_dialect_name
 from sqlspec.typing import import_optional_attr
 
-_AdbcConnection = Connection
-
 if TYPE_CHECKING:
     from collections.abc import Callable
     from types import TracebackType
-    from typing import TypeAlias
 
     from adbc_driver_flightsql import DatabaseOptions as AdbcFlightSqlDatabaseOptions
 
     from sqlspec.adapters.adbc.driver import AdbcDriver
     from sqlspec.core import StatementConfig
 
-    AdbcConnection: TypeAlias = _AdbcConnection
-    AdbcRawCursor: TypeAlias = _AdbcRawCursor
-    AdbcNativeError: TypeAlias = _AdbcNativeError
-else:
-    AdbcConnection = _AdbcConnection
-    AdbcRawCursor = _AdbcRawCursor
-    AdbcNativeError = _AdbcNativeError
+AdbcConnection: TypeAlias = Connection
+AdbcRawCursor: TypeAlias = _AdbcRawCursor
+AdbcNativeError: TypeAlias = _AdbcNativeError
 
 __all__ = (
     "AdbcConnection",
@@ -105,7 +98,6 @@ def __init__(
         self._driver: AdbcDriver | None = None
 
     def __enter__(self) -> "AdbcDriver":
-        from sqlspec.adapters.adbc.core import resolve_dialect_name
         from sqlspec.adapters.adbc.driver import AdbcDriver
 
         self._connection = self._acquire_connection()