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) Iterator protocol call
Awaiting result O(k) O(1) k = async generator's computation time
With default O(k) O(1) Returns default if exhausted

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)
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())