Tighten DBAPI conformance: type-object compare, qmark validation, dedupe

Three related PEP 249 / cleanup fixes:

ISSUE-06 — cursor.description[i][1] is the wire ValueType integer
(e.g. 10 for ISO8601). PEP 249 says the module type objects must
compare equal to that value. _DBAPIType now accepts both uppercase
SQL type name strings and wire ValueType ints. Added mappings for
STRING/BINARY/NUMBER/DATETIME/ROWID to the matching wire codes.

ISSUE-07 — reject mapping and set/frozenset bind parameters with
ProgrammingError. PEP 249 specifies qmark requires a sequence. A
dict silently iterated as keys before; sets would silently scramble
positional bindings.

ISSUE-13 — removed the duplicate _strip_leading_comments from
aio/cursor.py; it now imports the helper from the sync cursor
module.

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

Author: antoineleclair

src/dqlitedbapi/aio/cursor.py

@@ -3,30 +3,14 @@
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any
 
-from dqlitedbapi.cursor import _convert_params, _convert_row
+from dqlitedbapi.cursor import _convert_params, _convert_row, _strip_leading_comments
 from dqlitedbapi.exceptions import InterfaceError
 
 if TYPE_CHECKING:
     from dqlitedbapi.aio.connection import AsyncConnection
 
 
-def _strip_leading_comments(sql: str) -> str:
-    """Strip leading SQL comments (-- and /* */) and whitespace."""
-    s = sql.strip()
-    while True:
-        if s.startswith("--"):
-            newline = s.find("\n")
-            if newline == -1:
-                return ""
-            s = s[newline + 1 :].strip()
-        elif s.startswith("/*"):
-            end = s.find("*/")
-            if end == -1:
-                return s
-            s = s[end + 2 :].strip()
-        else:
-            break
-    return s
+__all__ = ["AsyncCursor", "_strip_leading_comments"]
 
 
 class AsyncCursor:

src/dqlitedbapi/cursor.py

@@ -1,11 +1,11 @@
 """PEP 249 Cursor implementation for dqlite."""
 
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from typing import TYPE_CHECKING, Any
 
 from dqlitewire.constants import ValueType
 
-from dqlitedbapi.exceptions import InterfaceError
+from dqlitedbapi.exceptions import InterfaceError, ProgrammingError
 from dqlitedbapi.types import (
     _convert_bind_param,
     _datetime_from_iso8601,
@@ -35,8 +35,31 @@ def _convert_row(row: Sequence[Any], column_types: Sequence[int]) -> tuple[Any,
     return tuple(result)
 
 
+def _reject_non_sequence_params(params: Any) -> None:
+    """Reject mappings and unordered containers 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.
+    """
+    if params is None:
+        return
+    if isinstance(params, Mapping):
+        raise ProgrammingError(
+            "qmark paramstyle requires a sequence; got a mapping. "
+            "Use a list or tuple positionally matching the ? placeholders."
+        )
+    if isinstance(params, (set, frozenset)):
+        raise ProgrammingError(
+            "qmark paramstyle requires an ordered sequence; got a set. "
+            "Use a list or tuple positionally matching the ? placeholders."
+        )
+
+
 def _convert_params(params: Sequence[Any] | None) -> list[Any] | None:
     """Convert driver-level bind parameters (e.g. datetime) to wire primitives."""
+    _reject_non_sequence_params(params)
     if params is None:
         return None
     return [_convert_bind_param(p) for p in params]

src/dqlitedbapi/types.py

@@ -3,6 +3,8 @@
 import datetime
 from typing import Any
 
+from dqlitewire.constants import ValueType
+
 
 # Type constructors
 def Date(year: int, month: int, day: int) -> datetime.date:  # noqa: N802
@@ -42,27 +44,69 @@ def Binary(data: bytes) -> bytes:  # noqa: N802
     return bytes(data)
 
 
-# Type objects for column type checking
+# Type objects for column type checking.
+#
+# PEP 249: "These objects represent a data type as represented in the
+# database. The module exports these objects: STRING, BINARY, NUMBER,
+# DATETIME, ROWID. The module should export a comparison for these types
+# and the object returned in Cursor.description[i][1]."
+#
+# Cursor.description[i][1] here is a wire-level ``ValueType`` integer
+# (e.g. 10 for ISO8601). The type objects below compare equal to both
+# the uppercase SQL type name strings (for declared-type matching) and
+# the matching ``ValueType`` ints.
 class _DBAPIType:
-    """Base type for DB-API type objects."""
+    """Base type for DB-API type objects. Compares equal to matching
+    uppercase SQL type names (str) and wire-level ``ValueType`` codes
+    (int).
+    """
 
-    def __init__(self, *values: str) -> None:
-        self.values = set(values)
+    def __init__(self, *values: str | int | ValueType) -> None:
+        normalized: set[str | int] = set()
+        for v in values:
+            if isinstance(v, ValueType):
+                normalized.add(int(v))
+            else:
+                normalized.add(v)
+        self.values = normalized
 
     def __eq__(self, other: object) -> bool:
         if isinstance(other, str):
             return other.upper() in self.values
+        if isinstance(other, ValueType):
+            return int(other) in self.values
+        if isinstance(other, int) and not isinstance(other, bool):
+            return other in self.values
         return NotImplemented
 
     def __hash__(self) -> int:
         return hash(frozenset(self.values))
 
 
-STRING = _DBAPIType("TEXT", "VARCHAR", "CHAR", "CLOB")
-BINARY = _DBAPIType("BLOB", "BINARY", "VARBINARY")
-NUMBER = _DBAPIType("INTEGER", "INT", "SMALLINT", "BIGINT", "REAL", "FLOAT", "DOUBLE", "NUMERIC")
-DATETIME = _DBAPIType("DATE", "TIME", "TIMESTAMP", "DATETIME")
-ROWID = _DBAPIType("ROWID", "INTEGER PRIMARY KEY")
+STRING = _DBAPIType("TEXT", "VARCHAR", "CHAR", "CLOB", ValueType.TEXT)
+BINARY = _DBAPIType("BLOB", "BINARY", "VARBINARY", ValueType.BLOB)
+NUMBER = _DBAPIType(
+    "INTEGER",
+    "INT",
+    "SMALLINT",
+    "BIGINT",
+    "REAL",
+    "FLOAT",
+    "DOUBLE",
+    "NUMERIC",
+    ValueType.INTEGER,
+    ValueType.FLOAT,
+    ValueType.BOOLEAN,
+)
+DATETIME = _DBAPIType(
+    "DATE",
+    "TIME",
+    "TIMESTAMP",
+    "DATETIME",
+    ValueType.ISO8601,
+    ValueType.UNIXTIME,
+)
+ROWID = _DBAPIType("ROWID", "INTEGER PRIMARY KEY", ValueType.INTEGER)
 
 
 # Internal conversion helpers.

tests/test_param_validation.py

@@ -0,0 +1,48 @@
+"""PEP 249 qmark parameter validation tests (ISSUE-07).
+
+PEP 249: for ``qmark`` paramstyle, "the sequence is mandatory and the
+driver will not accept mappings." We additionally reject ``set``/
+``frozenset`` because they are unordered and would silently scramble
+positional bindings.
+"""
+
+import pytest
+
+from dqlitedbapi.cursor import _reject_non_sequence_params
+from dqlitedbapi.exceptions import ProgrammingError
+
+
+class TestRejectMappings:
+    def test_dict_rejected(self) -> None:
+        with pytest.raises(ProgrammingError, match="mapping"):
+            _reject_non_sequence_params({"x": 1})
+
+    def test_ordered_dict_rejected(self) -> None:
+        from collections import OrderedDict
+
+        with pytest.raises(ProgrammingError, match="mapping"):
+            _reject_non_sequence_params(OrderedDict(a=1))
+
+
+class TestRejectUnorderedSequences:
+    def test_set_rejected(self) -> None:
+        with pytest.raises(ProgrammingError, match="set"):
+            _reject_non_sequence_params({1, 2, 3})
+
+    def test_frozenset_rejected(self) -> None:
+        with pytest.raises(ProgrammingError, match="set"):
+            _reject_non_sequence_params(frozenset({1, 2, 3}))
+
+
+class TestAccept:
+    def test_list_accepted(self) -> None:
+        _reject_non_sequence_params([1, 2, 3])  # no raise
+
+    def test_tuple_accepted(self) -> None:
+        _reject_non_sequence_params((1, 2, 3))  # no raise
+
+    def test_none_accepted(self) -> None:
+        _reject_non_sequence_params(None)  # no raise
+
+    def test_empty_list_accepted(self) -> None:
+        _reject_non_sequence_params([])  # no raise

tests/test_types_dbapi_compare.py

@@ -0,0 +1,73 @@
+"""PEP 249 type-object comparison tests (ISSUE-06).
+
+Per PEP 249 the module's type objects (STRING, BINARY, NUMBER, DATETIME,
+ROWID) must compare equal to whatever `cursor.description[i][1]` carries.
+We carry the wire `ValueType` integer there, so the type objects have to
+compare equal to the integer code too — not just to uppercase SQL type
+name strings.
+"""
+
+import pytest
+from dqlitewire.constants import ValueType
+
+from dqlitedbapi import BINARY, DATETIME, NUMBER, ROWID, STRING
+
+
+class TestStringType:
+    def test_equals_sql_type_names(self) -> None:
+        assert STRING == "TEXT"
+        assert STRING == "varchar"
+        assert STRING == "CLOB"
+
+    def test_equals_wire_text_value_type(self) -> None:
+        assert STRING == ValueType.TEXT
+        assert STRING == int(ValueType.TEXT)
+
+    def test_does_not_equal_non_text_wire_types(self) -> None:
+        assert not (STRING == ValueType.INTEGER)
+        assert not (STRING == ValueType.BLOB)
+        assert not (STRING == ValueType.ISO8601)
+
+
+class TestBinaryType:
+    def test_equals_blob_wire_type(self) -> None:
+        assert BINARY == ValueType.BLOB
+        assert BINARY == int(ValueType.BLOB)
+        assert BINARY == "BLOB"
+
+
+class TestNumberType:
+    @pytest.mark.parametrize("vt", [ValueType.INTEGER, ValueType.FLOAT, ValueType.BOOLEAN])
+    def test_equals_numeric_wire_types(self, vt: ValueType) -> None:
+        assert NUMBER == vt
+        assert NUMBER == int(vt)
+
+    def test_does_not_equal_text(self) -> None:
+        assert not (NUMBER == ValueType.TEXT)
+
+
+class TestDatetimeType:
+    @pytest.mark.parametrize("vt", [ValueType.ISO8601, ValueType.UNIXTIME])
+    def test_equals_datetime_wire_types(self, vt: ValueType) -> None:
+        assert DATETIME == vt
+        assert DATETIME == int(vt)
+
+    def test_equals_declared_type_names(self) -> None:
+        assert DATETIME == "DATETIME"
+        assert DATETIME == "DATE"
+        assert DATETIME == "timestamp"
+
+
+class TestRowidType:
+    def test_equals_integer_wire_type(self) -> None:
+        assert ROWID == ValueType.INTEGER
+        assert ROWID == int(ValueType.INTEGER)
+
+
+class TestHashability:
+    def test_types_still_hashable_after_int_mix(self) -> None:
+        # Mixed str/int contents mustn't break dict-key or set-member use.
+        types_set = {STRING, BINARY, NUMBER, DATETIME, ROWID}
+        assert len(types_set) == 5
+        d = {STRING: "s", NUMBER: "n"}
+        assert d[STRING] == "s"