fix(dbapi): bundle D — input validation, PEP 249 wrapping, cleanups

Nine issues from cycle 3 bundle D, all in the dbapi layer.

Input validation:
- ISSUE-82: fetchmany() rejects negative size with ProgrammingError
  rather than silently returning [] (range(-5) is empty). Mirror the
  arraysize-setter's >= 1 guard on the sync+async cursors.
- ISSUE-86: _reject_non_sequence_params now rejects str/bytes/
  bytearray/memoryview. They are iterable so qmark binding would
  silently "explode" into per-character binds — almost always a
  caller bug. Users should wrap in ``(value,)``.

Exception wrapping to satisfy PEP 249 "all DB errors funnel through
Error" contract:
- ISSUE-84: DateFromTicks / TimeFromTicks / TimestampFromTicks wrap
  NaN/inf/out-of-range with DataError instead of leaking
  ValueError/OverflowError/OSError.
- ISSUE-85: _call_client adds a trailing catch for DqliteError
  subclasses not enumerated above. A future client exception class
  cannot bypass PEP 249 wrapping.
- ISSUE-102: _datetime_from_iso8601 wraps parse failures in DataError.
- ISSUE-107: _datetime_from_unixtime wraps TypeError/OverflowError/
  OSError/ValueError in DataError (malformed server payload).

Interface completions:
- ISSUE-80: add Cursor.rownumber / AsyncCursor.rownumber property
  (PEP 249 optional). Returns the 0-based index of the next row or
  None when no result set is active.
- ISSUE-88: Time() and Timestamp() accept optional microsecond and
  tzinfo parameters for parity with stdlib datetime.time /
  datetime.datetime. Mixing driver Time() with stdlib time() no
  longer silently drops microsecond precision.

Cleanups:
- ISSUE-110: extract _is_row_returning(sql) helper at module level;
  both sync and async cursors import it. Previously duplicated
  inline in two places.
- ISSUE-113: narrow the three ``except Exception: pass`` blocks in
  _cleanup_loop_thread to specific expected exceptions (RuntimeError).
  Wider suppression hid programmer bugs during finalization.

Adds tests/test_cycle3_hardening.py with 32 regression tests across
these issues.

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

Author: antoineleclair

src/dqlitedbapi/aio/cursor.py

@@ -7,7 +7,7 @@
     _call_client,
     _convert_params,
     _convert_row,
-    _strip_leading_comments,
+    _is_row_returning,
 )
 from dqlitedbapi.exceptions import InterfaceError, NotSupportedError, ProgrammingError
 
@@ -64,6 +64,17 @@ def lastrowid(self) -> int | None:
         """Row ID of the last inserted row."""
         return self._lastrowid
 
+    @property
+    def rownumber(self) -> int | None:
+        """0-based index of the next row in the current result set.
+
+        PEP 249 optional extension. ``None`` when no result set is
+        active (ISSUE-80).
+        """
+        if self._description is None:
+            return None
+        return self._row_index
+
     @property
     def arraysize(self) -> int:
         """Number of rows to fetch at a time with fetchmany()."""
@@ -94,13 +105,7 @@ async def execute(
         conn = await self._connection._ensure_connection()
         params = _convert_params(parameters)
 
-        # Determine if this is a query that returns rows.
-        # Note: WITH ... INSERT/UPDATE/DELETE (without RETURNING) will be
-        # misrouted to query_raw_typed. This is a known limitation of the heuristic.
-        normalized = _strip_leading_comments(operation).upper()
-        is_query = normalized.startswith(("SELECT", "PRAGMA", "EXPLAIN", "WITH")) or (
-            " RETURNING " in normalized or normalized.endswith(" RETURNING")
-        )
+        is_query = _is_row_returning(operation)
 
         _, op_lock = self._connection._ensure_locks()
         async with op_lock:
@@ -191,6 +196,10 @@ async def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
 
         if size is None:
             size = self._arraysize
+        if size < 0:
+            # See sync Cursor.fetchmany: silently returning [] on a
+            # negative size hides caller bugs (ISSUE-82).
+            raise ProgrammingError(f"fetchmany size must be >= 0, got {size}")
 
         result: list[tuple[Any, ...]] = []
         for _ in range(size):

src/dqlitedbapi/connection.py

@@ -40,17 +40,23 @@ def _cleanup_loop_thread(
                 ResourceWarning,
                 stacklevel=2,
             )
+    # Narrow suppression to the specific exceptions loop/thread teardown
+    # can legitimately raise during finalization (ISSUE-113). Wider
+    # ``except Exception: pass`` would hide programmer bugs like a
+    # missing attribute reference introduced during a refactor.
     try:
         if not loop.is_closed():
             loop.call_soon_threadsafe(loop.stop)
-    except Exception:
+    except RuntimeError:
+        # Loop was closed between is_closed() and the threadsafe call.
         pass
-    with contextlib.suppress(Exception):
+    with contextlib.suppress(RuntimeError):
         thread.join(timeout=5)
     try:
         if not loop.is_closed():
             loop.close()
-    except Exception:
+    except RuntimeError:
+        # Raised if the loop was somehow restarted mid-finalization.
         pass
 
 

src/dqlitedbapi/cursor.py

@@ -35,6 +35,14 @@ async def _call_client(coro: Coroutine[Any, Any, Any]) -> Any:
       client.ProtocolError         → dbapi.InterfaceError
       client.DataError             → dbapi.DataError
       client.InterfaceError        → dbapi.InterfaceError
+      any other DqliteError        → dbapi.InterfaceError (ISSUE-85)
+
+    Every ``dqliteclient`` exception is a subclass of ``DqliteError``;
+    the trailing catch-all ensures a new client exception class cannot
+    bypass PEP 249 wrapping. PEP 249 requires all database-sourced
+    errors to surface as ``Error`` subclasses — without the fallback, a
+    future ``dqliteclient.CircuitOpenError`` or similar would leak past
+    ``except dqlitedbapi.Error`` boundaries.
     """
     try:
         return await coro
@@ -50,6 +58,13 @@ async def _call_client(coro: Coroutine[Any, Any, Any]) -> Any:
         raise DataError(str(e)) from e
     except _client_exc.InterfaceError as e:
         raise _DbapiInterfaceError(str(e)) from e
+    except _client_exc.DqliteError as e:
+        # Catch-all for any future subclass of DqliteError not enumerated
+        # above. Surface as InterfaceError rather than leaking to the
+        # caller as a non-DBAPI exception (ISSUE-85).
+        raise _DbapiInterfaceError(
+            f"unrecognized client error ({type(e).__name__}): {e}"
+        ) from e
 
 
 if TYPE_CHECKING:
@@ -76,15 +91,24 @@ def _convert_row(row: Sequence[Any], column_types: Sequence[int]) -> tuple[Any,
 
 
 def _reject_non_sequence_params(params: Any) -> None:
-    """Reject mappings and unordered containers per PEP 249 qmark rules.
+    """Reject mappings, unordered containers, and str/bytes per PEP 249 qmark rules.
 
     PEP 249: for ``qmark`` paramstyle "the sequence is mandatory and the
     driver will not accept mappings." We also reject ``set`` / ``frozenset``
     — they are sequences structurally but unordered, which silently
-    scrambles positional bindings.
+    scrambles positional bindings. And we reject ``str`` /
+    ``bytes`` / ``bytearray`` / ``memoryview`` — they are iterable, so
+    they would silently "explode" into character/byte binds and the
+    caller almost always meant ``(value,)`` instead (ISSUE-86).
     """
     if params is None:
         return
+    if isinstance(params, (str, bytes, bytearray, memoryview)):
+        raise ProgrammingError(
+            f"parameters must be a sequence of values, not "
+            f"{type(params).__name__!r}; did you mean to pass a tuple "
+            f"like (value,) with a single element?"
+        )
     if isinstance(params, Mapping):
         raise ProgrammingError(
             "qmark paramstyle requires a sequence; got a mapping. "
@@ -124,6 +148,26 @@ def _strip_leading_comments(sql: str) -> str:
     return s
 
 
+_ROW_RETURNING_PREFIXES = ("SELECT", "PRAGMA", "EXPLAIN", "WITH")
+
+
+def _is_row_returning(sql: str) -> bool:
+    """Heuristic for "does this statement return a result set?"
+
+    Single source of truth for sync and async cursors (ISSUE-110).
+    Matches leading SELECT/PRAGMA/EXPLAIN/WITH after stripping comments,
+    and catches trailing/embedded RETURNING clauses on DML.
+
+    Note: ``WITH ... INSERT/UPDATE/DELETE`` (no RETURNING) will be
+    misclassified as a query. This is a known limitation of a
+    prefix-only check — a full SQL parser is out of scope.
+    """
+    normalized = _strip_leading_comments(sql).upper()
+    if normalized.startswith(_ROW_RETURNING_PREFIXES):
+        return True
+    return " RETURNING " in normalized or normalized.endswith(" RETURNING")
+
+
 class Cursor:
     """PEP 249 compliant database cursor."""
 
@@ -183,6 +227,19 @@ def lastrowid(self) -> int | None:
         """Row ID of the last inserted row."""
         return self._lastrowid
 
+    @property
+    def rownumber(self) -> int | None:
+        """0-based index of the next row in the current result set.
+
+        PEP 249 optional extension: returns ``None`` if no result set is
+        active (no query executed, or last statement was DML without
+        RETURNING); otherwise returns the index of the row that the next
+        ``fetchone()`` would produce (ISSUE-80).
+        """
+        if self._description is None:
+            return None
+        return self._row_index
+
     @property
     def arraysize(self) -> int:
         """Number of rows to fetch at a time with fetchmany()."""
@@ -216,15 +273,7 @@ async def _execute_async(self, operation: str, parameters: Sequence[Any] | None
         conn = await self._connection._get_async_connection()
         params = _convert_params(parameters)
 
-        # Determine if this is a query that returns rows.
-        # Note: WITH ... INSERT/UPDATE/DELETE (without RETURNING) will be
-        # misrouted to query_raw_typed. This is a known limitation of the heuristic.
-        normalized = _strip_leading_comments(operation).upper()
-        is_query = normalized.startswith(("SELECT", "PRAGMA", "EXPLAIN", "WITH")) or (
-            " RETURNING " in normalized or normalized.endswith(" RETURNING")
-        )
-
-        if is_query:
+        if _is_row_returning(operation):
             columns, column_types, rows = await _call_client(
                 conn.query_raw_typed(operation, params)
             )
@@ -320,6 +369,11 @@ def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
 
         if size is None:
             size = self._arraysize
+        if size < 0:
+            # Previously ``range(-5)`` silently returned [] — hid caller
+            # bugs (ISSUE-82). ``arraysize`` setter already validates
+            # >= 1; mirror that here.
+            raise ProgrammingError(f"fetchmany size must be >= 0, got {size}")
 
         result: list[tuple[Any, ...]] = []
         for _ in range(size):

src/dqlitedbapi/types.py

@@ -1,8 +1,10 @@
 """PEP 249 type objects and constructors for dqlite."""
 
 import datetime
+import math
 from typing import Any
 
+from dqlitedbapi.exceptions import DataError
 from dqlitewire.constants import ValueType
 
 
@@ -12,31 +14,74 @@ def Date(year: int, month: int, day: int) -> datetime.date:  # noqa: N802
     return datetime.date(year, month, day)
 
 
-def Time(hour: int, minute: int, second: int) -> datetime.time:  # noqa: N802
-    """Construct a time value."""
-    return datetime.time(hour, minute, second)
+def Time(  # noqa: N802
+    hour: int,
+    minute: int,
+    second: int,
+    microsecond: int = 0,
+    tzinfo: datetime.tzinfo | None = None,
+) -> datetime.time:
+    """Construct a time value.
+
+    Accepts optional ``microsecond`` and ``tzinfo`` for parity with
+    stdlib ``datetime.time`` (ISSUE-88). PEP 249 does not require this,
+    but mixing the driver's ``Time()`` with ``datetime.time`` would
+    otherwise drop sub-second precision silently.
+    """
+    return datetime.time(hour, minute, second, microsecond, tzinfo=tzinfo)
 
 
 def Timestamp(  # noqa: N802
-    year: int, month: int, day: int, hour: int, minute: int, second: int
+    year: int,
+    month: int,
+    day: int,
+    hour: int,
+    minute: int,
+    second: int,
+    microsecond: int = 0,
+    tzinfo: datetime.tzinfo | None = None,
 ) -> datetime.datetime:
     """Construct a timestamp value."""
-    return datetime.datetime(year, month, day, hour, minute, second)
+    return datetime.datetime(year, month, day, hour, minute, second, microsecond, tzinfo=tzinfo)
+
+
+def _validate_ticks(ticks: float) -> None:
+    """Reject NaN/inf before handing to datetime.fromtimestamp.
+
+    ``fromtimestamp`` raises different stdlib exceptions depending on
+    the failure mode (``ValueError`` for NaN on some platforms,
+    ``OverflowError`` / ``OSError`` for out-of-range). Guard up front so
+    the caller always sees a single DB-API ``DataError`` (ISSUE-84).
+    """
+    if isinstance(ticks, float) and not math.isfinite(ticks):
+        raise DataError(f"Invalid timestamp ticks: {ticks}")
 
 
 def DateFromTicks(ticks: float) -> datetime.date:  # noqa: N802
     """Construct a date from a Unix timestamp."""
-    return datetime.date.fromtimestamp(ticks)
+    _validate_ticks(ticks)
+    try:
+        return datetime.date.fromtimestamp(ticks)
+    except (OverflowError, OSError, ValueError) as e:
+        raise DataError(f"Invalid timestamp ticks {ticks}: {e}") from e
 
 
 def TimeFromTicks(ticks: float) -> datetime.time:  # noqa: N802
     """Construct a time from a Unix timestamp."""
-    return datetime.datetime.fromtimestamp(ticks).time()
+    _validate_ticks(ticks)
+    try:
+        return datetime.datetime.fromtimestamp(ticks).time()
+    except (OverflowError, OSError, ValueError) as e:
+        raise DataError(f"Invalid timestamp ticks {ticks}: {e}") from e
 
 
 def TimestampFromTicks(ticks: float) -> datetime.datetime:  # noqa: N802
     """Construct a timestamp from a Unix timestamp."""
-    return datetime.datetime.fromtimestamp(ticks)
+    _validate_ticks(ticks)
+    try:
+        return datetime.datetime.fromtimestamp(ticks)
+    except (OverflowError, OSError, ValueError) as e:
+        raise DataError(f"Invalid timestamp ticks {ticks}: {e}") from e
 
 
 def Binary(data: bytes) -> bytes:  # noqa: N802
@@ -161,6 +206,11 @@ def _datetime_from_iso8601(text: str) -> datetime.datetime | None:
     PEP 249 NULL semantics.
 
     Naive input round-trips as naive; aware input preserves the offset.
+
+    A malformed string from the server (bug, corruption, or MitM) would
+    otherwise escape as a raw ``ValueError``; wrap as ``DataError`` to
+    satisfy PEP 249's "all DB errors funnel through Error" contract
+    (ISSUE-102).
     """
     if not text:
         return None
@@ -172,7 +222,7 @@ def _datetime_from_iso8601(text: str) -> datetime.datetime | None:
     try:
         d = datetime.date.fromisoformat(s)
     except ValueError as exc:
-        raise ValueError(f"Cannot parse ISO 8601 datetime: {text!r}") from exc
+        raise DataError(f"Cannot parse ISO 8601 datetime from server: {text!r}") from exc
     return datetime.datetime(d.year, d.month, d.day)
 
 
@@ -181,8 +231,15 @@ def _datetime_from_unixtime(value: int) -> datetime.datetime:
 
     UNIXTIME is unambiguously seconds-since-epoch in UTC, so returning a
     UTC-aware value is faithful. Callers that want local time can convert.
+
+    A corrupt server or MitM-modified bytes could deliver a non-integer
+    or out-of-range value; wrap the resulting stdlib exceptions as
+    ``DataError`` (ISSUE-107).
     """
-    return datetime.datetime.fromtimestamp(value, tz=datetime.UTC)
+    try:
+        return datetime.datetime.fromtimestamp(value, tz=datetime.UTC)
+    except (TypeError, OverflowError, OSError, ValueError) as e:
+        raise DataError(f"Invalid UNIXTIME from server: {value!r}") from e
 
 
 def _convert_bind_param(value: Any) -> Any: