feat(cursor): add optional callproc/nextset/scroll methods

PEP 249 specifies these three optional cursor methods. When unsupported,
drivers must raise NotSupportedError (not AttributeError). Add stubs on
both sync and async cursors that raise with a clear message.

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

Author: antoineleclair

src/dqlitedbapi/aio/cursor.py

@@ -9,7 +9,7 @@
     _convert_row,
     _strip_leading_comments,
 )
-from dqlitedbapi.exceptions import InterfaceError, ProgrammingError
+from dqlitedbapi.exceptions import InterfaceError, NotSupportedError, ProgrammingError
 
 if TYPE_CHECKING:
     from dqlitedbapi.aio.connection import AsyncConnection
@@ -213,6 +213,20 @@ def setoutputsize(self, size: int, column: int | None = None) -> None:
         """Set output size (no-op for dqlite)."""
         pass
 
+    async def callproc(
+        self, procname: str, parameters: Sequence[Any] | None = None
+    ) -> Sequence[Any] | None:
+        """PEP 249 optional extension — not supported."""
+        raise NotSupportedError("dqlite does not support stored procedures")
+
+    def nextset(self) -> bool | None:
+        """PEP 249 optional extension — not supported."""
+        raise NotSupportedError("dqlite does not support multiple result sets")
+
+    def scroll(self, value: int, mode: str = "relative") -> None:
+        """PEP 249 optional extension — not supported."""
+        raise NotSupportedError("dqlite cursors are not scrollable")
+
     def __repr__(self) -> str:
         state = "closed" if self._closed else "open"
         return f"<AsyncCursor rowcount={self._rowcount} {state}>"

src/dqlitedbapi/cursor.py

@@ -7,6 +7,7 @@
 from dqlitedbapi.exceptions import (
     DataError,
     InterfaceError,
+    NotSupportedError,
     OperationalError,
     ProgrammingError,
 )
@@ -338,6 +339,30 @@ def setoutputsize(self, size: int, column: int | None = None) -> None:
         """Set output size (no-op for dqlite)."""
         pass
 
+    def callproc(
+        self, procname: str, parameters: Sequence[Any] | None = None
+    ) -> Sequence[Any] | None:
+        """PEP 249 optional extension — not supported.
+
+        dqlite (and SQLite) have no stored-procedure concept.
+        """
+        raise NotSupportedError("dqlite does not support stored procedures")
+
+    def nextset(self) -> bool | None:
+        """PEP 249 optional extension — not supported.
+
+        dqlite's wire protocol does not return multiple result sets.
+        """
+        raise NotSupportedError("dqlite does not support multiple result sets")
+
+    def scroll(self, value: int, mode: str = "relative") -> None:
+        """PEP 249 optional extension — not supported.
+
+        The dqlite cursor is forward-only; rows are buffered from a
+        streamed wire response.
+        """
+        raise NotSupportedError("dqlite cursors are not scrollable")
+
     def __repr__(self) -> str:
         state = "closed" if self._closed else "open"
         return f"<Cursor rowcount={self._rowcount} {state}>"

tests/test_async_cursor.py

@@ -108,3 +108,30 @@ def test_setoutputsize_noop(self) -> None:
         conn = AsyncConnection("localhost:9001")
         cursor = AsyncCursor(conn)
         cursor.setoutputsize(100, 0)
+
+
+class TestOptionalAsyncCursorMethodsRaise:
+    @pytest.mark.asyncio
+    async def test_callproc_raises_not_supported(self) -> None:
+        from dqlitedbapi.exceptions import NotSupportedError
+
+        conn = AsyncConnection("localhost:9001")
+        cursor = AsyncCursor(conn)
+        with pytest.raises(NotSupportedError):
+            await cursor.callproc("some_proc")
+
+    def test_nextset_raises_not_supported(self) -> None:
+        from dqlitedbapi.exceptions import NotSupportedError
+
+        conn = AsyncConnection("localhost:9001")
+        cursor = AsyncCursor(conn)
+        with pytest.raises(NotSupportedError):
+            cursor.nextset()
+
+    def test_scroll_raises_not_supported(self) -> None:
+        from dqlitedbapi.exceptions import NotSupportedError
+
+        conn = AsyncConnection("localhost:9001")
+        cursor = AsyncCursor(conn)
+        with pytest.raises(NotSupportedError):
+            cursor.scroll(0)

tests/test_cursor.py

@@ -99,3 +99,29 @@ def test_setoutputsize_noop(self) -> None:
         cursor = Cursor(conn)
         # Should not raise
         cursor.setoutputsize(100, 0)
+
+
+class TestOptionalCursorMethodsRaise:
+    def test_callproc_raises_not_supported(self) -> None:
+        from dqlitedbapi.exceptions import NotSupportedError
+
+        conn = Connection("localhost:9001")
+        cursor = Cursor(conn)
+        with pytest.raises(NotSupportedError):
+            cursor.callproc("some_proc")
+
+    def test_nextset_raises_not_supported(self) -> None:
+        from dqlitedbapi.exceptions import NotSupportedError
+
+        conn = Connection("localhost:9001")
+        cursor = Cursor(conn)
+        with pytest.raises(NotSupportedError):
+            cursor.nextset()
+
+    def test_scroll_raises_not_supported(self) -> None:
+        from dqlitedbapi.exceptions import NotSupportedError
+
+        conn = Connection("localhost:9001")
+        cursor = Cursor(conn)
+        with pytest.raises(NotSupportedError):
+            cursor.scroll(0)