-
-
Notifications
You must be signed in to change notification settings - Fork 33.4k
Closed as not planned
Labels
Description
Documentation
As evidenced by GH-108427, the current example for asyncio.shield() may be confusing. The example:
cpython/Doc/library/asyncio-task.rst
Lines 588 to 601 in c7d68f9
| The statement:: | |
| task = asyncio.create_task(something()) | |
| res = await shield(task) | |
| is equivalent to:: | |
| res = await something() | |
| *except* that if the coroutine containing it is cancelled, the | |
| Task running in ``something()`` is not cancelled. From the point | |
| of view of ``something()``, the cancellation did not happen. | |
| Although its caller is still cancelled, so the "await" expression | |
| still raises a :exc:`CancelledError`. |
I personally find the existing text to be clear enough, but I'm also a native English speaker and have read the entire sample :). My only suggestion for a minor improvement would be to move the "except" to the front in the form of "In the absence of cancellation, the statement::" or similar.
I'd also be happy to just close this issue as "won't fix", but it seemed worth opening the discussion if I happen to be in a minority finding it clear.
Metadata
Metadata
Assignees
Labels
Projects
Status
Done