Stop cursor methods from over-clearing Connection.messages per PEP 249

PEP 249 §6.1.1 says ``Connection.messages`` is cleared by *connection*
methods (cursor() / commit() / rollback() / close()); §6.1.2 says
``Cursor.messages`` is cleared by *cursor* methods. The two surfaces
are independent. Every secondary cursor method (``fetchone`` /
``fetchmany`` / ``fetchall`` / ``setinputsizes`` / ``setoutputsize``
/ ``callproc`` / ``nextset`` / ``scroll``) on both the sync ``Cursor``
and async ``AsyncCursor`` was clearing ``Connection.messages`` in
addition to its own ``Cursor.messages`` — defeating the
independent-surface contract. A sibling-cursor or direct-connection
inspection of ``connection.messages`` after a cursor call always saw
``[]`` regardless of the connection's actual diagnostic state.

Remove the 15 over-clear blocks (9 sync, 6 async) and the misciting
"PEP 249 §6.1.1 — Connection.messages is cleared by the cursor fetch
methods" comments that misread the spec. Update the existing tests
that pinned the wrong behaviour to pin the corrected independence
contract instead. Add a dedicated independence pin module covering
the full surface (fetch* / setinputsizes / setoutputsize / callproc
/ nextset / scroll, plus the existing §6.1.2 ``Cursor.messages``
clear-on-cursor-methods contract).

Behaviour is invisible today (both lists are populated nowhere — see
cycle-28-dropped/MS1) but the cross-surface read contract is fixed
for any future code path that begins populating either list, and the
comments now accurately cite the spec.

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

Author: antoineleclair

src/dqlitedbapi/aio/cursor.py

@@ -473,11 +473,6 @@ async def fetchone(self) -> tuple[Any, ...] | None:
         # already adopted.
         self._connection._check_loop_binding()
         self._check_result_set()
-        # PEP 249 §6.1.1 — Connection.messages is cleared by the
-        # cursor fetch methods. Defensive against test mocks.
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
 
         if self._row_index >= len(self._rows):
             return None
@@ -497,11 +492,6 @@ async def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
         # Loop-binding check; see ``fetchone`` rationale.
         self._connection._check_loop_binding()
         self._check_result_set()
-        # PEP 249 §6.1.1 — Connection.messages is cleared by the
-        # cursor fetch methods. Defensive against test mocks.
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
 
         if size is None:
             size = self._arraysize
@@ -542,11 +532,6 @@ async def fetchall(self) -> list[tuple[Any, ...]]:
         # Loop-binding check; see ``fetchone`` rationale.
         self._connection._check_loop_binding()
         self._check_result_set()
-        # PEP 249 §6.1.1 — Connection.messages is cleared by the
-        # cursor fetch methods. Defensive against test mocks.
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
 
         result = self._rows[self._row_index :]
         self._row_index = len(self._rows)
@@ -596,9 +581,6 @@ def setinputsizes(self, sizes: Sequence[Any]) -> None:
         # PEP 249 §6.1.1 — clear "prior to executing the call" so the
         # contract holds even on the cross-loop rejection path.
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         # PEP 249 §6.2 says implementations are "free to have this
         # method do nothing" — including on closed cursors. Skip
         # the closed-cursor check.
@@ -614,9 +596,6 @@ def setinputsizes(self, sizes: Sequence[Any]) -> None:
     def setoutputsize(self, size: int, column: int | None = None) -> None:
         """Set output size (no-op for dqlite). See ``setinputsizes``."""
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         # PEP 249 §6.2 — see ``setinputsizes`` rationale.
         self._connection._check_loop_binding()
 
@@ -635,9 +614,6 @@ def callproc(self, procname: str, parameters: Sequence[Any] | None = None) -> No
         # Clear before any guard so the contract holds even on the
         # closed-cursor / cross-loop / not-supported paths.
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         # PEP 249 §6.1.2 — closed-cursor ops raise.
         self._check_closed()
         # Loop-binding check: parallel to the sync side's
@@ -653,9 +629,6 @@ def nextset(self) -> NoReturn:
         """PEP 249 optional extension — not supported."""
         # PEP 249 §6.1.1 — clear before any guard.
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         # PEP 249 §6.1.2 — closed-cursor ops raise.
         self._check_closed()
         # Loop-binding check; see ``callproc`` for rationale. Use
@@ -675,9 +648,6 @@ def scroll(self, value: int, mode: str = "relative") -> NoReturn:
         # ``messages`` cannot leave stale entries visible after the
         # caller observed the rejection. Clear before any guard.
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         # PEP 249 §6.1.2 — closed-cursor ops raise.
         self._check_closed()
         # Loop-binding check; see ``callproc`` for rationale. Use
@@ -705,9 +675,6 @@ def executescript(self, sql_script: str) -> NoReturn:
         diagnostic-leak prevention this stub family was added for.
         """
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         self._check_closed()
         self._connection._check_loop_binding()
         raise NotSupportedError(

src/dqlitedbapi/cursor.py

@@ -1202,14 +1202,6 @@ def fetchone(self) -> tuple[Any, ...] | None:
         self._connection._check_thread()
         self._check_closed()
         self._check_result_set()
-        # PEP 249 §6.1.1 — ``Connection.messages`` is cleared by the
-        # cursor fetch methods. Done after the closed-check so a
-        # closed cursor's fetch raises ``InterfaceError`` without
-        # first perturbing the connection's diagnostic list. Defensive
-        # against test mocks that pre-date the PEP 249 messages surface.
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
 
         if self._row_index >= len(self._rows):
             return None
@@ -1228,12 +1220,6 @@ def fetchmany(self, size: int | None = None) -> list[tuple[Any, ...]]:
         self._connection._check_thread()
         self._check_closed()
         self._check_result_set()
-        # PEP 249 §6.1.1 — clear Connection.messages too. Defensive
-        # against test mocks that pre-date the PEP 249 messages
-        # surface.
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
 
         if size is None:
             size = self._arraysize
@@ -1271,12 +1257,6 @@ def fetchall(self) -> list[tuple[Any, ...]]:
         self._connection._check_thread()
         self._check_closed()
         self._check_result_set()
-        # PEP 249 §6.1.1 — clear Connection.messages too. Defensive
-        # against test mocks that pre-date the PEP 249 messages
-        # surface.
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
 
         result = self._rows[self._row_index :]
         self._row_index = len(self._rows)
@@ -1359,9 +1339,6 @@ def setinputsizes(self, sizes: Sequence[Any]) -> None:
         # ``_check_thread`` for the same reason; this method and its
         # four secondary-method siblings keep the same ordering.
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         self._connection._check_thread()
         # PEP 249 §6.2 says implementations are "free to have this
         # method do nothing" — including on closed cursors. Skip the
@@ -1371,9 +1348,6 @@ def setinputsizes(self, sizes: Sequence[Any]) -> None:
     def setoutputsize(self, size: int, column: int | None = None) -> None:
         """Set output size (no-op for dqlite). See ``setinputsizes``."""
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         self._connection._check_thread()
         # PEP 249 §6.2 — see ``setinputsizes`` rationale.
 
@@ -1397,9 +1371,6 @@ def callproc(self, procname: str, parameters: Sequence[Any] | None = None) -> No
         # Clear before any guard so the contract holds even on the
         # cross-thread-rejection path. Mirrors ``nextset`` below.
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         self._connection._check_thread()
         # PEP 249 §6.1.2 — closed-cursor ops raise. Order: check
         # closed-state before raising NotSupported so the diagnostic
@@ -1417,9 +1388,6 @@ def nextset(self) -> NoReturn:
         # so the contract holds even on the cross-thread-rejection
         # path.
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         self._connection._check_thread()
         # PEP 249 §6.1.2 — closed-cursor operations raise.
         self._check_closed()
@@ -1438,9 +1406,6 @@ def scroll(self, value: int, mode: str = "relative") -> NoReturn:
         # future code that starts populating ``messages``. Order
         # matches the secondary-method family: clear before any guard.
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         self._connection._check_thread()
         self._check_closed()
         # PEP 249 §6.1.1 enumerates ``mode`` ∈ {"relative", "absolute"}.
@@ -1460,9 +1425,6 @@ def executescript(self, sql_script: str) -> NoReturn:
         as ``AttributeError``. Same shape as the
         ``Connection.executescript`` stub."""
         del self.messages[:]
-        conn_messages = getattr(self._connection, "messages", None)
-        if conn_messages is not None:
-            del conn_messages[:]
         self._connection._check_thread()
         self._check_closed()
         raise NotSupportedError(

tests/test_async_secondary_methods_clear_messages_before_guards.py

@@ -46,9 +46,10 @@ def _expect_messages_cleared_after_closed_call(invoke: Callable[[Any], None], cu
     with pytest.raises(InterfaceError, match="closed"):
         invoke(cur)
     assert list(cur.messages) == [], "Cursor.messages must be cleared before _check_closed raises"
-    assert list(cur._connection.messages) == [], (
-        "Connection.messages must be cleared before _check_closed raises"
-    )
+    # PEP 249 §6.1.1 / §6.1.2 — Connection.messages and Cursor.messages
+    # are independent surfaces. Cursor methods must NOT clear
+    # Connection.messages.
+    assert list(cur._connection.messages) == [(Warning, "stale-conn")]
 
 
 def _drive_other_loop(invoke_async: Callable[[], Any]) -> list[BaseException]:
@@ -83,7 +84,9 @@ async def test_setinputsizes_closed_cursor_clears_messages_first() -> None:
     cur._closed = True
     cur.setinputsizes([None])
     assert list(cur.messages) == []
-    assert list(cur._connection.messages) == []
+    # Connection.messages is the connection's surface; cursor methods
+    # must not clear it (PEP 249 §6.1.1 / §6.1.2 independent surfaces).
+    assert list(cur._connection.messages) == [(Warning, "stale-conn")]
 
 
 @pytest.mark.asyncio
@@ -95,7 +98,9 @@ async def test_setoutputsize_closed_cursor_clears_messages_first() -> None:
     cur._closed = True
     cur.setoutputsize(64)
     assert list(cur.messages) == []
-    assert list(cur._connection.messages) == []
+    # Connection.messages is the connection's surface; cursor methods
+    # must not clear it (PEP 249 §6.1.1 / §6.1.2 independent surfaces).
+    assert list(cur._connection.messages) == [(Warning, "stale-conn")]
 
 
 @pytest.mark.asyncio
@@ -137,4 +142,6 @@ async def test_callproc_cross_loop_clears_messages_first() -> None:
         f"expected ProgrammingError from cross-loop call; got {errors!r}"
     )
     assert list(cur.messages) == []
-    assert list(cur._connection.messages) == []
+    # Connection.messages is the connection's surface; cursor methods
+    # must not clear it (PEP 249 §6.1.1 / §6.1.2 independent surfaces).
+    assert list(cur._connection.messages) == [(Warning, "stale-conn")]

tests/test_callproc_scroll_clear_messages.py

@@ -29,16 +29,20 @@ def test_sync_callproc_clears_messages(cursor) -> None:
     cur, conn = cursor
     with pytest.raises(NotSupportedError):
         cur.callproc("p")
-    assert list(conn.messages) == []
+    # PEP 249 §6.1.1 / §6.1.2 — Connection.messages and Cursor.messages
+    # are independent surfaces. Cursor methods clear only Cursor.messages.
     assert list(cur.messages) == []
+    assert list(conn.messages) == [(Warning, "stale")]
 
 
 def test_sync_scroll_clears_messages(cursor) -> None:
     cur, conn = cursor
     with pytest.raises(NotSupportedError):
         cur.scroll(1)
-    assert list(conn.messages) == []
+    # PEP 249 §6.1.1 / §6.1.2 — Connection.messages and Cursor.messages
+    # are independent surfaces. Cursor methods clear only Cursor.messages.
     assert list(cur.messages) == []
+    assert list(conn.messages) == [(Warning, "stale")]
 
 
 @pytest.mark.asyncio
@@ -54,8 +58,10 @@ async def test_async_callproc_clears_messages() -> None:
     cur.messages.append((Warning, "stale"))
     with pytest.raises(NotSupportedError):
         cur.callproc("p")
-    assert list(conn.messages) == []
+    # PEP 249 §6.1.1 / §6.1.2 — Connection.messages and Cursor.messages
+    # are independent surfaces. Cursor methods clear only Cursor.messages.
     assert list(cur.messages) == []
+    assert list(conn.messages) == [(Warning, "stale")]
 
 
 @pytest.mark.asyncio
@@ -68,5 +74,7 @@ async def test_async_scroll_clears_messages() -> None:
     cur.messages.append((Warning, "stale"))
     with pytest.raises(NotSupportedError):
         cur.scroll(1)
-    assert list(conn.messages) == []
+    # PEP 249 §6.1.1 / §6.1.2 — Connection.messages and Cursor.messages
+    # are independent surfaces. Cursor methods clear only Cursor.messages.
     assert list(cur.messages) == []
+    assert list(conn.messages) == [(Warning, "stale")]

tests/test_connection_messages_cleared_by_cursor_methods.py

@@ -1,5 +1,16 @@
-"""PEP 249 §6.1.1 — Connection.messages is cleared by the cursor
-fetch methods (fetchone, fetchmany, fetchall) and by nextset.
+"""Pin: cursor methods do NOT clear ``Connection.messages``. PEP 249
+§6.1.1 says ``Connection.messages`` is cleared by *connection*
+methods (cursor() / commit() / rollback() / close()); §6.1.2 says
+``Cursor.messages`` is cleared by *cursor* methods. The two surfaces
+are independent.
+
+Previously cursor methods over-cleared ``Connection.messages`` from
+inside ``fetchone`` / ``fetchmany`` / ``fetchall`` / ``nextset`` /
+``setinputsizes`` / ``setoutputsize`` / ``callproc`` / ``scroll``.
+That violated PEP 249's independent-surface contract — a sibling-
+cursor / direct-connection inspection of ``connection.messages``
+after a cursor call always saw ``[]``. Pin the corrected behaviour:
+cursor methods leave ``Connection.messages`` untouched.
 """
 
 from __future__ import annotations
@@ -23,28 +34,32 @@ def _make_cursor() -> Cursor:
     return cur
 
 
-class TestConnectionMessagesCleared:
-    def test_fetchone_clears_connection_messages(self) -> None:
+class TestConnectionMessagesNotClearedByCursorMethods:
+    def test_fetchone_does_not_clear_connection_messages(self) -> None:
         cur = _make_cursor()
-        cur._connection.messages.append((RuntimeError, "stale"))
+        seed = (RuntimeError, "session-level diagnostic")
+        cur._connection.messages.append(seed)
         cur.fetchone()
-        assert cur._connection.messages == []
+        assert cur._connection.messages == [seed]
 
-    def test_fetchmany_clears_connection_messages(self) -> None:
+    def test_fetchmany_does_not_clear_connection_messages(self) -> None:
         cur = _make_cursor()
-        cur._connection.messages.append((RuntimeError, "stale"))
+        seed = (RuntimeError, "session-level diagnostic")
+        cur._connection.messages.append(seed)
         cur.fetchmany(1)
-        assert cur._connection.messages == []
+        assert cur._connection.messages == [seed]
 
-    def test_fetchall_clears_connection_messages(self) -> None:
+    def test_fetchall_does_not_clear_connection_messages(self) -> None:
         cur = _make_cursor()
-        cur._connection.messages.append((RuntimeError, "stale"))
+        seed = (RuntimeError, "session-level diagnostic")
+        cur._connection.messages.append(seed)
         cur.fetchall()
-        assert cur._connection.messages == []
+        assert cur._connection.messages == [seed]
 
-    def test_nextset_clears_connection_messages_before_raising(self) -> None:
+    def test_nextset_does_not_clear_connection_messages_before_raising(self) -> None:
         cur = _make_cursor()
-        cur._connection.messages.append((RuntimeError, "stale"))
+        seed = (RuntimeError, "session-level diagnostic")
+        cur._connection.messages.append(seed)
         with pytest.raises(NotSupportedError):
             cur.nextset()
-        assert cur._connection.messages == []
+        assert cur._connection.messages == [seed]