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 orNone
.
- 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:
- chunk(max_size)
Collects items into chunks of up to a given maximum size. Another
AsyncIterator
is returned which collects items intolist
s of a given size. The maximum chunk size must be a positive integer.Added 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:
- map(func)
This is similar to the built-in
map
function. AnotherAsyncIterator
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:
- filter(predicate)
This is similar to the built-in
filter
function. AnotherAsyncIterator
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: