Narrow return types on the async dialect adapter surface

Swap several Any return annotations for the precise types the bodies
already return: execute/executemany -> None, __iter__ -> Iterator[Any],
import_dbapi -> types.ModuleType, and _DqliteDate.result_processor ->
Callable[[Any], Any] | None. AsyncAdaptedConnection.__init__ now types
its parameter as the concrete AsyncConnection for callers while the
stored attribute stays Any to satisfy SQLAlchemy's wider Protocol.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antoineleclair

src/sqlalchemydqlite/aio.py

@@ -1,9 +1,10 @@
 """Async dqlite dialect for SQLAlchemy."""
 
 import contextlib
+import types
 from collections import deque
-from collections.abc import Sequence
-from typing import Any
+from collections.abc import Iterator, Sequence
+from typing import TYPE_CHECKING, Any
 
 from sqlalchemy import pool
 from sqlalchemy.engine import URL, AdaptedConnection
@@ -14,6 +15,9 @@
 from dqlitedbapi.exceptions import InterfaceError, NotSupportedError, OperationalError
 from sqlalchemydqlite.base import DqliteDialect
 
+if TYPE_CHECKING:
+    from dqlitedbapi.aio import AsyncConnection
+
 __all__ = ["AsyncAdaptedConnection", "AsyncAdaptedCursor", "DqliteDialect_aio"]
 
 
@@ -42,7 +46,7 @@ async def _async_soft_close(self) -> None:
     def close(self) -> None:
         self._rows.clear()
 
-    def execute(self, operation: str, parameters: Any = None) -> Any:
+    def execute(self, operation: str, parameters: Any = None) -> None:
         # Clear buffered state FIRST so a CancelledError (or any other
         # exception) during execute/fetchall leaves the adapter in a
         # "no active result" state rather than carrying stale rows
@@ -68,7 +72,7 @@ def execute(self, operation: str, parameters: Any = None) -> Any:
         finally:
             await_only(cursor.close())
 
-    def executemany(self, operation: str, seq_of_parameters: Any) -> Any:
+    def executemany(self, operation: str, seq_of_parameters: Any) -> None:
         # Clear state up-front so cancellation mid-call doesn't leak
         # a previous execution's buffered rows.
         self.description = None
@@ -139,7 +143,7 @@ def nextset(self) -> bool | None:
     def scroll(self, value: int, mode: str = "relative") -> None:
         raise NotSupportedError("dqlite cursors are not scrollable")
 
-    def __iter__(self) -> Any:
+    def __iter__(self) -> Iterator[Any]:
         while self._rows:
             yield self._rows.popleft()
 
@@ -158,8 +162,13 @@ class AsyncAdaptedConnection(AdaptedConnection):
     greenlet context.
     """
 
-    def __init__(self, connection: Any) -> None:
-        self._connection = connection
+    def __init__(self, connection: "AsyncConnection") -> None:
+        # ``_connection`` is the concrete ``dqlitedbapi.aio.AsyncConnection``
+        # this adapter wraps; SQLAlchemy's parent ``AdaptedConnection``
+        # declares the attribute with a wider Protocol type, so we keep
+        # the store on ``Any`` and rely on the annotation here to document
+        # the intended input shape.
+        self._connection: Any = connection
 
     def cursor(self) -> AsyncAdaptedCursor:
         return AsyncAdaptedCursor(self)
@@ -225,7 +234,7 @@ def get_pool_class(cls, url: URL) -> type[pool.Pool]:
         return AsyncAdaptedQueuePool
 
     @classmethod
-    def import_dbapi(cls) -> Any:
+    def import_dbapi(cls) -> types.ModuleType:
         from dqlitedbapi import aio
 
         return aio

src/sqlalchemydqlite/base.py

@@ -3,6 +3,7 @@
 import contextlib
 import datetime
 import math
+import types
 import warnings
 from collections.abc import Callable
 from typing import Any
@@ -49,7 +50,7 @@ class _DqliteDate(sqltypes.Date):
     def bind_processor(self, dialect: Any) -> None:
         return None
 
-    def result_processor(self, dialect: Any, coltype: Any) -> Any:
+    def result_processor(self, dialect: Any, coltype: Any) -> Callable[[Any], Any] | None:
         def process(value: Any) -> Any:
             if isinstance(value, datetime.datetime):
                 # Deliberate: tzinfo is dropped. See class docstring.
@@ -148,7 +149,7 @@ class DqliteDialect(SQLiteDialect):
     }
 
     @classmethod
-    def import_dbapi(cls) -> Any:
+    def import_dbapi(cls) -> types.ModuleType:
         import dqlitedbapi
 
         return dqlitedbapi

tests/test_async_adapter.py

@@ -230,3 +230,27 @@ def test_extra_positional_argument_rejected(self) -> None:
         cursor = AsyncAdaptedCursor.__new__(AsyncAdaptedCursor)
         with pytest.raises(TypeError):
             cursor.setinputsizes([10], 20)  # type: ignore[call-arg]
+
+
+class TestAioAdapterReturnAnnotations:
+    """Lock in the narrower return annotations on the async adapter surface."""
+
+    def test_execute_and_executemany_return_none(self) -> None:
+        import inspect
+
+        from sqlalchemydqlite.aio import AsyncAdaptedCursor
+
+        sig = inspect.signature(AsyncAdaptedCursor.execute)
+        assert sig.return_annotation is None or sig.return_annotation == "None"
+
+        sig = inspect.signature(AsyncAdaptedCursor.executemany)
+        assert sig.return_annotation is None or sig.return_annotation == "None"
+
+    def test_iter_returns_iterator(self) -> None:
+        import inspect
+
+        from sqlalchemydqlite.aio import AsyncAdaptedCursor
+
+        sig = inspect.signature(AsyncAdaptedCursor.__iter__)
+        # Accept either the Iterator annotation object or the stringified form.
+        assert "Iterator" in str(sig.return_annotation)