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

Created on 2016-07-22 10:08 by vstinner, last changed 2016-11-08 16:30 by gvanrossum.

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

https://docs.python.org/dev/library/asyncio-task.html#asyncio.as_completed

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:

1
2
3

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.
History
Date User Action Args
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