Skip to content

Potentially clarify asyncio.shield equivalence example #111274

Closed as not planned
Closed as not planned
@zware

Description

@zware

Documentation

As evidenced by GH-108427, the current example for asyncio.shield() may be confusing. The example:

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

No one assigned

    Labels

    Projects

    Status

    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions