Fix docs after AsyncConnection.cursor() made non-async

diff --git a/docs/async.rst b/docs/async.rst
index fbc851c7a8a7befb0349db68b05bd506b190a5bf..f715181090c1350efb66b63cb872d81b50a38780 100644 (file)
--- a/docs/async.rst
+++ b/docs/async.rst
@@ -18,7 +18,7 @@ here and there.
 
     async with await psycopg3.AsyncConnection.connect(
             "dbname=test user=postgres") as aconn:
-        async with await aconn.cursor() as acur:
+        async with aconn.cursor() as acur:
             await acur.execute(
                 "INSERT INTO test (num, data) VALUES (%s, %s)",
                 (100, "abc'def"))
@@ -33,8 +33,8 @@ here and there.
 
 .. _async-with:
 
-``with`` async connections and cursors
---------------------------------------
+``with`` async connections
+--------------------------
 
 As seen in :ref:`the basic usage <usage>`, connections and cursors can act as
 context managers, so you can run:
@@ -47,7 +47,7 @@ context managers, so you can run:
         # the cursor is closed upon leaving the context
     # the transaction is committed, the connection closed
 
-For asynchronous connections and cursor it's *almost* what you'd expect, but
+For asynchronous connections it's *almost* what you'd expect, but
 not quite. Please note that `~Connection.connect()` and `~Connection.cursor()`
 *don't return a context*: they are both factory methods which return *an
 object which can be used as a context*. That's because there are several use
@@ -61,8 +61,7 @@ two steps instead, as in
 
     aconn = await psycopg3.AsyncConnection.connect():
     async with aconn:
-        cur = await aconn.cursor()
-        async with cur:
+        async with aconn.cursor() as cur:
             await cur.execute(...)
 
 which can be condensed as:
@@ -70,11 +69,15 @@ which can be condensed as:
 .. code:: python
 
     async with await psycopg3.AsyncConnection.connect() as aconn:
-        async with await aconn.cursor() as cur:
+        async with aconn.cursor() as cur:
             await cur.execute(...)
 
 ...but no less than that: you still need to do the double async thing.
 
+The `AsyncConnection.cursor()` function is not marked as `!async` (it never
+performs I/O), so you don't need an `!await` on it and you can use the normal
+`async with` context manager.
+
 
 
 .. index::

diff --git a/docs/connection.rst b/docs/connection.rst
index 567461cf638b638ae798ce8a8d5fc596d3fa81ef..c648dcf5e4e3439ad42bdce2a453b32f5195afd4 100644 (file)
--- a/docs/connection.rst
+++ b/docs/connection.rst
@@ -196,9 +196,8 @@ The `!AsyncConnection` class
 
     .. automethod:: cursor
 
-        .. note:: You can use ``async with`` to close the cursor
-            automatically when the block is exited, but be careful about
-            the async quirkness: see :ref:`async-with` for details.
+        .. note:: You can use ``async with conn.cursor() as cur: ...`` to
+            close the cursor automatically when the block is exited.
 
     .. automethod:: execute(query, params=None, prepare=None) -> AsyncCursor
     .. automethod:: commit

diff --git a/docs/cursor.rst b/docs/cursor.rst
index 1b7f7a012a53f4769d988ba333a01f747cf14302..2366421cefcae8cc6b0c2a7d8a3afedc1f59ae59 100644 (file)
--- a/docs/cursor.rst
+++ b/docs/cursor.rst
@@ -176,9 +176,8 @@ The `!AsyncCursor` class
 
     .. automethod:: close
 
-        .. note:: you can use ``async with`` to close the cursor
-            automatically when the block is exited, but be careful about
-            the async quirkness: see :ref:`async-with` for details.
+        .. note:: You can use ``async with conn.cursor(): ...`` to close the
+            cursor automatically when the block is exited.
 
     .. automethod:: execute(query, params=None, prepare=None) -> AsyncCursor
     .. automethod:: executemany(query: Query, params_seq: Sequence[Args])