From d94ac4333ff87e8a1b28ae3b10b1ef0c6de9cfb0 Mon Sep 17 00:00:00 2001 From: Peter Hinch Date: Sat, 11 Apr 2020 15:52:01 +0100 Subject: [PATCH] docs/library/uasyncio.rst: Detail exception behaviour in cancel/timeout. --- docs/library/uasyncio.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/library/uasyncio.rst b/docs/library/uasyncio.rst index 11b9c6aee4..1fc8b53db0 100644 --- a/docs/library/uasyncio.rst +++ b/docs/library/uasyncio.rst @@ -68,11 +68,13 @@ Additional functions .. function:: wait_for(awaitable, timeout) Wait for the *awaitable* to complete, but cancel it if it takes longer - that *timeout* seconds. If *awaitable* is not a task then a task will be + than *timeout* seconds. If *awaitable* is not a task then a task will be created from it. If a timeout occurs, it cancels the task and raises ``asyncio.TimeoutError``: - this should be trapped by the caller. + this should be trapped by the caller. The task receives + ``asyncio.CancelledError`` which may be ignored or trapped using ``try...except`` + or ``try...finally`` to run cleanup code. Returns the return value of *awaitable*. @@ -106,8 +108,9 @@ class Task .. method:: Task.cancel() - Cancel the task by injecting a ``CancelledError`` into it. The task may - or may not ignore this exception. + Cancel the task by injecting ``asyncio.CancelledError`` into it. The task may + ignore this exception. Cleanup code may be run by trapping it, or via + ``try ... finally``. class Event -----------