Drop false stdlib-parity claim from fetchmany(0) docstring

Cursor.fetchmany / AsyncCursor.fetchmany advertised "stdlib sqlite3
parity" for the size=0 corner case. That claim is not reliable:
stdlib's fetchmany(0) behaviour varies across Python / sqlite
releases (some drain the result set, others return []), so dqlite
returning [] is parity with some versions and divergence from
others. The parity claim leaks a guarantee dqlite cannot keep.

Replace the parity wording with an explicit cross-driver matrix
that names what dqlite does (returns [] deterministically), how
stdlib's behaviour is version-dependent, and how psycopg3 treats
0 as a "use arraysize" sentinel. Cross-driver porters now have
the matrix instead of a false parity claim.

Documentation-only; no behaviour change.

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

Author: antoineleclair

src/dqlitedbapi/aio/cursor.py

@@ -708,14 +708,19 @@ async def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
 
         Returns an empty list when no more rows are available OR when
         no result set is active (DML-only / never-executed). Stdlib
-        parity with ``sqlite3.Cursor.fetchmany`` matching the
-        ``fetchone`` parity already in place.
-
-        **Divergence from psycopg3**: an explicit ``size=0`` returns
-        ``[]`` here (stdlib ``sqlite3`` parity). psycopg3 treats
-        ``size=0`` as "use ``self.arraysize``". Pass ``None`` or
-        omit ``size`` to default to ``self.arraysize``. See sync
-        sibling for the rationale.
+        parity with ``sqlite3.Cursor.fetchmany`` for the "no result
+        set" case matching the ``fetchone`` parity already in place.
+
+        **``size=0`` divergence (cross-driver matrix)**: dqlite
+        returns ``[]`` deterministically. This differs from stdlib
+        ``sqlite3`` (whose behaviour for ``fetchmany(0)`` is
+        version-dependent — some Python/sqlite releases drain the
+        result set, others return ``[]``) and from psycopg3 (which
+        treats ``0`` as the sentinel "use ``self.arraysize``").
+        Cross-driver code should pass an explicit positive size,
+        use ``None`` / omit ``size`` to default to ``self.arraysize``,
+        or rely on ``fetchall()`` to drain. See sync sibling for the
+        full rationale.
         """
         del self.messages[:]
         self._check_closed()

src/dqlitedbapi/cursor.py

@@ -1778,20 +1778,26 @@ def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
         Returns an empty list when no more rows are available. ``size``
         defaults to ``self.arraysize``.
 
-        Stdlib parity: ``sqlite3.Cursor.fetchmany()`` after a DML
-        (no result set active) returns ``[]`` rather than raising,
-        matching the ``fetchone`` parity already in place. Cross-
-        driver code that polls ``cur.fetchmany(N) or default`` after
-        a connect-and-cursor sequence works on stdlib and dqlite.
-
-        **Divergence from psycopg3**: an explicit ``size=0`` returns
-        ``[]`` here (stdlib ``sqlite3`` parity). psycopg3 treats
-        ``size=0`` as the sentinel meaning "use ``self.arraysize``"
-        (its default IS ``size: int = 0``, not ``None``). Cross-
-        driver code ported from psycopg that calls
+        Stdlib parity for the "no result set" case:
+        ``sqlite3.Cursor.fetchmany()`` after a DML (no result set
+        active) returns ``[]`` rather than raising, matching the
+        ``fetchone`` parity already in place. Cross-driver code that
+        polls ``cur.fetchmany(N) or default`` after a connect-and-
+        cursor sequence works on stdlib and dqlite.
+
+        **``size=0`` divergence (cross-driver matrix)**: dqlite
+        returns ``[]`` deterministically. This differs from stdlib
+        ``sqlite3`` (which has historically drained the result set on
+        some Python/sqlite versions and returned ``[]`` on others —
+        the behaviour is version-dependent and was never a reliable
+        parity guarantee) and from psycopg3 (which treats ``0`` as
+        the sentinel "use ``self.arraysize``", since its default IS
+        ``size: int = 0``, not ``None``). Cross-driver code should
+        pass an explicit positive size, use ``None`` / omit the
+        argument to default to ``self.arraysize``, or rely on
+        ``fetchall()`` to drain. Code ported from psycopg that calls
         ``cur.fetchmany(0)`` thinking it requests "default batch"
-        gets an empty list under dqlite. Pass ``None`` or omit
-        ``size`` to default to ``self.arraysize``.
+        gets an empty list under dqlite.
         """
         del self.messages[:]
         # See ``execute``'s prelude comment for the ordering rationale.

tests/test_fetchmany_zero_docstring_stdlib_divergence.py

@@ -0,0 +1,60 @@
+"""Doc-pin: ``Cursor.fetchmany`` / ``AsyncCursor.fetchmany`` docstrings
+do NOT claim "stdlib sqlite3 parity" for the ``size=0`` corner case.
+
+The prior docstring asserted "stdlib sqlite3 parity" for the
+``size=0`` corner; that claim has shifted across CPython releases
+(older Python releases drained the result set on ``fetchmany(0)``,
+recent releases return ``[]``) and was never a guarantee dqlite
+could meaningfully make. The replacement wording drops the
+parity claim and explicitly documents the three-driver matrix —
+stdlib behaviour varies / psycopg3 treats ``0`` as "use arraysize"
+/ dqlite returns ``[]`` deterministically.
+
+A doc-pin is sufficient because there is no behaviour change — this
+issue is documentation-only. The behaviour pin lives at
+``test_fetchmany_edges.py``; here we only assert that the docstring
+does not perpetuate the false-parity claim and explicitly flags the
+divergence.
+"""
+
+from __future__ import annotations
+
+import dqlitedbapi
+import dqlitedbapi.aio
+
+
+def test_sync_fetchmany_docstring_drops_stdlib_parity_claim() -> None:
+    doc = (dqlitedbapi.Cursor.fetchmany.__doc__ or "").lower()
+    assert "size=0" in doc or "size == 0" in doc, (
+        "fetchmany docstring should document the size=0 corner case "
+        "explicitly so the divergence callout has a referent."
+    )
+    # The old wording said "stdlib sqlite3 parity" for size=0 which is
+    # factually false / version-dependent. The new wording must
+    # explicitly flag the divergence.
+    assert "differs from stdlib" in doc or "diverges from stdlib" in doc, (
+        "fetchmany docstring must explicitly flag the stdlib divergence "
+        "for size=0 — stdlib's behaviour is version-dependent and was "
+        "never a reliable parity claim."
+    )
+    # Defensive: the literal "stdlib sqlite3 parity" substring (with
+    # the conjoined wording) should no longer appear.
+    assert "stdlib sqlite3 parity" not in doc, (
+        "fetchmany docstring still contains the 'stdlib sqlite3 parity' "
+        "phrase that this fix was supposed to remove."
+    )
+
+
+def test_async_fetchmany_docstring_drops_stdlib_parity_claim() -> None:
+    doc = (dqlitedbapi.aio.AsyncCursor.fetchmany.__doc__ or "").lower()
+    assert "size=0" in doc or "size == 0" in doc, (
+        "AsyncCursor.fetchmany docstring should document the size=0 corner case."
+    )
+    assert "differs from stdlib" in doc or "diverges from stdlib" in doc, (
+        "AsyncCursor.fetchmany docstring must explicitly flag the stdlib "
+        "divergence for size=0 (mirrors the sync sibling)."
+    )
+    assert "stdlib sqlite3 parity" not in doc, (
+        "AsyncCursor.fetchmany docstring still contains the 'stdlib sqlite3 "
+        "parity' phrase that this fix was supposed to remove."
+    )