docs: adjust cancel_safe() docstring

diff --git a/psycopg/psycopg/connection.py b/psycopg/psycopg/connection.py
index 12c06993abea001279d29e86407bad6df170081a..a4680d33ddaddeaff122615eb823ab30019d9ed2 100644 (file)
--- a/psycopg/psycopg/connection.py
+++ b/psycopg/psycopg/connection.py
@@ -265,15 +265,18 @@ class Connection(BaseConnection[Row]):
     def cancel_safe(self, *, timeout: float = 30.0) -> None:
         """Cancel the current operation on the connection.
 
+        :param timeout: raise a `~errors.CancellationTimeout` if the
+            cancellation request does not succeed within `timeout` seconds.
+
+        Note that a successful cancel attempt on the client is not a guarantee
+        that the server will successfully manage to cancel the operation.
+
         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.
 
         If the underlying libpq is older than version 17, the method will fall
         back to using the same implementation of `!cancel()`.
-
-        :raises ~psycopg.errors.CancellationTimeout: If the cancellation did
-            not terminate within specified timeout.
         """
         if not self._should_cancel():
             return

diff --git a/psycopg/psycopg/connection_async.py b/psycopg/psycopg/connection_async.py
index 096213a1b96af7b21ba2144d73f80ef83d392d99..f718cbe3ed0020aee1d682d9e6a5b7b463ef34a3 100644 (file)
--- a/psycopg/psycopg/connection_async.py
+++ b/psycopg/psycopg/connection_async.py
@@ -282,15 +282,18 @@ class AsyncConnection(BaseConnection[Row]):
     async def cancel_safe(self, *, timeout: float = 30.0) -> None:
         """Cancel the current operation on the connection.
 
+        :param timeout: raise a `~errors.CancellationTimeout` if the
+            cancellation request does not succeed within `timeout` seconds.
+
+        Note that a successful cancel attempt on the client is not a guarantee
+        that the server will successfully manage to cancel the operation.
+
         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.
 
         If the underlying libpq is older than version 17, the method will fall
         back to using the same implementation of `!cancel()`.
-
-        :raises ~psycopg.errors.CancellationTimeout: If the cancellation did
-            not terminate within specified timeout.
         """
         if not self._should_cancel():
             return