Description

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'

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']

Activity

1. JustAnotherArchivist commented on Jul 11, 2020

   

   JustAnotherArchivistmannequin

   on Jul 11, 2020

   MannequinAuthor

   More actions

   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.
2. JustAnotherArchivist

   added

   topic-asyncio

   type-featureA feature request or enhancementA feature request or enhancement

   on Jul 11, 2020
3. asvetlov commented on Jul 14, 2020

   

   asvetlov

   on Jul 14, 2020

   Contributor

   More actions

   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!
4. iritkatriel

   added

   easy

   3.11only security fixesonly security fixes

   on Mar 21, 2022
5. iritkatriel

   changed the title [-]Clarify whether Futures can be awaited multiple times[/-] [+][doc] Clarify that Futures can be awaited multiple times[/+] on Mar 21, 2022
6. iritkatriel

   added

   easy

   3.11only security fixesonly security fixes

   on Mar 21, 2022
7. iritkatriel

   changed the title [-]Clarify whether Futures can be awaited multiple times[/-] [+][doc] Clarify that Futures can be awaited multiple times[/+] on Mar 21, 2022
8. ezio-melotti

   transferred this issue fromon Apr 10, 2022
9. ezio-melotti

   added this to asyncioon Jul 17, 2022
10. ezio-melotti

    moved this to Todo in asyncioon Jul 17, 2022
11. kumaraditya303

    self-assigned this

    on Oct 2, 2022
12. kumaraditya303 commented on Oct 2, 2022

    

    kumaraditya303

    on Oct 2, 2022

    Contributor

    More actions

    I am surprised that this isn't documented. See #97738
13. kumaraditya303

    added

    docsDocumentation in the Doc dirDocumentation in the Doc dir

    3.10 (EOL)end of lifeend of life

    3.12only security fixesonly security fixes

    and removed

    type-featureA feature request or enhancementA feature request or enhancement

    on Oct 2, 2022
14. gvanrossum

    added a commit that references this issue on Oct 2, 2022

    GH-85447: Clarify docs about awaiting future multiple times (#97738)

    9151bbe
15. miss-islington

    added 2 commits that reference this issue on Oct 2, 2022

    pythonGH-85447: Clarify docs about awaiting future multiple times (py…

    66d52e2

    pythonGH-85447: Clarify docs about awaiting future multiple times (py…

    8ebba4c
16. gvanrossum

    closed this as completedon Oct 2, 2022
17. Repository owner moved this from Todo to Done in asyncioon Oct 2, 2022
18. miss-islington

    added 2 commits that reference this issue on Oct 2, 2022

    GH-85447: Clarify docs about awaiting future multiple times (GH-97738)

    72d445a

    GH-85447: Clarify docs about awaiting future multiple times (GH-97738)

    b26fb3c
19. carljm

    added a commit that references this issue on Oct 3, 2022

    Merge branch 'main' into dictwatch

    e83abac
20. pablogsal

    added a commit that references this issue on Oct 22, 2022

    GH-85447: Clarify docs about awaiting future multiple times (GH-97738)

    c8bdf33

Issue actions