Wrap protocol exceptions in PEP 249 exception types

Exceptions from the dqlite protocol layer (ConnectionError, OSError,
etc.) are now wrapped in OperationalError. Our own exception types
are re-raised as-is. Also replaces assert with proper InternalError
check for protocol initialization (fixes issue 09).

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

Author: antoineleclair

src/dqlitedbapi/aio/cursor.py

@@ -3,7 +3,7 @@
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any
 
-from dqlitedbapi.exceptions import InterfaceError, InternalError
+from dqlitedbapi.exceptions import InterfaceError, InternalError, OperationalError
 
 if TYPE_CHECKING:
     from dqlitedbapi.aio.connection import AsyncConnection
@@ -88,22 +88,26 @@ async def execute(
             " RETURNING " in normalized or normalized.endswith(" RETURNING")
         )
 
-        if is_query:
-            if conn._protocol is None or conn._db_id is None:
-                raise InternalError("Connection protocol not initialized")
-            columns, rows = await conn._protocol.query_sql(conn._db_id, operation, params)
-            self._description = [(name, None, None, None, None, None, None) for name in columns]
-            self._rows = [tuple(row) for row in rows]
-            self._row_index = 0
-            self._rowcount = len(rows)
-        else:
-            if conn._protocol is None or conn._db_id is None:
-                raise InternalError("Connection protocol not initialized")
-            last_id, affected = await conn._protocol.exec_sql(conn._db_id, operation, params)
-            self._lastrowid = last_id
-            self._rowcount = affected
-            self._description = None
-            self._rows = []
+        if conn._protocol is None or conn._db_id is None:
+            raise InternalError("Connection protocol not initialized")
+
+        try:
+            if is_query:
+                columns, rows = await conn._protocol.query_sql(conn._db_id, operation, params)
+                self._description = [(name, None, None, None, None, None, None) for name in columns]
+                self._rows = [tuple(row) for row in rows]
+                self._row_index = 0
+                self._rowcount = len(rows)
+            else:
+                last_id, affected = await conn._protocol.exec_sql(conn._db_id, operation, params)
+                self._lastrowid = last_id
+                self._rowcount = affected
+                self._description = None
+                self._rows = []
+        except (OperationalError, InterfaceError, InternalError):
+            raise
+        except Exception as e:
+            raise OperationalError(str(e)) from e
 
         return self
 

src/dqlitedbapi/cursor.py

@@ -3,7 +3,7 @@
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any
 
-from dqlitedbapi.exceptions import InterfaceError, InternalError
+from dqlitedbapi.exceptions import InterfaceError, InternalError, OperationalError
 
 if TYPE_CHECKING:
     from dqlitedbapi.connection import Connection
@@ -100,22 +100,26 @@ async def _execute_async(self, operation: str, parameters: Sequence[Any] | None
             " RETURNING " in normalized or normalized.endswith(" RETURNING")
         )
 
-        if is_query:
-            if conn._protocol is None or conn._db_id is None:
-                raise InternalError("Connection protocol not initialized")
-            columns, rows = await conn._protocol.query_sql(conn._db_id, operation, params)
-            self._description = [(name, None, None, None, None, None, None) for name in columns]
-            self._rows = [tuple(row) for row in rows]
-            self._row_index = 0
-            self._rowcount = len(rows)
-        else:
-            if conn._protocol is None or conn._db_id is None:
-                raise InternalError("Connection protocol not initialized")
-            last_id, affected = await conn._protocol.exec_sql(conn._db_id, operation, params)
-            self._lastrowid = last_id
-            self._rowcount = affected
-            self._description = None
-            self._rows = []
+        if conn._protocol is None or conn._db_id is None:
+            raise InternalError("Connection protocol not initialized")
+
+        try:
+            if is_query:
+                columns, rows = await conn._protocol.query_sql(conn._db_id, operation, params)
+                self._description = [(name, None, None, None, None, None, None) for name in columns]
+                self._rows = [tuple(row) for row in rows]
+                self._row_index = 0
+                self._rowcount = len(rows)
+            else:
+                last_id, affected = await conn._protocol.exec_sql(conn._db_id, operation, params)
+                self._lastrowid = last_id
+                self._rowcount = affected
+                self._description = None
+                self._rows = []
+        except (OperationalError, InterfaceError, InternalError):
+            raise
+        except Exception as e:
+            raise OperationalError(str(e)) from e
 
     def executemany(self, operation: str, seq_of_parameters: Sequence[Sequence[Any]]) -> "Cursor":
         """Execute a database operation multiple times."""

tests/test_exception_wrapping.py

@@ -0,0 +1,64 @@
+"""Tests that protocol exceptions are wrapped in PEP 249 exception types."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from dqlitedbapi.cursor import Cursor
+from dqlitedbapi.exceptions import OperationalError
+
+
+def _make_mock_connection_with_error(error: Exception) -> MagicMock:
+    """Create a mock Connection where protocol raises the given error."""
+    mock_protocol = AsyncMock()
+    mock_protocol.exec_sql = AsyncMock(side_effect=error)
+    mock_protocol.query_sql = AsyncMock(side_effect=error)
+
+    mock_async_conn = AsyncMock()
+    mock_async_conn._protocol = mock_protocol
+    mock_async_conn._db_id = 0
+
+    mock_conn = MagicMock()
+
+    async def get_async_conn() -> AsyncMock:
+        return mock_async_conn
+
+    mock_conn._get_async_connection = get_async_conn
+
+    def run_sync(coro: object) -> object:
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(coro)
+        finally:
+            loop.close()
+
+    mock_conn._run_sync = run_sync
+
+    return mock_conn
+
+
+class TestExceptionWrapping:
+    def test_connection_error_wrapped_as_operational_error(self) -> None:
+        """ConnectionError from protocol should become OperationalError."""
+        mock_conn = _make_mock_connection_with_error(ConnectionError("connection lost"))
+        cursor = Cursor(mock_conn)
+
+        with pytest.raises(OperationalError, match="connection lost"):
+            cursor.execute("SELECT 1")
+
+    def test_os_error_wrapped_as_operational_error(self) -> None:
+        """OSError from protocol should become OperationalError."""
+        mock_conn = _make_mock_connection_with_error(OSError("network unreachable"))
+        cursor = Cursor(mock_conn)
+
+        with pytest.raises(OperationalError, match="network unreachable"):
+            cursor.execute("INSERT INTO t VALUES (1)")
+
+    def test_runtime_error_wrapped_as_operational_error(self) -> None:
+        """Generic exceptions from protocol should become OperationalError."""
+        mock_conn = _make_mock_connection_with_error(RuntimeError("unexpected"))
+        cursor = Cursor(mock_conn)
+
+        with pytest.raises(OperationalError, match="unexpected"):
+            cursor.execute("SELECT 1")