Python Async Generator Function

An asynchronous generator function is a function defined using async def that contains one or more yield expressions. When called, it does not execute the function body; instead, it returns an asynchronous generator object. It combines the state-suspension capabilities of standard generators with the non-blocking execution of asynchronous programming, allowing the function to await awaitables between yield statements. Unlike a coroutine function (which returns a coroutine object implementing __await__), an asynchronous generator function returns an asynchronous generator object implementing __aiter__ and __anext__.

Syntax and Mechanics

An asynchronous generator function relies on two primary keywords:

async def: Declares the asynchronous function. The presence of a yield statement inside the body instructs the Python parser to classify it strictly as an asynchronous generator function rather than a coroutine function.
yield: Suspends the function’s execution, emits a value to the caller, and preserves the local state for resumption.

import asyncio

async def async_sequence_generator(limit: int):
    for i in range(limit):
        await asyncio.sleep(0.1)  # Yields control to the event loop
        yield i                   # Yields a value to the consumer

The Asynchronous Iterator Protocol

Under the hood, the returned asynchronous generator object implements the Asynchronous Iterator Protocol (PEP 525):

__aiter__(self): Returns the asynchronous generator object itself.
__anext__(self): Returns an awaitable that, when awaited, executes the generator’s body until the next yield expression. If the generator terminates, the awaitable raises a StopAsyncIteration exception.

Consumption

Because __anext__ returns an awaitable, asynchronous generators cannot be consumed using standard for loops or the next() built-in. They must be consumed within an asynchronous context using async for or the anext() built-in (introduced in Python 3.10).

async def consume_async_generator():
    # Implicit consumption via async for
    async for item in async_sequence_generator(3):
        print(item)
        
    # Explicit consumption via anext()
    gen_obj = async_sequence_generator(3)
    first_item = await anext(gen_obj)
    second_item = await anext(gen_obj)

Bidirectional Communication

Like standard generators, asynchronous generators support bidirectional communication, allowing the caller to send data or exceptions back into the suspended generator. These methods return awaitables:

asend(value): Resumes the generator and evaluates the yield expression to value.
athrow(type, [value, [traceback]]): Raises an exception at the point where the generator is suspended.
aclose(): Raises a GeneratorExit exception at the yield expression, forcing the generator to terminate and run any pending finally blocks.

async def bidirectional_async_generator():
    while True:
        # Execution pauses here until anext() or asend() is awaited
        received = yield "Ready"
        await asyncio.sleep(0.1)
        yield f"Received: {received}"

async def interact():
    gen = bidirectional_async_generator()
    
    # Prime the generator
    status = await anext(gen)          # Returns "Ready"
    
    # Send data into the generator
    response = await gen.asend(42)     # Returns "Received: 42"
    
    # Close the generator
    await gen.aclose()

Technical Constraints

No Return Values: An asynchronous generator function cannot contain a return value statement. It may only use an empty return statement, which immediately raises StopAsyncIteration to terminate the generator.
Event Loop Dependency: Because it utilizes await, the generator’s execution is strictly bound to a running asynchronous event loop (e.g., asyncio.run()).
Yield From: The yield from syntax is not supported in asynchronous generators. To yield values from another asynchronous generator, you must use an explicit async for loop.