asyncio doc: issue in as_completed() doc

[vstinner]

BPO	27589
Nosy	@gvanrossum, @vstinner, @mitsuhiko, @asvetlov, @hynek, @1st1, @tirkarthi

^{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 = <Date 2019-09-12.09:37:47.399>
created_at = <Date 2016-07-22.10:08:25.473>
labels = ['docs', 'expert-asyncio']
title = 'asyncio doc: issue in as_completed() doc'
updated_at = <Date 2019-09-12.09:37:47.398>
user = 'https://github.com/vstinner'

bugs.python.org fields:

activity = <Date 2019-09-12.09:37:47.398>
actor = 'asvetlov'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-09-12.09:37:47.399>
closer = 'asvetlov'
components = ['Documentation', 'asyncio']
creation = <Date 2016-07-22.10:08:25.473>
creator = 'vstinner'
dependencies = []
files = []
hgrepos = []
issue_num = 27589
keywords = []
message_count = 7.0
messages = ['270982', '271777', '280290', '280314', '280315', '280316', '352077']
nosy_count = 8.0
nosy_names = ['gvanrossum', 'vstinner', 'aronacher', 'asvetlov', 'docs@python', 'hynek', 'yselivanov', 'xtreak']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue27589'
versions = ['Python 3.6']

[vstinner]

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.

[hynek]

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.

[mitsuhiko]

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?

[gvanrossum]

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)

[hynek]

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. :)

[gvanrossum]

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.

[tirkarthi]

Current docs read as below with an example to show that earliest future is returned. I guess this can be closed.

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

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.