Issue #21601: Document asyncio.Task.cancel(). Initial patch written by Vajrasky

Kok.

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 67eaccd7bf6cfd2afc343b941c78989fb9d7fc50..eb254a9152f2fc3397fdac608dffa70a026ec529 100644 (file)
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -327,7 +327,27 @@ Task
 
       ``None`` is returned when called not in the context of a :class:`Task`.
 
-   .. method:: get_stack(self, \*, limit=None)
+   .. method:: cancel()
+
+      Request this task to cancel itself.
+
+      This arranges for a :exc:`~concurrent.futures.CancelledError` 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 :meth:`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, :meth:`~Future.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
+      :exc:`~concurrent.futures.CancelledError` exception (even if
+      :meth:`cancel` was not called).
+
+   .. method:: get_stack(\*, limit=None)
 
       Return the list of stack frames for this task's coroutine.
 

diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py
index 45a6342eea4eeb42fe390eff84fa4a1a694f4a3a..2aa568bc6d5b3a0ef630add42314850359cc287d 100644 (file)
--- a/Lib/asyncio/tasks.py
+++ b/Lib/asyncio/tasks.py
@@ -269,9 +269,9 @@ class Task(futures.Future):
                 print(line, file=file, end='')
 
     def cancel(self):
-        """Request that a task to cancel itself.
+        """Request this task to cancel itself.
 
-        This arranges for a CancellationError to be thrown into the
+        This arranges for a CancelledError 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.