From: Victor Stinner <victor.stinner@gmail.com>
Date: Mon, 7 Apr 2014 09:18:06 +0000 (+0200)
Subject: asyncio: Document Task.cancel() properly.
X-Git-Tag: v3.4.1rc1~123
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4bd652a276c575de476d634da8cc4f95815721e9;p=python

asyncio: Document Task.cancel() properly.
---

diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py
index 0967e7e628..153f731a76 100644
--- a/Lib/asyncio/tasks.py
+++ b/Lib/asyncio/tasks.py
@@ -250,6 +250,25 @@ class Task(futures.Future):
                 print(line, file=file, end='')
 
     def cancel(self):
+        """Request that a task to cancel itself.
+
+        This arranges for a CancellationError to be thrown into the
+        wrapped coroutine on the next cycle through the event loop.
+        The coroutine then has a chance to clean up or even deny
+        the request using try/except/finally.
+
+        Contrary to Future.cancel(), this does not guarantee that the
+        task will be cancelled: the exception might be caught and
+        acted upon, delaying cancellation of the task or preventing it
+        completely.  The task may also return a value or raise a
+        different exception.
+
+        Immediately after this method is called, Task.cancelled() will
+        not return True (unless the task was already cancelled).  A
+        task will be marked as cancelled when the wrapped coroutine
+        terminates with a CancelledError exception (even if cancel()
+        was not called).
+        """
         if self.done():
             return False
         if self._fut_waiter is not None: