Document async with connection and cursor

diff --git a/docs/connection.rst b/docs/connection.rst
index 84cb838b32e8ca15a10dd812eb708f50ec7aee11..6d74ad49b407aa8f212f4ab890444210286bb67f 100644 (file)
--- a/docs/connection.rst
+++ b/docs/connection.rst
@@ -49,8 +49,18 @@ The `!Connection` class
             .. __: https://www.postgresql.org/docs/current/libpq-envars.html
 
     .. automethod:: close
+
+        .. note:: you can use :ref:`with connect(): ...<with-statement>` to
+            close the connection automatically when the block is exited.
+
+    .. autoattribute:: closed
+        :annotation: bool
+
     .. automethod:: cursor
 
+        .. note:: you can use :ref:`with conn.cursor(): ...<with-statement>`
+            to close the cursor automatically when the block is exited.
+
 
     .. rubric:: Transaction management methods
 
@@ -74,9 +84,6 @@ The `!Connection` class
 
     .. rubric:: Checking and configuring the connection state
 
-    .. autoattribute:: closed
-        :annotation: bool
-
     .. autoattribute:: client_encoding
         :annotation: str
 
@@ -122,7 +129,17 @@ The `!AsyncConnection` class
 
     .. automethod:: connect
     .. automethod:: close
+
+        .. note:: you can use `!async with` to close the connection
+            automatically when the block is exited, but be careful about
+            the async quirkness: see :ref:`with-statement` for details.
+
     .. 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:`with-statement` for details.
+
     .. automethod:: commit
     .. automethod:: rollback
 

diff --git a/docs/cursor.rst b/docs/cursor.rst
index 8f0c651e7cf0f4973b92a34ddb11313b802de977..429dbf8d6e17d591d94be894aa744add7f9f5e3e 100644 (file)
--- a/docs/cursor.rst
+++ b/docs/cursor.rst
@@ -32,7 +32,12 @@ The `!Cursor` class
     terminate a transaction or a session though.
 
     .. automethod:: close
-    .. autoproperty:: closed
+
+        .. note:: you can use :ref:`with conn.cursor(): ...<with-statement>`
+            to close the cursor automatically when the block is exited.
+
+    .. autoattribute:: closed
+        :annotation: bool
 
     .. rubric:: Methods to send commands
 
@@ -99,6 +104,11 @@ The `!AsyncCursor` class
     methods, but have an `async` interface.
 
     .. 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:`with-statement` for details.
+
     .. automethod:: execute
     .. automethod:: executemany
     .. automethod:: copy

diff --git a/docs/usage.rst b/docs/usage.rst
index 4b30406201665060d24ee4725a2f03377ba55873..38adbc507042b2432ce21c67dc8e13f3afad9abd 100644 (file)
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -94,10 +94,12 @@ The main entry points of `!psycopg3` are:
 
 .. index:: with
 
+.. _with-statement:
+
 ``with`` connections and cursors
 --------------------------------
 
-The connections and cursors act as context managers, so you can run:
+Connections and cursors act as context managers, so you can run:
 
 .. code:: python
 
@@ -114,6 +116,29 @@ The connections and cursors act as context managers, so you can run:
     # the transaction is committed on successful exit of the context
     # and the connection closed
 
+For asynchronous connections and cursor it's *almost* what you'd expect, but
+not quite. Please note that `!connect()` and `!cursor()` *don't return a
+context*: they are both factory methods which return *an object which can be
+used as a context*. So you cannot use ``async with connect()``: you have to do
+it in two steps instead, as in
+
+.. code:: python
+
+    aconn = await psycopg3.AsyncConnection.connect():
+    async with aconn:
+        cur = await aconn.cursor()
+        async with as cur:
+            await cur.execute(...)
+
+which can be condensed as:
+
+.. code:: python
+
+    async with (await psycopg3.AsyncConnection.connect()) as aconn:
+        async with (await aconn.cursor()) as cur:
+            await cur.execute(...)
+
+...but no less than that: you still need to do the double async thing.
 
 
 .. index::