From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Wed, 10 Feb 2021 13:41:32 +0000 (+0100)
Subject: Fix docs after AsyncConnection.cursor() made non-async
X-Git-Tag: 3.0.dev0~115^2~8
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=44f3090277a391b1ec28c2a4121601a2702306a4;p=thirdparty%2Fpsycopg.git

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

diff --git a/docs/async.rst b/docs/async.rst
index fbc851c7a..f71518109 100644
--- 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 567461cf6..c648dcf5e 100644
--- 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 1b7f7a012..2366421ce 100644
--- 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])