Title: asyncio doc: issue in as_completed() doc
Type: Stage: resolved
Components: asyncio, Documentation Versions: Python 3.6
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: aronacher, asvetlov, docs@python, gvanrossum, hynek, vstinner, xtreak, yselivanov
Priority: normal Keywords:

Created on 2016-07-22 10:08 by vstinner, last changed 2019-09-12 09:37 by asvetlov. This issue is now closed.

Messages (7)
msg270982 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-07-22 10:08
Remark on as_completed() doc by Hynek.

Futures are yielded in an unexpected order: as soon as a future completes.
msg271777 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2016-08-01 08:48
More explicitly:

The doc sells the function short.  If you have a bunch of futures and want to know as soon as one of them is ready: this is the function for you.

The only hint that this is the actual behavior comes from the *name* of the function; not the documentation.
msg280290 - (view) Author: Armin Ronacher (aronacher) * (Python committer) Date: 2016-11-08 10:59
I am not even sure what the function is supposed to tell me.  The documentation is very unclear and the example code does not help.  What is "fs" for instance?  And why would it return things that are not from fs?
msg280314 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2016-11-08 16:12
However, in general you should use a different pattern. Wrap each future in
a coroutine that does whatever you want to do to the first one ready and
maybe cancel the others. Then gather() all coroutines with the flag that
keeps errors.

--Guido (mobile)
msg280315 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2016-11-08 16:26
Such an idiom is IMHO not the main usefulness of this function tho.

As an (untested) example, something like

async def f(n):
   await asyncio.sleep(n)
   return n

for f in asyncio.as_completed([f(3), f(2), f(1)]):
    print(await f)

will print:


That’s *super* useful if you’re coordinating multiple independent external systems and need to process their results as soon as they arrive (and not once they’re *all* done).

Maybe it always worked by accident for me but it’s my understanding, that that is what this function is for (and I haven’t found another way to achieve it).

That’s why it would be nice if there’d be authoritative docs on what it’s supposed to do. :)
msg280316 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2016-11-08 16:30
Well, in that case the idiom will be even simpler: wrap each one in a
coroutine that awaits it and prints the result and then gather() all the
coroutine wrappers.
msg352077 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2019-09-12 09:34
Current docs read as below with an example to show that earliest future is returned. I guess this can be closed.

Run awaitable objects in the aws set concurrently. Return an iterator of Future objects. Each Future object returned represents the earliest result from the set of the remaining awaitables.
Date User Action Args
2019-09-12 09:37:47asvetlovsetstatus: open -> closed
resolution: fixed
stage: resolved
2019-09-12 09:34:23xtreaksetnosy: + xtreak, asvetlov
messages: + msg352077
2016-11-08 16:30:27gvanrossumsetmessages: + msg280316
2016-11-08 16:26:18hyneksetmessages: + msg280315
2016-11-08 16:12:10gvanrossumsetmessages: + msg280314
2016-11-08 10:59:27aronachersetnosy: + aronacher
messages: + msg280290
2016-08-01 08:48:00hyneksetnosy: + hynek
messages: + msg271777
2016-07-22 10:08:25vstinnercreate