[doc] Clarify that Futures can be awaited multiple times

[JustAnotherArchivist]

BPO	41275
Nosy	@asvetlov, @1st1, @aeros, @JustAnotherArchivist

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-07-11.02:41:58.789>
labels = ['easy', '3.11', 'type-feature', 'expert-asyncio']
title = '[doc] Clarify that Futures can be awaited multiple times'
updated_at = <Date 2022-03-21.10:51:26.622>
user = 'https://github.com/JustAnotherArchivist'

bugs.python.org fields:

activity = <Date 2022-03-21.10:51:26.622>
actor = 'iritkatriel'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['asyncio']
creation = <Date 2020-07-11.02:41:58.789>
creator = 'JustAnotherArchivist'
dependencies = []
files = []
hgrepos = []
issue_num = 41275
keywords = ['easy']
message_count = 2.0
messages = ['373504', '373628']
nosy_count = 4.0
nosy_names = ['asvetlov', 'yselivanov', 'aeros', 'JustAnotherArchivist']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue41275'
versions = ['Python 3.11']

[JustAnotherArchivist]

While the situation is clear regarding coroutine objects (bpo-25887), as far as I can see, the documentation doesn't specify whether asyncio.Futures can be awaited multiple times. The code has always (at least since the integration into CPython) allowed for it since Future.__await__ simply returns Future.result() if it is already done. Is this guaranteed/intended behaviour, as also implied by some of the comments on bpo-25887, or is it considered an implementation detail?

Here are the only two things I found in the documentation regarding this:

library/asyncio-task: When a Future object is awaited it means that the coroutine will wait until the Future is resolved in some other place.

library/asyncio-future: Future is an awaitable object. Coroutines can await on Future objects until they either have a result or an exception set, or until they are cancelled.

Neither of these say anything about awaiting a Future that is already resolved, i.e. has a result, has an exception, or was cancelled.

If this is intended to be guaranteed, it should be mentioned in the Future documentation. If it is considered an implementation detail, it's probably not necessary to explicitly mention this anywhere, but it might be a good idea to add another line to e.g. the asyncio.wait example on how to correctly retrieve the result of an already-awaited Future/Task.

[asvetlov]

The allowance to wait for the future object multiple times is settled in stone. This cannot be changed without breaking very many codes.

So yes, asyncio guarantees that the feature is settled in stone. If set_value() / set_exception() was called, the value/exception is returned (raised) on every following await fut.

Pull request for documentation with clarification of the status quo is welcome!