bpo-40405: Fix asyncio.as_completed docs

[bharel]

Fixed as_completed docs to correctly state the function return value.

https://bugs.python.org/issue40405

[remilapeyre]

Hi @bharel, thanks for fixing the documentation!

[aeros]

@bharel I like the version you suggested in the bpo issue: "Each coroutine returns the next result from the set of the remaining awaitables, based upon the order of completion."

However, with some further consideration, I think we could make a slight additional improvement: "Each coroutine returned can be awaited to get the next result from the set of the remaining awaitables, based upon the order of completion."

(Note: italics only used to emphasize the part changed.)

I think it goes along better with the spirit of @1st1's original suggestion of using "allows to wait" (emphasizing that the coroutine objects need to be awaited to get the result), while reading a bit better from a grammatical perspective, and including the part about "order of completion" to make that part more explicit.

Any further feedback would be more than welcome though. With as_completed being a rather fundamental part of asyncio, I think it's important for the wording to be as clear as possible.

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[1st1]

"Each coroutine returned can be awaited to get the next result from the set of the remaining awaitables, based upon the order of completion."

SGMT, except I think that "based upon the order of completion." is unnecessary.

[bharel]

It's a long sentence. I was afraid it will be the case but then again there's no better option.
I think "based upon order of completion" does clarify, even if it's deductible from the function name and example.

[aeros]

@1st1

SGMT, except I think that "based upon the order of completion." is unnecessary.

Would you have another suggestion which clarifies that point, or do you think specifying that it's based upon completion order is unneeded? Although I have a preference for explicitly saying "order of completion", I think using your original suggestion for "earliest" would be okay as well:

"Each coroutine returned can be awaited to get the earliest next result from the set of the remaining awaitables."

[aeros]

@bharel If you would like to update the PR to the following:

"Each coroutine returned can be awaited to get the earliest next result from the set of the remaining awaitables."

I would be comfortable with merging it. The inclusion of "earliest" is similar enough to Yury's original proposal, and he approved of the recent version minus the "order of completion part".

[bharel]

@aeros I still believe "get the earliest next result from the set of the remaining awaitables" is a statement that overcomplicates it.

"earliest next result" is probably enough, or just "Each coroutine returned can be awaited to get the next result, based upon order of completion."
Sort of "less is more".

Either case, I've updated the PR to reflect your request.

[bharel]

I have made the requested changes; please review again.

[bedevere-bot]

Thanks for making the requested changes!

@aeros: please review the changes made to this pull request.

[aeros]

I still believe "get the earliest next result from the set of the remaining awaitables" is a statement that overcomplicates it.

"earliest next result" is probably enough, or just "Each coroutine returned can be awaited to get the next result, based upon order of completion."
Sort of "less is more".

Since Yury wanted to omit the "based upon order of completion" part with it being too verbose and essentially repeating the name, I believe the latest version provides the best compromise of including all necessary information to the reader without being too long or repetitive.

It's a bit difficult to get the wording 100% perfect for everyone since it's rather subjective, but I think this is the closest we can reasonably get without investing significantly more time into bikeshedding over the details. Eventually, the discussion reaches a point where you get diminishing returns in the time invested to tangible benefit ratio, and I think we have arrived there.

Either case, I've updated the PR to reflect your request.

Thanks! I'll go ahead and merge it. Also, thanks for the review @1st1.

[aeros]

Also, I'll backport to 3.9 and 3.8 so it appears in the latest versions of the documentation on docs.python.org.

[miss-islington]

Thanks @bharel for the PR, and @aeros for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9.
🐍🍒⛏🤖

[miss-islington]

Thanks @bharel for the PR, and @aeros for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-bot]

GH-20337 is a backport of this pull request to the 3.9 branch.

[bedevere-bot]

GH-20338 is a backport of this pull request to the 3.8 branch.