From 8fe00efaeb78ad31bf09407f8e98a4a82c5cb62c Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Sat, 13 Apr 2024 12:23:38 +0200 Subject: [PATCH] docs: adjust cancel_safe() docstring --- psycopg/psycopg/connection.py | 9 ++++++--- psycopg/psycopg/connection_async.py | 9 ++++++--- 2 files changed, 12 insertions(+), 6 deletions(-) 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 -- 2.47.2