Document chained-equality idiom for unhashable PEP 249 type sentinels

_DBAPIType objects (STRING/BINARY/NUMBER/DATETIME/ROWID) are intentionally
unhashable so that no canonical hash silently violates the hash-eq invariant
when a multi-value sentinel (NUMBER == FLOAT_CODE, NUMBER == INT_CODE) is
used as a dict key. That decision is correct, but the user-facing
introspection idiom — chained equality vs. set membership — was not pinned.

A naive caller writing `desc[i][1] in {STRING, NUMBER}` gets a noisy
TypeError where the PEP 249 idiom `desc[i][1] == STRING or desc[i][1] ==
NUMBER` works. Document the chained-equality form in the class docstring
and the README "Limitations vs stdlib" section, and add a regression pin
for the documented idiom against wire-level ValueType ints.

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

Author: antoineleclair

README.md

@@ -153,6 +153,24 @@ borrowed from one.
   `sqlite3`'s implicit-transaction model — see Transactions above.
 - **SERIALIZABLE isolation only.** Every statement is ordered by Raft;
   weaker isolation levels aren't exposed.
+- **PEP 249 type sentinels (`STRING`, `BINARY`, `NUMBER`, `DATETIME`,
+  `ROWID`) are unhashable.** Use chained equality against
+  `description[i][1]`, NOT set/dict membership:
+
+  ```python
+  type_code = cur.description[i][1]
+  if type_code == STRING or type_code == NUMBER:  # OK
+      ...
+  if type_code in {STRING, NUMBER}:               # raises TypeError
+      ...
+  ```
+
+  The sentinels wrap multiple wire type codes (`NUMBER` covers
+  INTEGER+FLOAT+BOOLEAN, `DATETIME` covers DATE+TIMESTAMP+ISO8601),
+  so no canonical hash can satisfy the Python hash-eq invariant.
+  Stdlib `sqlite3` doesn't export these sentinels at all, so the
+  chained-equality form is the cross-driver-portable idiom.
+
 - **`WITH ... INSERT/UPDATE/DELETE` (CTE-prefixed pure DML) reports
   zero `rowcount` and no `lastrowid`.** The driver dispatches between
   the row-returning and execute paths via a prefix-based heuristic;

src/dqlitedbapi/types.py

@@ -202,6 +202,19 @@ class _DBAPIType:
     would make ``{NUMBER: x}[FLOAT_CODE]`` raise ``KeyError`` despite
     ``NUMBER == FLOAT_CODE`` being True. Refusing to hash turns that
     silent miss into a noisy ``TypeError``.
+
+    **Caller idiom** — introspecting ``description[i][1]`` against
+    type sentinels: use chained equality, NOT set membership::
+
+        type_code = cur.description[i][1]
+        if type_code == STRING or type_code == NUMBER:
+            ...
+
+    Set/dict membership (``type_code in {STRING, NUMBER}``) raises
+    ``TypeError: unhashable type`` for the reason above. The
+    chained-``==`` form is the PEP 249 idiom and works against this
+    driver and stdlib ``sqlite3`` (which does not export these
+    sentinels at all).
     """
 
     def __init__(self, *values: str | int | ValueType, _name: str = "") -> None:

tests/test_dbapi_type_hash_consistency.py

@@ -39,6 +39,31 @@ def test_cannot_be_dict_keys(self) -> None:
             dict([(NUMBER, "x")])  # noqa: C406 -- literal triggers B018
 
 
+class TestDocumentedIdiom:
+    """Pin the chained-equality idiom documented in the class
+    docstring and README. Without this pin a future refactor that
+    implements ``__hash__ = lambda self: id(self)`` (which would
+    re-enable ``in {...}`` syntactically) would silently break
+    multi-value sentinel dispatch — set membership would fall back
+    to identity, missing every legitimate ``ValueType`` int.
+    """
+
+    def test_type_in_set_raises_typeerror(self) -> None:
+        # The shape that PEP 249 callers might naively try first.
+        with pytest.raises(TypeError, match="unhashable"):
+            _ = STRING in {STRING, NUMBER}
+
+    def test_chained_equality_is_the_documented_idiom(self) -> None:
+        from dqlitewire.constants import ValueType
+
+        # Wire type code as seen in description[i][1].
+        type_code = int(ValueType.TEXT)
+        assert type_code == STRING or type_code == NUMBER  # noqa: PLR1714
+
+        type_code = int(ValueType.INTEGER)
+        assert type_code == STRING or type_code == NUMBER  # noqa: PLR1714
+
+
 class TestDbapiTypesDistinct:
     """Distinct _DBAPIType instances must not collide under eq."""