Home Python Built-in Functions anext() Python anext() Function Definition In Python 3.10 and newer, anext(async_iterator) is the async version of next() . It returns an awaitable ; await anext(it) produces the next item. When the iterator is exhausted, awaiting it raises StopAsyncIteration.
Like next(), it accepts a default : await anext(it, None) returns None at the end instead of raising. Get the iterator with aiter() or use an async generator object directly, and run everything inside asyncio.run().
anext() is a built-in function : it lives in the builtins module, so it is always available without an import. New in Python 3.10. On Python 3.8 and 3.9, use await it.__anext__() instead.
Syntax Await the call inside an async def function.
async def main():
item = await anext(async_iterator)
item = await anext(async_iterator, default) Call What it does await anext(agen)The next item. await anext(agen, None)None when exhausted.anext(agen)An awaitable; nothing runs until it is awaited. await anext(aiter(x))The first item of an async iterable.
Forgetting await is the most common bug: you get an awaitable object instead of the item.
Library declarations anext(async_iterator, /)
anext(async_iterator, default, /)
# returns an awaitable; new in Python 3.10 Parameters Parameter Description async_iterator Required. An object with __anext__(), such as an async generator. default Optional. Returned instead of raising StopAsyncIteration.
Return Value Return Value Description awaitable Awaiting it gives the next item, or default when the iterator is exhausted.
Python Examples 1. Items and default 2. StopAsyncIteration 3. First match Example 1 — Await Items and Fall Back to a Default Read two values from an async generator, then get the default at the end.
import asyncio
async def numbers():
yield 1
yield 2
async def main():
it = numbers()
print(await anext(it))
print(await anext(it))
print(await anext(it, "no more"))
asyncio.run(main()) How It Works Async generators are async iterators. numbers() can be passed straight to anext().Await each step. await anext(it) resumes the generator until its next yield.Default at the end. After two values, the third call returns "no more" instead of raising.One entry point. asyncio.run(main()) runs the whole coroutine.Example 2 — Handle StopAsyncIteration Read the only message of an async inbox and catch the end-of-stream exception.
import asyncio
async def one_message():
yield "hello"
async def main():
inbox = one_message()
print(await anext(inbox))
try:
await anext(inbox)
except StopAsyncIteration:
print("StopAsyncIteration: inbox is empty")
asyncio.run(main()) hello
StopAsyncIteration: inbox is empty How It Works A single item. The generator yields "hello" once.No default. The second await anext(inbox) has nothing to return.Async end signal. Async iterators raise StopAsyncIteration, not StopIteration.Caught like any error. A normal try/except handles it inside the coroutine.Example 3 — First Matching Reading from an Async Stream Use an async generator expression with anext(..., None), and see that anext() returns an awaitable.
import asyncio
async def sensor_readings():
for value in [17, 21, 24, 19]:
await asyncio.sleep(0)
yield value
async def first_above(limit):
readings = (r async for r in sensor_readings() if r > limit)
return await anext(readings, None)
async def main():
print(await first_above(20))
print(await first_above(30))
pending = anext(sensor_readings())
print(hasattr(pending, "__await__"))
print(await pending)
asyncio.run(main()) How It Works Async filter. (r async for r in ... if r > limit) is an async generator expression.First match or None. 21 is the first reading above 20; nothing exceeds 30, so the default is returned.Awaitable first. Without await, anext() returns an object with __await__, not a number.Await later. Awaiting pending finally runs the generator and yields 17.Frequently Asked Questions Which Python version added anext()? Python 3.10, together with aiter().
What is the difference between next() and anext()? next() returns the item directly from a regular iterator. anext() returns an awaitable for an async iterator; you must await it.
What does anext() raise at the end? StopAsyncIteration, unless you pass a default value.
Why do I get a coroutine-like object instead of a value? You forgot await. Write item = await anext(it).
Can I call anext() outside async code? No. Await it inside an async def function that runs in an event loop, for example via asyncio.run().
Next: any() True if at least one item is truthy.
any() → About the author Developer, cloud engineer, and technical writer
I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.
10 people found this page helpful
Helpful Share Copy link Suggestion