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 7269bd73add62f00708f57872a5171545f60eb35..db0b341a484a8f8f877ce7c560e7d34ff2471477 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 24c9cb1ae6159f10eb8b59dd20b772575b3d1917..1ed40085dc3ace1b5fe26980b07353f0a14e2aff 100644 (file)
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -54,7 +54,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`).