docs: improve cancel_safe documentation

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index 71f10dbc9e2901d5084e3fe0678e27859358fee0..1aaeac082da04f6a1dc09a57c358016aab14c396 100644 (file)
--- 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 f7e90d92af89ed302be694e581fd3bc8dc8c5e5a..80e2b66da26a9ded388885797d63f594e28cd313 100644 (file)
--- 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 ab370db13981c312be0ef48a28d5914ec88dff8e..61444a31cd46f2608ba1052e24b1cf0e7353fc21 100644 (file)
--- 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: