Document per-RPC-phase timeout budget on connection and pool docstrings

The timeout parameter is applied per RPC phase (send, read, any
continuation drain), not as an end-to-end deadline. The wire layer's
_operation_deadline already documented this correctly, but the public
DqliteConnection / AsyncDqliteConnection / ConnectionPool / create_pool
docstrings just said "Connection timeout in seconds" — letting an
operator size their wait_for() expecting the inner budget to be
absolute.

Spell out the per-phase semantics and direct callers to wrap with
asyncio.timeout() for a wall-clock deadline.

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

Author: antoineleclair

src/dqliteclient/__init__.py

@@ -70,7 +70,10 @@ async def connect(
     Args:
         address: Node address in "host:port" format
         database: Database name to open
-        timeout: Connection timeout in seconds
+        timeout: Per-RPC-phase timeout in seconds (forwarded). Each
+            phase of an operation gets the full budget independently;
+            wrap with ``asyncio.timeout(...)`` to enforce an end-to-end
+            deadline.
         max_total_rows: Cumulative row cap across continuation frames
             for a single query. Forwarded to the underlying
             DqliteConnection. None disables the cap.
@@ -124,7 +127,10 @@ async def create_pool(
         database: Database name to open
         min_size: Minimum number of connections to maintain
         max_size: Maximum number of connections
-        timeout: Connection timeout in seconds
+        timeout: Per-RPC-phase timeout in seconds (forwarded). Each
+            phase of an operation gets the full budget independently;
+            wrap with ``asyncio.timeout(...)`` to enforce an end-to-end
+            deadline.
         cluster: Externally-owned ClusterClient shared across pools.
         node_store: Externally-owned NodeStore used to build a new
             ClusterClient. Mutually exclusive with ``cluster``.

src/dqliteclient/connection.py

@@ -509,7 +509,14 @@ def __init__(
         Args:
             address: Node address in "host:port" format
             database: Database name to open
-            timeout: Connection timeout in seconds
+            timeout: Per-RPC-phase timeout in seconds. The same budget
+                is applied to each phase of an operation independently
+                (send, then read, then any continuation drain), so a
+                single high-level call (e.g. a ``query_sql`` returning
+                a large continuation-paginated result) can take up to
+                roughly N × ``timeout`` end-to-end. To enforce a true
+                end-to-end deadline, wrap the call in
+                ``asyncio.timeout(...)`` or ``asyncio.wait_for(...)``.
             max_total_rows: Cumulative row cap across continuation
                 frames for a single query. Prevents a slow-drip server
                 from keeping the client alive indefinitely within the

src/dqliteclient/pool.py

@@ -140,7 +140,13 @@ def __init__(
             database: Database name
             min_size: Minimum connections to maintain
             max_size: Maximum connections allowed
-            timeout: Connection timeout
+            timeout: Per-RPC-phase timeout (forwarded to each pooled
+                ``DqliteConnection``). Each phase of an operation
+                (send, read, any continuation drain) gets the full
+                budget independently, so a single call can take up to
+                roughly N × ``timeout`` end-to-end. Wrap callers in
+                ``asyncio.timeout(...)`` to enforce a wall-clock
+                deadline.
             cluster: Externally-owned ClusterClient. Lets multiple pools
                 share one ClusterClient (and thus its node store, leader
                 cache, etc.) across databases or tenants.