Skip to content

anext() Function

The anext() function returns the next item from an asynchronous iterator.

Complexity Reference

Operation Time Space Notes
anext() call O(1) O(1) Plus the __anext__() call itself, which for an async def or async generator only builds the awaitable
Awaiting result O(k) O(1) k = work of one __anext__() step, including its awaits; space excludes the step's own allocations
With default O(k) O(1) Returns default if exhausted; O(1) extra per suspension

Hand-written awaitables and the default

With a default, anext() wraps the awaitable that __anext__() returns and calls its __await__() on every step of the await, not once. An async def __anext__() or an async generator resumes where it left off and completes normally. A class whose __await__() is a generator function starts over on each call; if every call suspends, the await never completes. For such an iterator, leave the default out and catch StopAsyncIteration yourself.

Basic Usage

Get Next Async Item

import asyncio

async def async_generator():
    for i in range(3):
        yield i

async def main():
    async_iter = aiter(async_generator())

    # Get next item - O(k) where k = async iterator work for this step
    value = await anext(async_iter)
    print(value)  # 0

    value = await anext(async_iter)
    print(value)  # 1

asyncio.run(main())

With Default Value

import asyncio

async def async_generator():
    yield 1
    yield 2
    # Iterator exhausted after

async def main():
    async_iter = aiter(async_generator())

    print(await anext(async_iter))  # 1
    print(await anext(async_iter))  # 2

    # Default when exhausted - O(1) once iterator is exhausted
    value = await anext(async_iter, "END")
    print(value)  # "END"

asyncio.run(main())

Without Default (Raises Exception)

import asyncio

async def async_generator():
    yield 1

async def main():
    async_iter = aiter(async_generator())

    print(await anext(async_iter))  # 1

    try:
        # No default - raises StopAsyncIteration when exhausted (O(1) at exhaustion)
        print(await anext(async_iter))
    except StopAsyncIteration:
        print("Iterator exhausted")

asyncio.run(main())

Practical Example

import asyncio

async def fetch_items(items):
    for item in items:
        await asyncio.sleep(0.1)  # Simulate async work
        yield item

async def main():
    # Create async iterator - O(1)
    iterator = aiter(fetch_items(["a", "b", "c"]))

    # Get items manually - O(k) each where k depends on iterator body
    first = await anext(iterator)
    print(f"First: {first}")  # First: a

    second = await anext(iterator, None)
    print(f"Second: {second}")  # Second: b

    # Get remaining with loop
    async for item in iterator:
        print(f"Item: {item}")  # Item: c

asyncio.run(main())

Comparison with next()

import asyncio

# next() - synchronous - O(1) call, the generator's step runs inside it
def sync_gen():
    yield 1
    yield 2

sync_iter = iter(sync_gen())
print(next(sync_iter))  # Synchronous

# anext() - asynchronous - O(1) call, awaiting depends on generator
async def async_gen():
    yield 1
    yield 2

async def main():
    async_iter = aiter(async_gen())
    print(await anext(async_iter))  # Must await

asyncio.run(main())