> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
1. `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.
2. `yield`: Suspends the function's execution, emits a value to the caller, and preserves the local state for resumption.
```python theme={"dark"}
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).
```python theme={"dark"}
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.
```python theme={"dark"}
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.
Tired of Poor Python Skills? Fix That With Deep Grasping!
Learn More
