Inconsistent behavior for duplicate inputs to `asyncio.as_completed` versus `asyncio.gather()`

[Alc-Was-Taken]

Bug report

Checklist

• I am confident this is a bug in CPython, not a bug in a third-party project
• I have searched the CPython issue tracker, and am confident this bug has not been reported before

A clear and concise description of the bug

The provided code displays varying behavior. The asserts below illustrate the disparity between the current and expected outcomes. While the assert using asyncio.gather functions correctly as intended, the one utilizing asyncio.as_completed shows inconsistency between the first and second call.

If the behavior is considered to be correct as intended, it would be helpful to have a brief explanation, possibly in the functools.cache documentation, clarifying the reasons behind this decision.

import asyncio
from functools import cache

@cache
async def foo():
  await asyncio.sleep(1)
  return 1

async def main():
  # assert await asyncio.gather(foo(), foo(), foo()) == [1, 1, 1], 'The result is as expected, if this line is uncommented'

  # When the above statement is uncommented, the following assert passes for [1], but the expected result is [1, 1, 1]
  assert [await result for result in asyncio.as_completed([foo(), foo(), foo()])] == [1]

  info = foo.cache_info()
  assert info.hits == 2 and info.misses == 1, 'The result is as expected, but the outcome of the previous statement is inconsistent'

  # RuntimeError: cannot reuse already awaited coroutine
  # The expected result is [1, 1, 1] or [1] if the behavior above is justified
  assert [await result for result in asyncio.as_completed([foo(), foo(), foo()])] == [1, 1, 1]

asyncio.run(main())

Your environment

• CPython versions tested on: Output from sys.version = 3.11.4
• Operating system and architecture: Output from sys.platform = darwin and platform.architecture() = 64bit

Linked PRs

• gh-107619: Extend functools LRU cache docs with generators and async functions #107934
• [3.12] gh-107619: Extend functools LRU cache docs with generators and async functions (GH-107934) #108161
• [3.11] gh-107619: Extend functools LRU cache docs with generators and async functions (GH-107934) #108162

[rhettinger]

When I run the posted code, I get:

RuntimeError: cannot reuse already awaited coroutine

This indicates what is happening. An async function returns a coroutine, not the actual function result from return 1. That means that the cache decorator is caching the coroutine, not the function result. Since the coroutine is not "reawaitable", we get an exception.

The docs for cache() reference the lru_cache() doc which say:

In general, the LRU cache should only be used when you want to reuse previously computed values. Accordingly, it doesn’t make sense to cache functions with side-effects, functions that need to create distinct mutable objects on each call, or impure functions such as time() or random().

I'm thinking of amending the last sentence to include generators and async functions in the list of places where it doesn't caching doesn't make sense.

Note, this isn't specific to caching. Depending on what they do with the inner function result, many other function wrappers would not work with async def.

[Alc-Was-Taken]

Thanks for replying @rhettinger, just to strengthen my understanding, how does your explanation clarify the first uncommented assert statement assert [await result for result in asyncio.as_completed([foo(), foo(), foo()])] == [1] why does this not raise a RuntimeError on the first occurrence and the resulting list is [1] not [1, 1, 1] when the cache hit suggests it made 2 more calls? The RuntimeError only happens when I run the same statement again.

EDIT:
I would expect [await result for result in asyncio.as_completed([foo(), foo(), foo()])] to behave the same as await asyncio.gather(foo(), foo(), foo())

I hope not to come across as impolite, but I kindly urge you to revisit the inline comments in the original code. By doing so, you may gain further clarity on my concerns in case something was overlooked in my explanation or by others. 🙂

[rhettinger]

Given that foo() always returns the exact same coroutine, the other behaviors follow from the differences between gather() and as_completed(). The former has explicit handling for duplicate futures. The latter stores the todo as a set which necessarily eliminates duplicates.

I'll leave this issue open in case one of the asyncio maintainers wants to weigh in on the intended behavior when given duplicate inputs. In the meantime, I'll edit the functools.cache() docs to emphasize that caching a generator or coroutine is not like caching a pure function.

[gvanrossum]

My immediate reaction is that it looks like a mistake to apply @cache to a coroutine (async def). That should probably documented. I don't know if this mistake or misunderstanding is common enough to guard explicitly against it in the cache decorator.

Given that, as Raymond says, many other decorators don't make sense for coroutines either, the documentation warning may well belong (or be repeated) in the asyncio docs for coroutines.

[Hels15]

Has it been fixed? What is the current state?