From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 8 Apr 2024 22:57:53 +0000 (+0200)
Subject: docs: improve cancel_safe documentation
X-Git-Tag: 3.2.0~54^2~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2978ed45c4028631752b443781bf7eb8358b12bb;p=thirdparty%2Fpsycopg.git

docs: improve cancel_safe documentation
---

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index 71f10dbc9..1aaeac082 100644
--- a/docs/api/connections.rst
+++ b/docs/api/connections.rst
@@ -285,9 +285,36 @@ The `!Connection` class
 
     .. rubric:: Methods you can use to do something cool
 
-    .. automethod:: cancel
     .. automethod:: cancel_safe
 
+        .. warning::
+
+            This method shouldn't be used as a `~signal.signal` handler.
+            Please use `cancel()` instead.
+
+        .. versionadded:: 3.2
+
+    .. automethod:: cancel
+
+        .. warning::
+
+            The `!cancel()` method has a few shortcomings:
+
+            - it is blocking even on async connections,
+            - it `might use an insecure connection`__ even if the original
+              connection was secure.
+
+            Therefore you should use the `cancel_safe()` method whenever
+            possible.
+
+            .. __: https://www.postgresql.org/docs/devel/libpq-cancel.html
+                   #LIBPQ-CANCEL-DEPRECATED
+
+        .. note::
+
+            Unlike `cancel_safe()`, it is safe to call this method as a
+            `~signal.signal` handler.
+
     .. automethod:: notifies
 
         Notifies are received after using :sql:`LISTEN` in a connection, when
@@ -505,6 +532,10 @@ The `!AsyncConnection` class
                 async with conn.transaction() as tx:
                     ...
 
+    .. automethod:: cancel_safe
+
+        .. versionadded:: 3.2
+
     .. automethod:: notifies
 
         .. versionchanged:: 3.2
diff --git a/psycopg/psycopg/connection.py b/psycopg/psycopg/connection.py
index f7e90d92a..80e2b66da 100644
--- a/psycopg/psycopg/connection.py
+++ b/psycopg/psycopg/connection.py
@@ -264,15 +264,12 @@ class Connection(BaseConnection[Row]):
     def cancel_safe(self) -> None:
         """Cancel the current operation on the connection.
 
-        This is a non-blocking version of `cancel()` which leverages a more
-        secure and improved cancellation feature of the libpq (available from
-        version 17).
+        This is a non-blocking version of `~Connection.cancel()` which
+        leverages a more secure and improved cancellation feature of the libpq,
+        which is only available from version 17.
 
-        In contrast with `cancel()`, it is not appropriate for use in a signal
-        handler.
-
-        If the underlying libpq is older than version 17, fall back to
-        `cancel()`.
+        If the underlying libpq is older than version 17, the method will fall
+        back to using the same implementation of `!cancel()`.
         """
         if self._should_cancel():
             try:
diff --git a/psycopg/psycopg/connection_async.py b/psycopg/psycopg/connection_async.py
index ab370db13..61444a31c 100644
--- a/psycopg/psycopg/connection_async.py
+++ b/psycopg/psycopg/connection_async.py
@@ -281,15 +281,12 @@ class AsyncConnection(BaseConnection[Row]):
     async def cancel_safe(self) -> None:
         """Cancel the current operation on the connection.
 
-        This is a non-blocking version of `cancel()` which leverages a more
-        secure and improved cancellation feature of the libpq (available from
-        version 17).
+        This is a non-blocking version of `~Connection.cancel()` which
+        leverages a more secure and improved cancellation feature of the libpq,
+        which is only available from version 17.
 
-        In contrast with `cancel()`, it is not appropriate for use in a signal
-        handler.
-
-        If the underlying libpq is older than version 17, fall back to
-        `cancel()`.
+        If the underlying libpq is older than version 17, the method will fall
+        back to using the same implementation of `!cancel()`.
         """
         if self._should_cancel():
             try: