Document hasattr-vs-stdlib divergence on PEP 249 optional-extension stubs

PEP 249 §7 + the cross-driver ``except dbapi.Error:``
discipline justifies exposing ``tpc_*``, ``callproc``,
``nextset``, ``scroll``, etc. as always-raising stubs (the
NotSupportedError surface stays inside the dbapi.Error
hierarchy instead of leaking AttributeError). The
trade-off: ``hasattr(conn, "tpc_begin")`` returns True
against this driver, while stdlib ``sqlite3`` omits the
methods entirely so ``hasattr`` returns False there. Code
that feature-detects via ``hasattr`` mistakenly takes the
"supported" branch on this driver and surfaces
``NotSupportedError`` from inside the call.

Document the trap at the top of the stub block in
``connection.py`` and on ``Cursor.callproc`` (the
canonical cross-driver feature-detection target). Add a
test pinning both halves of the contract — the stub is
present (``hasattr=True``, callable) AND raises
``NotSupportedError`` — so a future "harmonise hasattr
with stdlib" change has to flip the test deliberately.

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

Author: antoineleclair

src/dqlitedbapi/connection.py

@@ -1354,6 +1354,18 @@ def closed(self) -> bool:
     # via NotSupportedError so cross-driver code that calls them
     # inside ``except sqlite3.Error:`` catches uniformly. dqlite-
     # server does not implement any of these.
+    #
+    # **Note for cross-driver code porting from stdlib ``sqlite3``:**
+    # ``hasattr(conn, "tpc_begin")`` returns ``True`` on this driver
+    # because the stub IS defined (it just unconditionally raises).
+    # Stdlib ``sqlite3`` has no ``tpc_*`` methods at all, so
+    # ``hasattr`` returns ``False`` there. Code that feature-detects
+    # via ``hasattr`` will mistakenly take the "supported" branch
+    # against dqlitedbapi and then surface ``NotSupportedError``
+    # from inside the call. To portably test for support, use a
+    # ``try: conn.tpc_begin(xid); except dbapi.NotSupportedError:``
+    # block instead of ``hasattr``. The same caveat applies to
+    # ``callproc`` / ``nextset`` / ``scroll`` on the cursor side.
 
     def tpc_begin(self, xid: object) -> NoReturn:
         raise NotSupportedError("dqlite does not support two-phase commit")

src/dqlitedbapi/cursor.py

@@ -1326,6 +1326,14 @@ def callproc(self, procname: str, parameters: Sequence[Any] | None = None) -> No
         dqlite (and SQLite) have no stored-procedure concept. Annotated
         ``NoReturn`` because the body unconditionally raises
         ``NotSupportedError`` — symmetric with ``nextset`` below.
+
+        **Note for cross-driver code porting from stdlib ``sqlite3``:**
+        ``hasattr(cur, "callproc")`` returns ``True`` here because the
+        method is defined (it just unconditionally raises). Stdlib
+        ``sqlite3.Cursor`` has no ``callproc`` / ``nextset`` / ``scroll``
+        attributes, so ``hasattr`` returns ``False`` there. Use
+        ``try / except NotSupportedError`` for portable feature-
+        detection; ``hasattr`` is misleading on this driver.
         """
         # PEP 249 §6.1.1 names ``callproc`` among the cursor methods
         # that clear ``Connection.messages`` / ``Cursor.messages``.

tests/test_pep249_stub_hasattr_divergence.py

@@ -0,0 +1,85 @@
+"""Pin: PEP 249 optional-extension stubs are exposed as
+always-raising methods (PEP 249 §7 + cross-driver
+``except dbapi.Error:`` discipline). This means ``hasattr``
+returns True against this driver, diverging from stdlib
+``sqlite3`` (which omits ``tpc_*`` / ``callproc`` / ``nextset``
+/ ``scroll`` entirely).
+
+The divergence is documented in the relevant module / method
+docstrings. Cross-driver code porting from stdlib must use
+``try/except NotSupportedError`` for feature detection,
+not ``hasattr``. This test pins the documented contract so a
+future "harmonise hasattr with stdlib" change has to flip the
+test deliberately.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from dqlitedbapi.connection import Connection
+from dqlitedbapi.exceptions import NotSupportedError
+
+
+@pytest.fixture
+def conn() -> Connection:
+    return Connection("localhost:9001", timeout=1.0)
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        "tpc_begin",
+        "tpc_prepare",
+        "tpc_commit",
+        "tpc_rollback",
+        "tpc_recover",
+        "xid",
+        "enable_load_extension",
+        "load_extension",
+        "backup",
+        "iterdump",
+        "create_function",
+        "create_aggregate",
+        "create_collation",
+        "create_window_function",
+    ],
+)
+def test_connection_stub_methods_present_for_pep249_compliance(conn: Connection, name: str) -> None:
+    """``hasattr`` returns True — the stub is present so
+    ``except dbapi.Error:`` catches the rejection uniformly.
+    Stdlib ``sqlite3`` omits these (so ``hasattr`` is False
+    there). Documented divergence."""
+    assert hasattr(conn, name)
+    method = getattr(conn, name)
+    assert callable(method)
+
+
+def test_connection_tpc_methods_raise_not_supported(conn: Connection) -> None:
+    """Stubs raise ``NotSupportedError`` (a ``dbapi.Error``
+    subclass) so cross-driver ``except dbapi.Error:`` catches.
+    The ``hasattr`` trap is the cost; the catch-uniformity is
+    the benefit. Pin both halves."""
+    with pytest.raises(NotSupportedError, match="two-phase commit"):
+        conn.tpc_begin(object())
+
+
+def test_cursor_callproc_nextset_scroll_present_but_raise() -> None:
+    """Cursor stubs match the connection-side discipline:
+    present + raise NotSupportedError. ``hasattr`` is True;
+    the ``try/except`` portable path produces the right answer."""
+    conn = Connection("localhost:9001", timeout=1.0)
+    cur = conn.cursor()
+    try:
+        for name in ("callproc", "nextset", "scroll"):
+            assert hasattr(cur, name)
+
+        with pytest.raises(NotSupportedError, match="stored procedures"):
+            cur.callproc("foo")
+        with pytest.raises(NotSupportedError, match="multiple result sets"):
+            cur.nextset()
+        with pytest.raises(NotSupportedError, match="not scrollable"):
+            cur.scroll(0)
+    finally:
+        cur.close()
+        conn._closed = True