docs: add hint about using add_signal_handler() to interrupt async queries

Courtesy @gjcarneiro, thank you!

diff --git a/docs/advanced/async.rst b/docs/advanced/async.rst
index a89273d6ef7f7be5847ce95e4cca66ab43051667..1a8719f72c9dd6c64e613d2a896f8e89bc1e9518 100644 (file)
--- a/docs/advanced/async.rst
+++ b/docs/advanced/async.rst
@@ -106,6 +106,36 @@ Note that the `AsyncConnection.cursor()` function is not an `!async` function
 you can use the normal `async with` context manager.
 
 
+.. index:: Ctrl-C
+
+.. _async-ctrl-c:
+
+Interrupting async operations using Ctrl-C
+------------------------------------------
+
+If a long running operation is interrupted by a Ctrl-C on a normal connection
+running in the main thread, the operation will be cancelled and the connection
+will be put in error state, from which can be recovered with a normal
+`~Connection.rollback()`.
+
+If the query is running in an async connection, a Ctrl-C will be likely
+intercepted by the async loop and interrupt the whole program. In order to
+emulate what normally happens with blocking connections, you can use
+`asyncio's add_signal_handler()`__, to call `Connection.cancel()`:
+
+.. code:: python
+
+    import asyncio
+    import signal
+
+    async with await psycopg.AsyncConnection.connect() as conn:
+        loop.add_signal_handler(signal.SIGINT, conn.cancel)
+        ...
+
+
+.. __: https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.add_signal_handler
+
+
 .. index::
     pair: Asynchronous; Notifications
     pair: LISTEN; SQL command

diff --git a/docs/news.rst b/docs/news.rst
index 3f2aa4eb6e2c5b6896bc5f92e390bd45af790496..a1ceb95798325caf6ee89d255125741860ede44a 100644 (file)
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -39,7 +39,7 @@ Psycopg 3.0.10
 ^^^^^^^^^^^^^^
 
 - Leave the connection in working state after interrupting a query with Ctrl-C
-  (currently only for sync connections, :ticket:`#231`).
+  (:ticket:`#231`).
 - Fix `Cursor.description` after a COPY ... TO STDOUT operation
   (:ticket:`#235`).
 - Fix building on FreeBSD and likely other BSD flavours (:ticket:`#241`).