Generator created in async function is actually an async_generator at runtime

[injust]

Code sample in pyright playground

import asyncio
from collections.abc import AsyncGenerator
from typing import reveal_type


async def values() -> AsyncGenerator[int]:
    yield 1
    yield 2
    yield 3


async def run() -> list[int]:
    bar = ([foo async for foo in values()] for _ in range(2))
    reveal_type(bar)  # Runtime type is 'async_generator'
    return next(bar)  # TypeError: 'async_generator' object is not an iterator


asyncio.run(run())

I'm confused by how generators work in async functions.

mypy and Pyright agree that bar is Generator[list[int], None, None], so everything type checks. But the code fails during runtine because bar is actually an async_generator.

[erictraut]

Hmm, I wasn't aware that any generator created within an async function's body is automatically created as async. Do you know if that behavior is documented?

[injust]

No, I couldn't find this documented anywhere.

Do you have any ideas, or is this something I should bring up at https://discuss.python.org/?

[erictraut]

@JelleZijlstra might know off the top of his head.

[JelleZijlstra]

This happens only if the genexp contains an async listcomp inside of it:

>>> async def foo():
...     print(x for x in [1])
...     print([a async for a in b] for x in [1])
...     
>>> asyncio.run(foo())
<generator object foo.<locals>.<genexpr> at 0x101a33a70>
<async_generator object foo.<locals>.<genexpr> at 0x101aa5130>

This makes sense because the inner listcomp is async and therefore must be evaluated within an async context. It's not clearly documented, though: https://docs.python.org/3.14/reference/expressions.html#generator-expressions says "If a generator expression contains either async for clauses or await expressions it is called an asynchronous generator expression. An asynchronous generator expression returns a new asynchronous generator object, which is an asynchronous iterator (see Asynchronous Iterators)." However, I wouldn't necessarily expect that to include async for expressions in a nested scope. Also, when a genexp includes an async genexp, the outer genexp doesn't become async.

So I'd recommend that you open a CPython bug report to have this clarified in the documentation.

[injust]

Also, when a genexp includes an async genexp, the outer genexp doesn't become async.

Could you clarify what you mean by this part? ([a async for a in b] for x in [1]) is a genexp that includes an async genexp, and it does return an async_generator.

[JelleZijlstra]

It includes a list comprehension, not a genexp.

>>> async def f():
...     x = ((a async for a in [1]) for b in [2])
...     print(x)
... 
>>> import asyncio
>>> asyncio.run(f())
<generator object f.<locals>.<genexpr> at 0x1008e5ff0>

[injust]

python/cpython#138097