From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sat, 13 Apr 2024 10:23:38 +0000 (+0200)
Subject: docs: adjust cancel_safe() docstring
X-Git-Tag: 3.2.0~41^2~2
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8fe00efaeb78ad31bf09407f8e98a4a82c5cb62c;p=thirdparty%2Fpsycopg.git

docs: adjust cancel_safe() docstring
---

diff --git a/psycopg/psycopg/connection.py b/psycopg/psycopg/connection.py
index 12c06993a..a4680d33d 100644
--- 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 096213a1b..f718cbe3e 100644
--- 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