Async Iterator#

Some API functions return an “async iterator”. An async iterator is something that is capable of being used in an async for statement.

These async iterators can be used as follows:

async for elem in channel.history():
    # do stuff with elem here

Certain utilities make working with async iterators easier, detailed below.

class discord.AsyncIterator#

Represents the “AsyncIterator” concept. Note that no such class exists, it is purely abstract.

async for x in y: Iterates over the contents of the async iterator.

await next()#

This function is a coroutine.

Advances the iterator by one, if possible. If no more items are found then this raises NoMoreItems.

await get(**attrs)#

This function is a coroutine.

Similar to utils.get() except run over the async iterator.

Getting the last message by a user named ‘Dave’ or None:

msg = await channel.history().get(author__name='Dave')

await find(predicate)#

This function is a coroutine.

Similar to utils.find() except run over the async iterator.

Unlike utils.find(), the predicate provided can be a coroutine.

Getting the last audit log with a reason or None:

def predicate(event):
    return event.reason is not None

event = await guild.audit_logs().find(predicate)

Parameters:: predicate – The predicate to use. Could be a coroutine.
Returns:: The first element that returns True for the predicate or None.

await flatten()#

This function is a coroutine.

Flattens the async iterator into a list with all the elements.

Returns:: A list of every element in the async iterator.
Return type:: list

chunk(max_size)#

Collects items into chunks of up to a given maximum size. Another AsyncIterator is returned which collects items into lists of a given size. The maximum chunk size must be a positive integer.

New in version 1.6.

Collecting groups of users:

async for leader, *users in reaction.users().chunk(3):
    ...

Warning

The last chunk collected may not be as large as max_size.

Parameters:: max_size – The size of individual chunks.
Return type:: AsyncIterator

map(func)#

This is similar to the built-in map function. Another AsyncIterator is returned that executes the function on every element it is iterating over. This function can either be a regular function or a coroutine.

Creating a content iterator:

def transform(message):
    return message.content

async for content in channel.history().map(transform):
    message_length = len(content)

Parameters:: func – The function to call on every element. Could be a coroutine.
Return type:: AsyncIterator

filter(predicate)#

This is similar to the built-in filter function. Another AsyncIterator is returned that filters over the original async iterator. This predicate can be a regular function or a coroutine.

Getting messages by non-bot accounts:

def predicate(message):
    return not message.author.bot

async for elem in channel.history().filter(predicate):
    ...

Parameters:: predicate – The predicate to call on every element. Could be a coroutine.
Return type:: AsyncIterator