[Python-checkins] bpo-33649: Fix gather() docs; fix title; few other nits. (GH-9475) (GH-9481)
Yury Selivanov
webhook-mailer at python.org
Fri Sep 21 16:35:37 EDT 2018
https://github.com/python/cpython/commit/e45662c28bfc84aa3674463a2995e45da4d63793
commit: e45662c28bfc84aa3674463a2995e45da4d63793
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Yury Selivanov <yury at magic.io>
date: 2018-09-21T16:35:34-04:00
summary:
bpo-33649: Fix gather() docs; fix title; few other nits. (GH-9475) (GH-9481)
(cherry picked from commit db1a80e97aa7217c561fb3627f70be1882de9534)
Co-authored-by: Yury Selivanov <yury at magic.io>
files:
M Doc/library/asyncio-task.rst
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 1b95592cd99e..bdb475a797db 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -129,7 +129,8 @@ other coroutines::
async def main():
# Nothing happens if we just call "nested()".
- # (a coroutine object is created but not awaited)
+ # A coroutine object is created but not awaited,
+ # so it *won't run at all*.
nested()
# Let's do it differently now and await it:
@@ -307,12 +308,15 @@ Running Tasks Concurrently
aggregate list of returned values. The order of result values
corresponds to the order of awaitables in *aws*.
+ If *return_exceptions* is ``False`` (default), the first
+ raised exception is immediately propagated to the task that
+ awaits on ``gather()``. Other awaitables in the *aws* sequence
+ **won't be cancelled** and will continue to run.
+
If *return_exceptions* is ``True``, exceptions are treated the
same as successful results, and aggregated in the result list.
- Otherwise, the first raised exception is immediately propagated
- to the task that awaits on ``gather()``.
- If ``gather`` is *cancelled*, all submitted awaitables
+ If ``gather()`` is *cancelled*, all submitted awaitables
(that have not completed yet) are also *cancelled*.
If any Task or Future from the *aws* sequence is *cancelled*, it is
@@ -362,16 +366,15 @@ Running Tasks Concurrently
propagated regardless of *return_exceptions*.
-Shielding Tasks From Cancellation
-=================================
+Shielding From Cancellation
+===========================
.. awaitablefunction:: shield(aw, \*, loop=None)
Protect an :ref:`awaitable object <asyncio-awaitables>`
from being :meth:`cancelled <Task.cancel>`.
- *aw* can be a coroutine, a Task, or a Future-like object. If
- *aw* is a coroutine it is automatically scheduled as a Task.
+ If *aw* is a coroutine it is automatically scheduled as a Task.
The statement::
@@ -603,7 +606,7 @@ Task Object
.. class:: Task(coro, \*, loop=None)
- A :class:`Future`-like object that wraps a Python
+ A :class:`Future-like <Future>` object that runs a Python
:ref:`coroutine <coroutine>`. Not thread-safe.
Tasks are used to run coroutines in event loops.
@@ -800,7 +803,7 @@ Task Object
is used to get the current loop.
This method is **deprecated** and will be removed in
- Python 3.9. Use the :func:`all_tasks` function instead.
+ Python 3.9. Use the :func:`asyncio.all_tasks` function instead.
.. classmethod:: current_task(loop=None)
@@ -810,7 +813,8 @@ Task Object
is used to get the current loop.
This method is **deprecated** and will be removed in
- Python 3.9. Use the :func:`current_task` function instead.
+ Python 3.9. Use the :func:`asyncio.current_task` function
+ instead.
.. _asyncio_generator_based_coro:
More information about the Python-checkins
mailing list