Utility Functions 

redbot.core.utils.can_user_react_in(obj, messageable, /)[source]

Checks if a user/guild member can react in the given messageable.

This function properly resolves the permissions for discord.Thread as well.

Note

Without making an API request, it is not possible to reliably detect whether a guild member (who is NOT current bot user) can react in a private thread.

If it’s essential for you to reliably detect this, you will need to try fetching the thread member:

can_react = can_user_react_in(member, thread)
if thread.is_private() and not thread.permissions_for(member).manage_threads:
    try:
        await thread.fetch_member(member.id)
    except discord.NotFound:
        can_react = False

Parameters:

obj (discord.abc.User) – The user or member to check permissions for. If passed messageable resolves to a guild channel/thread, this needs to be an instance of discord.Member.
messageable (discord.abc.Messageable) – The messageable object to check permissions for. If this resolves to a DM/group channel, this function will return True.

Returns:

Whether the user can send messages in the given messageable.

Return type:

Raises:

TypeError – When the passed channel is of type discord.PartialMessageable.

redbot.core.utils.can_user_send_messages_in(obj, messageable, /)[source]

Checks if a user/member can send messages in the given messageable.

This function properly resolves the permissions for discord.Thread as well.

Note

Without making an API request, it is not possible to reliably detect whether a guild member (who is NOT current bot user) can send messages in a private thread.

If it’s essential for you to reliably detect this, you will need to try fetching the thread member:

can_send_messages = can_user_send_messages_in(member, thread)
if thread.is_private() and not thread.permissions_for(member).manage_threads:
    try:
        await thread.fetch_member(member.id)
    except discord.NotFound:
        can_send_messages = False

Parameters:

obj (discord.abc.User) – The user or member to check permissions for. If passed messageable resolves to a guild channel/thread, this needs to be an instance of discord.Member.
messageable (discord.abc.Messageable) – The messageable object to check permissions for. If this resolves to a DM/group channel, this function will return True.

Returns:

Whether the user can send messages in the given messageable.

Return type:

Raises:

TypeError – When the passed channel is of type discord.PartialMessageable.

redbot.core.utils.deduplicate_iterables(*iterables)[source]: Returns a list of all unique items in iterables, in the order they were first encountered.

redbot.core.utils.get_end_user_data_statement(file)[source]

This function attempts to get the end_user_data_statement key from cog’s info.json. This will log the reason if None is returned.

Example

You can use this function in cog package’s top-level __init__.py to conveniently reuse end user data statement from info.json file placed in the same directory:

from redbot.core.utils import get_end_user_data_statement

__red_end_user_data_statement__ = get_end_user_data_statement(__file__)

async def setup(bot):
    ...

To help detect issues with the info.json file while still allowing the cog to load, this function logs an error if info.json file doesn’t exist, can’t be parsed, or doesn’t have an end_user_data_statement key.

Parameters:: file (Union[pathlib.Path, str]) – The __file__ variable for the cog’s __init__.py file.
Returns:: The end user data statement found in the info.json or None if there was an issue finding one.
Return type:: Optional[str]

redbot.core.utils.get_end_user_data_statement_or_raise(file)[source]

This function attempts to get the end_user_data_statement key from cog’s info.json.

Example

You can use this function in cog package’s top-level __init__.py to conveniently reuse end user data statement from info.json file placed in the same directory:

from redbot.core.utils import get_end_user_data_statement_or_raise

__red_end_user_data_statement__ = get_end_user_data_statement_or_raise(__file__)

async def setup(bot):
    ...

In order to ensure that you won’t end up with no end user data statement, this function raises if info.json file doesn’t exist, can’t be parsed, or doesn’t have an end_user_data_statement key.

Parameters:

file (Union[pathlib.Path, str]) – The __file__ variable for the cog’s __init__.py file.

Returns:

The end user data statement found in the info.json.

Return type:

Raises:

FileNotFoundError – When info.json does not exist.
KeyError – When info.json does not have the end_user_data_statement key.
json.JSONDecodeError – When info.json can’t be decoded with json.load()
UnicodeError – When info.json can’t be decoded due to bad encoding.
Exception – Any other exception raised from pathlib and json modules when attempting to parse the info.json for the end_user_data_statement key.

class redbot.core.utils.AsyncIter(iterable, delay=0, steps=1)[source]

Bases: AsyncIterator[_T], Awaitable[List[_T]]

Asynchronous iterator yielding items from iterable that sleeps for delay seconds every steps items.

Parameters:

iterable (Iterable) – The iterable to make async.
delay (Union[float, int]) – The amount of time in seconds to sleep.
steps (int) – The number of iterations between sleeps.

Raises:

ValueError – When steps is lower than 1.

Examples

>>> from redbot.core.utils import AsyncIter
>>> async for value in AsyncIter(range(3)):
...     print(value)
0
1
2

async for ... in enumerate(start=0)[source]

Async iterable version of enumerate.

Parameters:: start (int) – The index to start from. Defaults to 0.
Returns:: An async iterator of tuples in the form of (index, item).
Return type:: AsyncIterator[Tuple[int, T]]

Examples

>>> from redbot.core.utils import AsyncIter
>>> iterator = AsyncIter(['one', 'two', 'three'])
>>> async for i in iterator.enumerate(start=10):
...     print(i)
(10, 'one')
(11, 'two')
(12, 'three')

async for ... in filter(function)[source]

Filter the iterable with an (optionally async) predicate.

Parameters:: function (Callable[[T], Union[bool, Awaitable[bool]]]) – A function or coroutine function which takes one item of iterable as an argument, and returns True or False.
Returns:: An object which can either be awaited to yield a list of the filtered items, or can also act as an async iterator to yield items one by one.
Return type:: AsyncFilter[T]

Examples

>>> from redbot.core.utils import AsyncIter
>>> def predicate(value):
...     return value <= 5
>>> iterator = AsyncIter([1, 10, 5, 100])
>>> async for i in iterator.filter(predicate):
...     print(i)
1
5

>>> from redbot.core.utils import AsyncIter
>>> def predicate(value):
...     return value <= 5
>>> iterator = AsyncIter([1, 10, 5, 100])
>>> await iterator.filter(predicate)
[1, 5]

__await__()[source]

Returns a list of the iterable.

Examples

>>> from redbot.core.utils import AsyncIter
>>> iterator = AsyncIter(range(5))
>>> await iterator
[0, 1, 2, 3, 4]

await find(predicate, default=None)[source]

Calls predicate over items in iterable and return first value to match.

Parameters:

predicate (Union[Callable, Coroutine]) – A function that returns a boolean-like result. The predicate provided can be a coroutine.
default (Optional[Any]) – The value to return if there are no matches.

Raises:

TypeError – When predicate is not a callable.

Examples

>>> from redbot.core.utils import AsyncIter
>>> await AsyncIter(range(3)).find(lambda x: x == 1)
1

await flatten()[source]

Returns a list of the iterable.

Examples

>>> from redbot.core.utils import AsyncIter
>>> iterator = AsyncIter(range(5))
>>> await iterator.flatten()
[0, 1, 2, 3, 4]

map(func)[source]

Set the mapping callable for this instance of AsyncIter.

Important

This should be called after AsyncIter initialization and before any other of its methods.

Parameters:: func (Union[Callable, Coroutine]) – The function to map values to. The function provided can be a coroutine.
Raises:: TypeError – When func is not a callable.

Examples

>>> from redbot.core.utils import AsyncIter
>>> async for value in AsyncIter(range(3)).map(bool):
...     print(value)
False
True
True

await next(default=Ellipsis)[source]

Returns a next entry of the iterable.

Parameters:: default (Optional[Any]) – The value to return if the iterator is exhausted.
Raises:: StopAsyncIteration – When default is not specified and the iterator has been exhausted.

Examples

>>> from redbot.core.utils import AsyncIter
>>> iterator = AsyncIter(range(5))
>>> await iterator.next()
0
>>> await iterator.next()
1

async for ... in without_duplicates()[source]

Iterates while omitting duplicated entries.

Examples

>>> from redbot.core.utils import AsyncIter
>>> iterator = AsyncIter([1,2,3,3,4,4,5])
>>> async for i in iterator.without_duplicates():
...     print(i)
1
2
3
4
5

Chat Formatting

for ... in redbot.core.utils.chat_formatting.pagify(text, delims=('\n',), *, priority=False, escape_mass_mentions=True, shorten_by=8, page_length=2000)[source]

Generate multiple pages from the given text.

The returned iterator supports length estimation with operator.length_hint().

Note

This does not respect code blocks or inline code.

Parameters:

text (str) – The content to pagify and send.
delims (sequence of str, optional) – Characters where page breaks will occur. If no delimiters are found in a page, the page will break after page_length characters. By default this only contains the newline.
priority (bool) – Set to True to choose the page break delimiter based on the order of delims. Otherwise, the page will always break at the last possible delimiter.
escape_mass_mentions (bool) – If True, any mass mentions (here or everyone) will be silenced.
shorten_by (int) – How much to shorten each page by. Defaults to 8.
page_length (int) – The maximum length of each page. Defaults to 2000.

Yields:

str – Pages of the given text.

redbot.core.utils.chat_formatting.bold(text, escape_formatting=True)[source]

Get the given text in bold.

Note: By default, this function will escape text prior to emboldening.

Parameters:

text (str) – The text to be marked up.
escape_formatting (bool, optional) – Set to False to not escape markdown formatting in the text.

Returns:

The marked up text.

Return type:

redbot.core.utils.chat_formatting.box(text, lang='')[source]

Get the given text in a code block.

Parameters:

text (str) – The text to be marked up.
lang (str, optional) – The syntax highlighting language for the codeblock.

Returns:

The marked up text.

Return type:

redbot.core.utils.chat_formatting.error(text)[source]

Get text prefixed with an error emoji.

Parameters:: text (str) – The text to be prefixed.
Returns:: The new message.
Return type:: str

redbot.core.utils.chat_formatting.escape(text, *, mass_mentions=False, formatting=False)[source]

Get text with all mass mentions or markdown escaped.

Parameters:

text (str) – The text to be escaped.
mass_mentions (bool, optional) – Set to True to escape mass mentions in the text.
formatting (bool, optional) – Set to True to escape any markdown formatting in the text.

Returns:

The escaped text.

Return type:

redbot.core.utils.chat_formatting.format_perms_list(perms)[source]

Format a list of permission names.

This will return a humanized list of the names of all enabled permissions in the provided discord.Permissions object.

Parameters:: perms (discord.Permissions) – The permissions object with the requested permissions to list enabled.
Returns:: The humanized list.
Return type:: str

redbot.core.utils.chat_formatting.header(text, size)[source]

Formats a header.

Parameters:

text (str) – The text for the header.
size (Literal['small', 'medium', 'large']) – The size of the header (‘small’, ‘medium’ or ‘large’)

Returns:

The new message.

Return type:

redbot.core.utils.chat_formatting.humanize_list(items, *, locale=None, style='standard')[source]

Get comma-separated list, with the last element joined with and.

Parameters:

items (Sequence[str]) – The items of the list to join together.
locale (Optional[str]) – The locale to convert, if not specified it defaults to the bot’s locale.
style (str) –
The style to format the list with.

Note: Not all styles are necessarily available in all locales, see documentation of babel.lists.format_list for more details.

standard
A typical ‘and’ list for arbitrary placeholders. eg. “January, February, and March”

standard-short
A short version of a ‘and’ list, suitable for use with short or abbreviated placeholder values. eg. “Jan., Feb., and Mar.”

or
A typical ‘or’ list for arbitrary placeholders. eg. “January, February, or March”

or-short
A short version of an ‘or’ list. eg. “Jan., Feb., or Mar.”

unit
A list suitable for wide units. eg. “3 feet, 7 inches”

unit-short
A list suitable for short units eg. “3 ft, 7 in”

unit-narrow
A list suitable for narrow units, where space on the screen is very limited. eg. “3′ 7″”

Raises:

ValueError – The locale does not support the specified style.

Examples

>>> humanize_list(['One', 'Two', 'Three'])
'One, Two, and Three'
>>> humanize_list(['One'])
'One'
>>> humanize_list(['omena', 'peruna', 'aplari'], style='or', locale='fi')
'omena, peruna tai aplari'

redbot.core.utils.chat_formatting.humanize_number(val, override_locale=None)[source]

Convert an int or float to a str with digit separators based on bot locale.

Parameters:

val (Union[int, float]) – The int/float to be formatted.
override_locale (Optional[str]) – A value to override bot’s regional format.

Raises:

decimals.InvalidOperation – If val is greater than 10 x 10^21 for some locales, 10 x 10^24 in others.

Returns:

Locale-aware formatted number.

Return type:

redbot.core.utils.chat_formatting.humanize_timedelta(*, timedelta=None, seconds=None, negative_format=None, maximum_units=None)[source]

Get a locale aware human timedelta representation.

This works with either a timedelta object or a number of seconds.

Fractional values will be omitted.

Values that are less than 1 second but greater than -1 second will be an empty string.

Parameters:

timedelta (Optional[datetime.timedelta]) – A timedelta object
seconds (Optional[SupportsInt]) – A number of seconds
negative_format (Optional[str]) – How to format negative timedeltas, using %-formatting rules. Defaults to “negative %s”
maximum_units (Optional[int]) – The maximum number of different units to output in the final string.

Returns:

A locale aware representation of the timedelta or seconds.

Return type:

Raises:

ValueError – The function was called with neither a number of seconds nor a timedelta object, or with a maximum_units less than 1.

Examples

>>> humanize_timedelta(seconds=314)
'5 minutes, 14 seconds'
>>> humanize_timedelta(timedelta=timedelta(minutes=3.14), maximum_units=1)
'3 minutes'
>>> humanize_timedelta(timedelta=timedelta(days=-3.14), negative_format="%s ago", maximum_units=3)
'3 days, 3 hours, 21 minutes ago'

redbot.core.utils.chat_formatting.hyperlink(text, url)[source]

Create hyperlink markdown with text and a URL.

Parameters:

text (str) – The text which will contain the link.
url (str) – The URL used for the hyperlink.

Returns:

The new message.

Return type:

redbot.core.utils.chat_formatting.info(text)[source]

Get text prefixed with an info emoji.

Parameters:: text (str) – The text to be prefixed.
Returns:: The new message.
Return type:: str

redbot.core.utils.chat_formatting.inline(text)[source]

Get the given text as inline code.

Parameters:: text (str) – The text to be marked up.
Returns:: The marked up text.
Return type:: str

redbot.core.utils.chat_formatting.italics(text, escape_formatting=True)[source]

Get the given text in italics.

Note: By default, this function will escape text prior to italicising.

Parameters:

text (str) – The text to be marked up.
escape_formatting (bool, optional) – Set to False to not escape markdown formatting in the text.

Returns:

The marked up text.

Return type:

redbot.core.utils.chat_formatting.question(text)[source]

Get text prefixed with a question emoji.

Parameters:: text (str) – The text to be prefixed.
Returns:: The new message.
Return type:: str

redbot.core.utils.chat_formatting.quote(text)[source]

Quotes the given text.

Parameters:: text (str) – The text to be marked up.
Returns:: The marked up text.
Return type:: str

redbot.core.utils.chat_formatting.rich_markup(*objects, crop=True, emoji=True, highlight=True, justify=None, markup=True, no_wrap=None, overflow=None, width=None)[source]

Returns a codeblock with ANSI formatting for colour support.

This supports a limited set of Rich markup, and rich helper functions. (https://rich.readthedocs.io/en/stable/index.html)

Parameters:

*objects (Any) – The text to convert to ANSI formatting.
crop (Optional[bool]) – Crop output to width of virtual terminal. Defaults to True.
emoji (Optional[bool]) – Enable emoji code. Defaults to True.
highlight (Optional[bool]) – Enable automated highlighting. Defaults to True.
justify (Optional[str]) – Justify method: “default”, “left”, “right”, “center”, or “full”. Defaults to None.
markup (Optional[bool]) – Boolean to enable Console Markup. Defaults to True.
no_wrap (Optional[bool]) – Disables word wrapping. Defaults to None.
overflow (Optional[str]) – Overflow method: “ignore”, “crop”, “fold”, or “ellipsis”. Defaults to None.
width (Optional[int]) – The width of the virtual terminal. Defaults to 80 characters long.

Returns:

The ANSI formatted text in a codeblock.

Return type:

redbot.core.utils.chat_formatting.spoiler(text, escape_formatting=True)[source]

Get the given text as a spoiler.

Note: By default, this function will escape text prior to making the text a spoiler.

Parameters:

text (str) – The text to be marked up.
escape_formatting (bool, optional) – Set to False to not escape markdown formatting in the text.

Returns:

The marked up text.

Return type:

redbot.core.utils.chat_formatting.strikethrough(text, escape_formatting=True)[source]

Get the given text with a strikethrough.

Note: By default, this function will escape text prior to applying a strikethrough.

Parameters:

text (str) – The text to be marked up.
escape_formatting (bool, optional) – Set to False to not escape markdown formatting in the text.

Returns:

The marked up text.

Return type:

redbot.core.utils.chat_formatting.subtext(text)[source]

Formats subtext from the given text.

Parameters:: text (str) – The text to format as subtext.
Returns:: The new message.
Return type:: str

redbot.core.utils.chat_formatting.success(text)[source]

Get text prefixed with a success emoji.

Parameters:: text (str) – The text to be prefixed.
Returns:: The new message.
Return type:: str

redbot.core.utils.chat_formatting.text_to_file(text, filename='file.txt', *, spoiler=False, encoding='utf-8')[source]

Prepares text to be sent as a file on Discord, without character limit.

This writes text into a bytes object that can be used for the file or files parameters of discord.abc.Messageable.send().

Parameters:

text (str) – The text to put in your file.
filename (str) – The name of the file sent. Defaults to file.txt.
spoiler (bool) – Whether the attachment is a spoiler. Defaults to False.

Returns:

The file containing your text.

Return type:

discord.File

redbot.core.utils.chat_formatting.underline(text, escape_formatting=True)[source]

Get the given text with an underline.

Note: By default, this function will escape text prior to underlining.

Parameters:

text (str) – The text to be marked up.
escape_formatting (bool, optional) – Set to False to not escape markdown formatting in the text.

Returns:

The marked up text.

Return type:

redbot.core.utils.chat_formatting.warning(text)[source]

Get text prefixed with a warning emoji.

Parameters:: text (str) – The text to be prefixed.
Returns:: The new message.
Return type:: str

Embed Helpers

redbot.core.utils.embed.randomize_colour(embed)[source]

Gives the provided embed a random color. There is an alias for this called randomize_color

Parameters:: embed (discord.Embed) – The embed to add a color to
Returns:: The embed with the color set to a random color
Return type:: discord.Embed

Menus

redbot.core.utils.menus.DEFAULT_CONTROLS = mappingproxy({'⬅️': <function prev_page>, '❌': <function close_menu>, '➡️': <function next_page>}): Default controls for menu() that contain controls for previous page, closing menu, and next page.

await redbot.core.utils.menus.close_menu(ctx, pages, controls, message, page, timeout, emoji, *, user=None)[source]: Function for closing (deleting) menu which is suitable for use in controls mapping that is passed to menu().

await redbot.core.utils.menus.menu(ctx, pages, controls=None, message=None, page=0, timeout=30.0, *, user=None)[source]

An emoji-based menu

All functions for handling what a particular emoji does should be coroutines (i.e. async def). Additionally, they must take all of the parameters of this function, in addition to a string representing the emoji reacted with. This parameter should be the 7th one, and none of the parameters in the handling functions are optional.

Warning

The user parameter is considered provisional. If no issues arise, we plan on including it under developer guarantees in the first release made after 2024-05-24.

Warning

If you’re using the user param, you need to pass it as a keyword-only argument, and set None as the default in your function.

Examples

Simple menu using default controls:

from redbot.core.utils.menus import menu

pages = ["Hello", "Hi", "Bonjour", "Salut"]
await menu(ctx, pages)

Menu with a custom control performing an action (deleting an item from pages list):

from redbot.core.utils import menus

items = ["Apple", "Banana", "Cucumber", "Dragonfruit"]

def generate_pages():
    return [f"{fruit} is an awesome fruit!" for fruit in items]

async def delete_item_action(ctx, pages, controls, message, page, timeout, emoji):
    fruit = items.pop(page)  # lookup and remove corresponding fruit name
    await ctx.send(f"I guess you don't like {fruit}, huh? Deleting...")
    pages = generate_pages()
    if not pages:
        return await menus.close_menu(ctx, pages, controls, message, page, timeout)
    page = min(page, len(pages) - 1)
    return await menus.menu(ctx, pages, controls, message, page, timeout)

pages = generate_pages()
controls = {**menus.DEFAULT_CONTROLS, "\N{NO ENTRY SIGN}": delete_item_action}
await menus.menu(ctx, pages, controls)

Menu with custom controls that output a result (confirmation prompt):

from redbot.core.utils.menus import menu

async def control_yes(*args, **kwargs):
    return True

async def control_no(*args, **kwargs):
    return False

msg = "Do you wish to continue?"
controls = {
    "\N{WHITE HEAVY CHECK MARK}": control_yes,
    "\N{CROSS MARK}": control_no,
}
reply = await menu(ctx, [msg], controls)
if reply:
    await ctx.send("Continuing...")
else:
    await ctx.send("Okay, I'm not going to perform the requested action.")

Parameters:

ctx (commands.Context) – The command context
pages (Union[List[str], List[discord.Embed]]) – The pages of the menu. All pages need to be of the same type (either str or discord.Embed).
controls (Optional[Mapping[str, Callable]]) – A mapping of emoji to the function which handles the action for the emoji. The signature of the function should be the same as of this function and should additionally accept an emoji parameter of type str. If not passed, DEFAULT_CONTROLS is used or only a close menu control is shown when pages is of length 1.
message (Optional[discord.Message]) – The message representing the menu. Usually None when first opening the menu
page (int) – The current page number of the menu
timeout (float) – The time (in seconds) to wait for a reaction
user (Optional[discord.User]) –
The user allowed to interact with the menu. Defaults to ctx.author.

Warning

This parameter is provisional. If no issues arise, we plan on including it under developer guarantees in the first release made after 2024-05-24.

Raises:

RuntimeError – If either of the notes above are violated

await redbot.core.utils.menus.next_page(ctx, pages, controls, message, page, timeout, emoji, *, user=None)[source]: Function for showing next page which is suitable for use in controls mapping that is passed to menu().

await redbot.core.utils.menus.prev_page(ctx, pages, controls, message, page, timeout, emoji, *, user=None)[source]: Function for showing previous page which is suitable for use in controls mapping that is passed to menu().

redbot.core.utils.menus.start_adding_reactions(message, emojis)[source]

Start adding reactions to a message.

This is a non-blocking operation - calling this will schedule the reactions being added, but the calling code will continue to execute asynchronously. There is no need to await this function.

This is particularly useful if you wish to start waiting for a reaction whilst the reactions are still being added - in fact, this is exactly what menu() uses to do that.

Parameters:

message (discord.Message) – The message to add reactions to.
emojis (Iterable[Union[str, discord.Emoji]]) – The emojis to react to the message with.

Returns:

The task for the coroutine adding the reactions.

Return type:

asyncio.Task

Event Predicates

MessagePredicate

class redbot.core.utils.predicates.MessagePredicate(predicate)[source]

Bases: Callable[[Message], bool]

A simple collection of predicates for message events.

These predicates intend to help simplify checks in message events and reduce boilerplate code.

This class should be created through the provided classmethods. Instances of this class are callable message predicates, i.e. they return True if a message matches the criteria.

All predicates are combined with MessagePredicate.same_context().

Examples

Waiting for a response in the same channel and from the same author:

await bot.wait_for("message", check=MessagePredicate.same_context(ctx))

Waiting for a response to a yes or no question:

pred = MessagePredicate.yes_or_no(ctx)
await bot.wait_for("message", check=pred)
if pred.result is True:
    # User responded "yes"
    ...

Getting a member object from a user’s response:

pred = MessagePredicate.valid_member(ctx)
await bot.wait_for("message", check=pred)
member = pred.result

result

The object which the message content matched with. This is dependent on the predicate used - see each predicate’s documentation for details, not every method will assign this attribute. Defaults to None.

Type:: Any

classmethod cancelled(ctx=None, channel=None, user=None)[source]

Match if the message is [p]cancel.

Parameters:

ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod contained_in(collection, ctx=None, channel=None, user=None)[source]

Match if the response is contained in the specified collection.

The index of the response in the collection sequence is assigned to the result attribute.

Parameters:

collection (Sequence[str]) – The collection containing valid responses.
ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod equal_to(value, ctx=None, channel=None, user=None)[source]

Match if the response is equal to the specified value.

Parameters:

value (str) – The value to compare the response with.
ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod greater(value, ctx=None, channel=None, user=None)[source]

Match if the response is greater than the specified value.

Parameters:

value (Union[int, float]) – The value to compare the response with.
ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod has_role(ctx=None, channel=None, user=None)[source]

Match if the response refers to a role which the author has.

Assigns the matching discord.Role object to result.

One of user or ctx must be supplied. This predicate cannot be used in DM.

Parameters:

ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[Union[discord.TextChannel, discord.VoiceChannel, discord.StageChannel, discord.Thread]]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod length_greater(length, ctx=None, channel=None, user=None)[source]

Match if the response’s length is greater than the specified length.

Parameters:

length (int) – The value to compare the response’s length with.
ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod length_less(length, ctx=None, channel=None, user=None)[source]

Match if the response’s length is less than the specified length.

Parameters:

length (int) – The value to compare the response’s length with.
ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod less(value, ctx=None, channel=None, user=None)[source]

Match if the response is less than the specified value.

Parameters:

value (Union[int, float]) – The value to compare the response with.
ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod lower_contained_in(collection, ctx=None, channel=None, user=None)[source]

Same as contained_in(), but the response is set to lowercase before matching.

Parameters:

collection (Sequence[str]) – The collection containing valid lowercase responses.
ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod lower_equal_to(value, ctx=None, channel=None, user=None)[source]

Match if the response as lowercase is equal to the specified value.

Parameters:

value (str) – The value to compare the response with.
ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod positive(ctx=None, channel=None, user=None)[source]

Match if the response is a positive number.

Assigns the response to result as a float.

Parameters:

ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod regex(pattern, ctx=None, channel=None, user=None)[source]

Match if the response matches the specified regex pattern.

This predicate will use re.search to find a match. The resulting match object will be assigned to result.

Parameters:

pattern (Union[pattern object, str]) – The pattern to search for in the response.
ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod same_context(ctx=None, channel=None, user=None)[source]

Match if the message fits the described context.

Parameters:

ctx (Optional[Context]) – The current invocation context.
channel (Optional[discord.abc.Messageable]) – The messageable object we expect a message in. If unspecified, defaults to ctx.channel. If ctx is unspecified too, the message’s channel will be ignored.
user (Optional[discord.abc.User]) – The user we expect a message from. If unspecified, defaults to ctx.author. If ctx is unspecified too, the message’s author will be ignored.

Returns:

The event predicate.

Return type:

classmethod valid_float(ctx=None, channel=None, user=None)[source]

Match if the response is a float.

Assigns the response to result as a float.

Parameters:

ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod valid_int(ctx=None, channel=None, user=None)[source]

Match if the response is an integer.

Assigns the response to result as an int.

Parameters:

ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod valid_member(ctx=None, channel=None, user=None)[source]

Match if the response refers to a member in the current guild.

Assigns the matching discord.Member object to result.

This predicate cannot be used in DM.

Parameters:

ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[Union[discord.TextChannel, discord.VoiceChannel, discord.StageChannel, discord.Thread]]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod valid_role(ctx=None, channel=None, user=None)[source]

Match if the response refers to a role in the current guild.

Assigns the matching discord.Role object to result.

This predicate cannot be used in DM.

Parameters:

ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[Union[discord.TextChannel, discord.VoiceChannel, discord.StageChannel, discord.Thread]]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod valid_text_channel(ctx=None, channel=None, user=None)[source]

Match if the response refers to a text channel in the current guild.

Assigns the matching discord.TextChannel object to result.

This predicate cannot be used in DM.

Parameters:

ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[Union[discord.TextChannel, discord.VoiceChannel, discord.StageChannel, discord.Thread]]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

classmethod yes_or_no(ctx=None, channel=None, user=None)[source]

Match if the message is “yes”/”y” or “no”/”n”.

This will assign True for yes, or False for no to the result attribute.

Parameters:

ctx (Optional[Context]) – Same as ctx in same_context().
channel (Optional[discord.abc.Messageable]) – Same as channel in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

ReactionPredicate

class redbot.core.utils.predicates.ReactionPredicate(predicate)[source]

Bases: Callable[[Reaction, User], bool]

A collection of predicates for reaction events.

All checks are combined with ReactionPredicate.same_context().

Examples

Confirming a yes/no question with a tick/cross reaction:

from redbot.core.utils.predicates import ReactionPredicate
from redbot.core.utils.menus import start_adding_reactions

msg = await ctx.send("Yes or no?")
start_adding_reactions(msg, ReactionPredicate.YES_OR_NO_EMOJIS)

pred = ReactionPredicate.yes_or_no(msg, ctx.author)
await ctx.bot.wait_for("reaction_add", check=pred)
if pred.result is True:
    # User responded with tick
    ...
else:
    # User responded with cross
    ...

Waiting for the first reaction from any user with one of the first 5 letters of the alphabet:

from redbot.core.utils.predicates import ReactionPredicate
from redbot.core.utils.menus import start_adding_reactions

msg = await ctx.send("React to me!")
emojis = ReactionPredicate.ALPHABET_EMOJIS[:5]
start_adding_reactions(msg, emojis)

pred = ReactionPredicate.with_emojis(emojis, msg)
await ctx.bot.wait_for("reaction_add", check=pred)
# pred.result is now the index of the letter in `emojis`

result

The object which the reaction matched with. This is dependent on the predicate used - see each predicate’s documentation for details, not every method will assign this attribute. Defaults to None.

Type:: Any

ALPHABET_EMOJIS = ('🇦', '🇧', '🇨', '🇩', '🇪', '🇫', '🇬', '🇭', '🇮', '🇯', '🇰', '🇱', '🇲', '🇳', '🇴', '🇵', '🇶', '🇷', '🇸', '🇹', '🇺', '🇻', '🇼', '🇽', '🇾', '🇿')

A tuple of all 26 alphabetical letter emojis.

Type:: Tuple[str, …]

NUMBER_EMOJIS = ('0⃣', '1⃣', '2⃣', '3⃣', '4⃣', '5⃣', '6⃣', '7⃣', '8⃣', '9⃣')

A tuple of all single-digit number emojis, 0 through 9.

Type:: Tuple[str, …]

YES_OR_NO_EMOJIS = ('✅', '❎')

A tuple containing the tick emoji and cross emoji, in that order.

Type:: Tuple[str, str]

classmethod same_context(message=None, user=None)[source]

Match if a reaction fits the described context.

This will ignore reactions added by the bot user, regardless of whether or not user is supplied.

Parameters:

message (Optional[discord.Message]) – The message which we expect a reaction to. If unspecified, the reaction’s message will be ignored.
user (Optional[discord.abc.User]) – The user we expect to react. If unspecified, the user who added the reaction will be ignored.

Returns:

The event predicate.

Return type:

ReactionPredicate

classmethod with_emojis(emojis, message=None, user=None)[source]

Match if the reaction is one of the specified emojis.

Parameters:

emojis (Sequence[Union[str, discord.Emoji, discord.PartialEmoji]]) – The emojis of which one we expect to be reacted.
message (discord.Message) – Same as message in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

ReactionPredicate

classmethod yes_or_no(message=None, user=None)[source]

Match if the reaction is a tick or cross emoji.

The emojis used are in ReactionPredicate.YES_OR_NO_EMOJIS.

This will assign True for yes, or False for no to the result attribute.

Parameters:

message (discord.Message) – Same as message in same_context().
user (Optional[discord.abc.User]) – Same as user in same_context().

Returns:

The event predicate.

Return type:

ReactionPredicate

Mod Helpers

await redbot.core.utils.mod.check_permissions(ctx, perms)[source]

Check if the author has required permissions.

This will always return True if the author is a bot owner, or has the administrator permission. If perms is empty, this will only check if the user is a bot owner.

Parameters:

ctx (Context) – The command invocation context to check.
perms (Dict[str, bool]) – A dictionary mapping permissions to their required states. Valid permission names are those listed as properties of the discord.Permissions class.

Returns:

True if the author has the required permissions.

Return type:

redbot.core.utils.mod.get_audit_reason(author, reason=None, *, shorten=False)[source]

Construct a reason to appear in the audit log.

Parameters:

author (discord.Member) – The author behind the audit log action.
reason (str) – The reason behind the audit log action.
shorten (bool) – When set to True, the returned audit reason string will be shortened to fit the max length allowed by Discord audit logs.

Returns:

The formatted audit log reason.

Return type:

await redbot.core.utils.mod.is_admin_or_superior(bot, obj)[source]

Same as is_mod_or_superior except for admin permissions.

If a message is passed, its author’s permissions are checked. If a role is passed, it simply checks if it is the admin role.

Parameters:

bot (redbot.core.bot.Red) – The bot object.
obj (discord.Message or discord.Member or discord.Role) – The object to check permissions for.

Returns:

True if the object has admin permissions.

Return type:

Raises:

TypeError – If the wrong type of obj was passed.

await redbot.core.utils.mod.is_mod_or_superior(bot, obj)[source]

Check if an object has mod or superior permissions.

If a message is passed, its author’s permissions are checked. If a role is passed, it simply checks if it is one of either the admin or mod roles.

Parameters:

bot (redbot.core.bot.Red) – The bot object.
obj (discord.Message or discord.Member or discord.Role) – The object to check permissions for.

Returns:

True if the object has mod permissions.

Return type: