`StopAsyncIteration`

StopAsyncIteration is a built-in exception that signals the end of an asynchronous iteration. This exception is specifically used in asynchronous iterators to indicate that there are no further items to yield. When you implement an asynchronous iterator, you raise it in the .__anext__() method to stop iteration.

You don’t typically catch this exception directly. Instead, you make sure your asynchronous iterators raise this exception to terminate iteration.

`StopAsyncIteration` Occurs When

StopAsyncIteration occurs when the asynchronous iterator has no further items to yield.

`StopAsyncIteration` Can Be Used When

Indicating the end of an asynchronous iteration in custom asynchronous iterators
Implicitly controlling the flow of asynchronous iteration in async for loops

`StopAsyncIteration` Examples

An example of when the exception appears:

Pythonshow_exception.py
      
    
import asyncio

async def demonstrate_exception():
    async_iterator = asyncio.as_completed([
        asyncio.create_task(asyncio.sleep(0)),
        asyncio.create_task(asyncio.sleep(0))
    ])
    print(await async_iterator.__anext__())  # Completes
    print(await async_iterator.__anext__())  # Completes
    print(await async_iterator.__anext__())  # Raises StopAsyncIteration

# Usage
asyncio.run(demonstrate_exception())

You won’t typically call .__anext__() directly in real code, and you generally won’t see StopAsyncIteration raised, because Python handles it during normal flow control.

An example of when you may raise the exception in a custom asynchronous iterator:

Pythonasync_counter.py
      
    
import asyncio

class AsyncCounter:
    def __init__(self, stop):
        self.current = 0
        self.stop = stop

    async def __anext__(self):
        if self.current >= self.stop:
            raise StopAsyncIteration
        await asyncio.sleep(0)  # Yield control to the event loop
        self.current += 1
        return self.current - 1

    def __aiter__(self):
        return self

# Usage
counter = AsyncCounter(5)

async def main():
    async for number in counter:
        print(number)

asyncio.run(main())  # Output: 0 1 2 3 4

In this example, AsyncCounter is an asynchronous iterator that counts from 0 up to stop. When current reaches stop, the iterator raises a StopAsyncIteration exception to end the iteration.

Tutorial

Asynchronous Iterators and Iterables in Python

In this tutorial, you'll learn how to create and use asynchronous iterators and iterables in Python. You'll explore their syntax and structure and discover how they can be leveraged to handle asynchronous operations more efficiently.

advanced python

For additional information on related topics, take a look at the following resources: