From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Thu, 19 Nov 2020 19:29:57 +0000 (+0000)
Subject: Document async with connection and cursor
X-Git-Tag: 3.0.dev0~343
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a48932e077271563cd2df215ca156806b4f14a12;p=thirdparty%2Fpsycopg.git

Document async with connection and cursor
---

diff --git a/docs/connection.rst b/docs/connection.rst
index 84cb838b3..6d74ad49b 100644
--- 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 8f0c651e7..429dbf8d6 100644
--- 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 4b3040620..38adbc507 100644
--- 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::