Python StopAsyncIteration – Tutorial with Examples

The StopAsyncIteration exception is raised to signal that an asynchronous iterator has no more items to produce. It’s raised implicitly by the anext() method of an asynchronous iterator when there are no more items to produce. By catching this exception, you can detect the end of iteration for an asynchronous iterator.

In this article, you will learn about Python StopAsyncIteration method with multiple examples. You’ll understand how to raise StopAsyncIteration exception with multiple examples.

1. What is an Async Iterator?

Async iterators were introduced in Python 3.5.

An object that produces data asynchronously is an asynchronous iterator. Python’s built-in async for each statement can iterate over asynchronous iterators.
Async iterators are often used to represent streams, infinite sequences, or large, asynchronous datasets.

For example, the following asynchronous iterator produces numbers incrementally:

import asyncio

class NumberProducer:
    def __init__(self, start, stop):
        self.current = start
        self.stop = stop

    async def __aiter__(self):
        return self

    async def __anext__(self):
        if self.current > self.stop:
            raise StopAsyncIteration

        result = self.current
        self.current += 1
        return result

async def main():
    async for number in NumberProducer(0, 5):
        print(number)

asyncio.run(main())

Output

0
1
2
3
4
5

As you can see, once the iterator has no items left to yield, it raises a StopAsyncIteration exception to signal the end of iteration.

2. What is a StopAsyncIteration Exception?

StopAsyncIteration is Python’s built-in exception type for signaling the end of iteration for asynchronous iterators. Async iterators are expected to raise this exception when there are no longer any items to produce. StopAsyncIteration is silent, which means it doesn’t print a traceback or error message, so it’s up to you to detect and handle the exception.

3. How to raise StopAsyncIteration explicitly?

To signal the end of the iteration for an asynchronous iterator, you can raise a StopAsyncIteration exception explicitly. Here’s an example of how to do that:

import asyncio

async def main():
    i = 0
    async for number in range(10):
        if i >= 5:
            raise StopAsyncIteration
        i += 1
        print(number)

asyncio.run(main())

Output

0
1
2
3
4

In this example, the async for each loop yields numbers from 0 to 9.
If the counter is greater than or equal to 5, it raises a StopAsyncIteration exception to signal the end of iteration. As a result, only the first five numbers (0 to 4) are printed.

4. How to detect StopAsyncIteration?

Detecting StopAsyncIteration is similar to detecting StopIteration for synchronous iterators. The recommended way to handle the end of iteration is to use an async for each loop. This loop manages the iteration and automatically catches StopAsyncIteration.

import asyncio

async def MyAsyncIterable():
    yield 1
    yield 2
    raise StopAsyncIteration

async def main():
    async for i in MyAsyncIterable():
        print(i)

asyncio.run(main())

Output

1
2

In this example, the MyAsyncIterable() asynchronous generator raises StopAsyncIteration to signal the end of iteration, and the async foreach loop catches it silently.

Conclusion

In this article, you have learned how to work with the StopAsyncIteration exception in Python. You can use this exception to signal the end of iteration for asynchronous iterators. You can either raise it explicitly or let the iterator raise it implicitly.
The async for each loop is the recommended way to handle asynchronous iteration and automatically catches StopAsyncIteration.