API Reference¶

Bot¶

The default order in which everything is called and what methods call what:

on_raw_reaction_add(payload)
- process_raw_reaction_commands(payload)
  - get_raw_reaction_context(payload)
    - _early_invoke
      
      checks if reaction is a command that can be invoked without prefix. If
      
      invoke_without_prefix is True, returns a valid ctx here instead of continuing.
    - reaction_before_processing(ctx)
    - _wait_for_emoji_stream
      
      uses wait_for for reactions and tries to find a command from them.
    - reaction_after_processing(ctx)
      
      starts as a task
  - invoke(ctx)
    
    runs checks, before invokes, arg conversion, and all the normal stuff.

ReactionBotMixin¶

Can use this to add reaction commands for your own bot subclass. Just be sure nothing conflicts.

class OtherSubclassedBot(commands.Bot):
    # stuff here

class SubclassedBot(ReactionBotMixin, OtherSubclassedBot):
    pass

Note

Probably use/subclass ReactionBot or AutoShardedReactionBot instead.

class discord.ext.reactioncommands.ReactionBotMixin(command_prefix, prefix_emoji, listening_emoji, *args, listen_timeout=15, listen_total_timeout=120, remove_reactions_after=True, **kwargs)¶: Mixin for implementing reaction commands to Bot

ReactionBot¶

class discord.ext.reactioncommands.ReactionBot(command_prefix, prefix_emoji, listening_emoji, *args, listen_timeout=15, listen_total_timeout=120, remove_reactions_after=True, **kwargs)¶

Subclass of discord.ext.commands.Bot that adds reaction commands.

All other args and kwargs should be the same as discord.ext.commands.Bot.

prefix_emoji¶

Similar to command_prefix, but for starting emoji commands. Can be a string, list of strings, or callable/coroutine with the bot as its first parameter and discord.RawReactionActionEvent as its second parameter. This callable should return a string or list of strings.

Type: Union[Callable, list, str]

listening_emoji¶

Same as prefix_emoji. Can be None if you don’t want to invoke emoji groups with reactions or add a reaction on every prefix_emoji reaction.

# example callable, bot.emoji_prefixes is a mapping of
# guild id to emoji
def prefix(bot, payload):
    return bot.emoji_prefixes.get(payload.guild_id, "🤖")

Type: Union[Callable, str, None]

listen_timeout¶

Time in seconds that the bot will listen for emojis from a user. Will reset after each emoji added or removed. Pass None to disable. Default value is 15.

Type: Optional[int]

listen_total_timeout¶

Total time in seconds the bot will listen to a user. Prevents the user from adding or removing emojis and keeping the listen session active forever. Pass None to disable. Default value is 120.

Type: Optional[int]

remove_reactions_after¶

Whether the bot should remove its own reactions. Default value is True.

Type: Optional[bool]

case_insensitive¶

In addition to making normal commands case insensitive, attempts to normalize emojis by removing different skin colored and gendered modifiers when being invoked.

Ex: 👍🏿/👍🏾/👍🏽/👍🏼/👍🏻 –> 👍

🧙‍♂️/🧙‍♀️ –> 🧙

Type: Optional[bool]

add_command(command)¶

Adds a command to the internal list.

If the command passed has attribute emojis, will be treated as an instance of ReactionCommand.

Adds ReactionCommand.emojis to the internal mapping of reaction commands.

Parameters: command (commands.Command) – The command to add

async get_context(message, *, cls=<class 'discord.ext.commands.context.Context'>)¶

Functions exactly the same as original get_context().

Only difference is this function will attempt to set attribute ctx.reaction_command to False to indicate it is a message command.

Returns: The context from message
Return type: Context

async get_listening_emoji(payload)¶

Method that gets listening_emoji that is used for group invoke and letting the user know the bot is listening.

You can try using ProxyPayload.from_reaction_user() to use this with non raw reaction methods or from_message() for a message.

Parameters: payload (discord.RawReactionActionEvent) – payload to get listening_emoji from
Returns: A single emoji or None. If not None the bot will add as a reaction to indicate it is listening for reactions.
Return type: Optional[str]

async get_prefix_emoji(payload)¶

Method that gets the ReactionBot.prefix_emoji or list of emojis that can be used to start listening for commands.

Reaction mirror to get_prefix().

You can try using ProxyPayload.from_reaction_user() to use this with non raw reaction methods or from_message() for a message.

Parameters: payload (discord.RawReactionActionEvent) – payload to get prefix emoji from
Returns: A list of emojis, or single emoji that the bot is listening for.
Return type: Union[list, str]

async get_raw_reaction_context(payload, *, cls=<class 'discord.ext.reactioncommands.reactioncontext.ReactionContext'>, check=None)¶

Creates a ReactionContext from payload.

Meant to be used with on_raw_reaction_add() or on_raw_reaction_remove()

A lot of weird sh*t happens here. If something is not cached or provided, a ProxyBase where id may be used instead. It may have attributes set to other proxy objects. These proxy objects should behave similar to discord.PartialMessage, but subclassed from their originals. Most methods should work but attributes probably won’t.

Raw Reaction mirror to get_context().

Parameters

payload (discord.RawReactionActionEvent) – payload to start getting context from
cls – The class that will be used for the context.

check (Optional[Callable[discord.RawReactionActionEvent]]) –

Check that will be passed to wait_for(). Default check is equivalent to:

def check(payload: discord.RawReactionActionEvent):
    same_msg = payload.message_id == ctx.message.id
    same_user =  payload.user_id == ctx.author.id
    return same_msg and same_user

Returns

The context to invoke.

Return type

ReactionContext

get_reaction_command(name)¶

Gets a command by emoji.

Parameters: name (str) – Emoji(s) for the command.
Returns: The command or None
Return type: Optional[ReactionCommand]

async get_reaction_context(reaction, user, *, cls=<class 'discord.ext.reactioncommands.reactioncontext.ReactionContext'>, check=None, event_type=None)¶

Creates a context from Reaction and discord.User/discord.Member.

Meant to be used with on_reaction_add() or on_reaction_remove().

Reaction mirror to get_context().

Parameters

reaction (discosrd.Reaction) – the reaction the user added
user (Union[discord.Member, discord.User]) – the user who added the reaction
cls – The class that will be used for the context.

check (Optional[Callable[discord.RawReactionActionEvent]]) –

Check that will be passed to wait_for(). Default check is equivalent to:

def check(payload: discord.RawReactionActionEvent):
    same_msg = payload.message_id == ctx.message.id
    same_user =  payload.user_id == ctx.author.id
    return same_msg and same_user

Note

This still uses raw methods to listen for reactions.

Returns

The context to invoke.

Return type

ReactionContext

async process_raw_reaction_commands(payload)¶

Gets context and invokes from a payload. Takes payload from on_raw_reaction_add() or on_raw_reaction_remove().

Raw Reaction mirror to process_commands().

Note

If you overwrite raw_reaction_add or use discord.ext.commands.Bot.event() to overwrite, don’t forget to add this so reaction commands will still work.

Parameters: payload (discord.RawReactionActionEvent) – Payload to get context and invoke from.

async process_reaction_commands(reaction, user)¶

Gets context and invokes from a reaction and user. Gets arguments from from on_reaction_add() or on_reaction_remove().

Reaction mirror to process_commands().

Parameters

reaction (discord.Reaction) – The reaction the user added
user (Union[discord.Member, discord.User]) – The user who added the reaction

async reaction_after_processing(ctx)¶

Method that is called after verifying the command and before checks, @before_invoke, and command invoke. If ReactionBot.remove_reactions_after is True, they will be removed here.

Note

This method cleans up after reaction_before_processing(). If you overwrite one you should probably overwrite the other/call super().

Parameters: ctx (ReactionContext) – Context that will be invoked.

async reaction_before_processing(ctx, *, check_only=False)¶

Method that is called after verifying the prefix emoji and before the command input is added by the user. Determines if the bot should listen to reactions. ReactionBot.listening_emoji is added here.

Note

This method prevents users from starting multiple listening sessions and has some cleanup that is done in reaction_after_processing(). If you overwrite one you should probably overwrite the other /call super().

Parameters

ctx (ReactionContext) – Context that may be invoked.
check_only (bool) – Whether this should be standalone call without an expected matching reaction_after_processing() call. Default False.

Returns

Whether the bot should continue listening for reactions or not.

Return type

bool

reaction_command(emojis, *args, **kwargs)¶

Decorator that creates and adds a command to the internal list of commands. Calls @reaction_command().

args and kwargs should be the same as normal @Group.command().

Parameters

emojis (Union[list, str]) – An emoji or list of emojis that can be used to invoke this command.
invoke_with_message (Optional[bool]) – Whether the command can be invoke with messages. Default value is True.

Returns

A decorator that converts the provided method into a Command, adds it to the internal lsit of commands, then returns it.

Return type

Callable

property reaction_commands¶

Unique registered reaction commands.

Type: set[ReactionCommand]

reaction_group(emojis, *args, **kwargs)¶

Shortcut decorator that creates and adds a group to the internal list of commands. Calls @reaction_group().

args and kwargs should be the same as normal @Group.group().

Parameters

emojis (Union[list, str]) – An emoji or list of emojis that can be used to invoke this group.
invoke_with_message (Optional[bool]) – Whether the command can be invoke with messages. Default value is True.

Returns

A decorator that converts the provided method into a Group, adds it to the list of commands, then returns it.

Return type

Callable

remove_command(name)¶

Remove a command to the internal list by name.

Attempts to remove emojis from the internal mapping of emoji: Command. Be wary of manually updating emojis.

Parameters: name (str) – Name of the command to remove
Returns: The command that was removed
Return type: Optional[commands.Command]

remove_reaction_command(emoji)¶

Attempts to remove a reaction command by emoji

Parameters: emoji (str) – emoji of the reaction command to remove
Returns: The command that was removed or None
Return type: Optional[ReactionCommand]

AutoShardedReactionBot¶

Woah look at you. Imagine having a bot big enough to use AutoShardedReactionBot.

class discord.ext.reactioncommands.AutoShardedReactionBot(command_prefix, prefix_emoji, listening_emoji, *args, listen_timeout=15, listen_total_timeout=120, remove_reactions_after=True, **kwargs)¶: Sharded version of ReactionBot. IDK, probably works. Subclass of discord.ext.commands.AutoShardedBot.

ReactionCommand¶

ReactionCommand classes and other related stuff. Mostly behave like normal commands. Only big difference is emojis and altered _parse_arguments for argument parsing.

Decorators¶

Decorators for adding commands in cogs.

@discord.ext.reactioncommands.reaction_command(emojis, name=None, cls=None, **attrs)¶

Decorator that creates a command. Default class is ReactionCommand.

**attrs should be the same as @commands.command().

Parameters

emojis (Union[list, str]) – An emoji or list of emojis that can be used to invoke this command.
invoke_with_message (Optional[bool]) – Whether the command can be invoked from messages. Default value is True.

Returns

A decorator that converts the provided method into a Command, then returns it

Return type

Callable

@discord.ext.reactioncommands.reaction_group(emojis, name=None, **attrs)¶

Decorator that creates a group. Sets the cls kwarg to ReactionGroup.

**attrs should be the same as @commands.group().

Parameters

emojis (Union[list, str]) – An emoji or list of emojis that can be used to invoke this command.
invoke_with_message (Optional[bool]) – Whether the command can be invoked from messages. Default value is True.
case_insensitive (Optional[bool]) –
In addition to making normal commands case insensitive, attempts to normalize emojis by removing different skin colored and gendered modifiers when being invoked.

Ex: 👍🏿/👍🏾/👍🏽/👍🏼/👍🏻 –> 👍 or 🧙‍♂️/🧙‍♀️ –> 🧙

Returns

A decorator that converts the provided method into a Group, then returns it

Return type

Callable

Command Classes¶

You can combine these with your own command/group subclasses just like ReactionBotMixin. Same as above, be careful about any conflicts.

class discord.ext.reactioncommands.ReactionCommandMixin(*args, **kwargs)¶

Mixin for ReactionCommands

Implements ReactionCommand functionality for ReactionCommand and ReactionGroup.

Parameters

emojis (Union[str, list]) – emoji or list of emojis that the command cane be invoked with
invoke_with_message (bool) – Whether the command can be invoked from a message. Defaults to True.
invoke_without_prefix (bool) –
Whether the command can be invoked without ReactionBot.command_emoji. Defaults to False.

Warning

Can get a lot of unwanted commands with this set to True. Be careful.

class discord.ext.reactioncommands.ReactionGroupMixin(*args, **kwargs)¶

Mixin for ReactionGroups.

Implements reaction group functionality for ReactionBot and ReactionGroup.

Parameters

case_insensitive (Optional[bool]) –

In addition to making normal commands case insensitive, attempts to normalize emojis by removing different skin colored and gendered modifiers when being invoked.

Ex: 👍🏿/👍🏾/👍🏽/👍🏼/👍🏻 –> 👍 or 🧙‍♂️/🧙‍♀️ –> 🧙

ReactionCommand¶

class discord.ext.reactioncommands.ReactionCommand(*args, **kwargs)¶

Basically the same as commands.Command but with modified argument conversion flow to allow reaction invoke. Can be invoked with messages or reactions by default.

Other args and kwargs should be the same as commands.Command.

emojis¶

A list of emojis that the command can be invoked with. This attribute will always be a list even if the input is a single emoji.

Type: list

invoke_with_message¶

Whether the command can be invoked with messages or not. Pass False to only allow reaction invoke. Default value is True.

Type: Optional[bool]

invoke_without_prefix¶

Whether the command can be invoked without ReactionBot.command_emoji. Defaults to False.

Warning

Can get a lot of unwanted command invokes with this set to True. Be careful.

Type: bool

async _parse_arguments(ctx)¶: Warning

Argument converting had to change a lot for reaction commands.

No way to get input so there is no conversion or parsing done here unless it was invoked from a message.

When ReactionCommand or ReactionGroup is invoked from a reaction, args will be filled with their default value or None.

async can_run(ctx)¶

Overwritten to also raise ReactionOnlyCommand for commands that have invoke_with_message set to False.

Otherwise the same as can_run().

Parameters: ctx (Context) – Context to check if it can run against.
Raises: discord.ext.commands.CommandError – Error for why command can’t be run
Returns: Whether or not the command can run.
Return type: bool

ReactionGroup¶

class discord.ext.reactioncommands.ReactionGroup(*args, **kwargs)¶

Basically the same as commands.Group but with modified argument conversion flow to allow reaction invoke. Can be invoked with messages or reactions by default.

Other args and kwargs should be the same as commands.Group.

emojis¶

A list of emojis that the command can be invoked with. This attribute will always be a list even if the input is a single emoji.

Type: list

invoke_with_message¶

Whether the command can be invoked with messages or not. Pass False to only allow reaction invoke. Default value is True.

Type: Optional[bool]

case_insensitive¶

In addition to making normal commands case insensitive, attempts to normalize emojis by removing different skin colored and gendered modifiers when being invoked.

Ex: 👍🏿/👍🏾/👍🏽/👍🏼/👍🏻 –> 👍 or 🧙‍♂️/🧙‍♀️ –> 🧙

Type: Optional[bool]

invoke_without_prefix¶

Whether the command can be invoked without ReactionBot.command_emoji. Defaults to False.

Note

Can get a lot of unwanted command invokes with this set to True. Be careful.

Type: bool

async _parse_arguments(ctx)¶: Warning

Argument converting had to change a lot for reaction commands.

No way to get input so there is no conversion or parsing done here unless it was invoked from a message.

When ReactionCommand or ReactionGroup is invoked from a reaction, args will be filled with their default value or None.

add_command(command)¶

Adds a command to the internal list.

If the command passed has attribute emojis, will be treated as an instance of ReactionCommand.

Adds ReactionCommand.emojis to the internal mapping of reaction commands.

Parameters: command (commands.Command) – The command to add

async can_run(ctx)¶

Overwritten to also raise ReactionOnlyCommand for commands that have invoke_with_message set to False.

Otherwise the same as can_run().

Parameters: ctx (Context) – Context to check if it can run against.
Raises: discord.ext.commands.CommandError – Error for why command can’t be run
Returns: Whether or not the command can run.
Return type: bool

get_reaction_command(name)¶

Gets a command by emoji.

Parameters: name (str) – Emoji(s) for the command.
Returns: The command or None
Return type: Optional[ReactionCommand]

reaction_command(emojis, *args, **kwargs)¶

Decorator that creates and adds a command to the internal list of commands. Calls @reaction_command().

args and kwargs should be the same as normal @Group.command().

Parameters

emojis (Union[list, str]) – An emoji or list of emojis that can be used to invoke this command.
invoke_with_message (Optional[bool]) – Whether the command can be invoke with messages. Default value is True.

Returns

A decorator that converts the provided method into a Command, adds it to the internal lsit of commands, then returns it.

Return type

Callable

property reaction_commands¶

Unique registered reaction commands.

Type: set[ReactionCommand]

reaction_group(emojis, *args, **kwargs)¶

Shortcut decorator that creates and adds a group to the internal list of commands. Calls @reaction_group().

args and kwargs should be the same as normal @Group.group().

Parameters

emojis (Union[list, str]) – An emoji or list of emojis that can be used to invoke this group.
invoke_with_message (Optional[bool]) – Whether the command can be invoke with messages. Default value is True.

Returns

A decorator that converts the provided method into a Group, adds it to the list of commands, then returns it.

Return type

Callable

remove_command(name)¶

Remove a command to the internal list by name.

Attempts to remove emojis from the internal mapping of emoji: Command. Be wary of manually updating emojis.

Parameters: name (str) – Name of the command to remove
Returns: The command that was removed
Return type: Optional[commands.Command]

remove_reaction_command(emoji)¶

Attempts to remove a reaction command by emoji

Parameters: emoji (str) – emoji of the reaction command to remove
Returns: The command that was removed or None
Return type: Optional[ReactionCommand]

ReactionContext¶

There’s a lot of weird crap that goes on here if using raw methods. A ProxyBase is used if anything from payload cannot be resolved to a matching object from cache.

Ex: A ProxyMember or ProxyUser may be used instead of discord.Member or discord.User if get_member() or get_user() return None and payload.member is None.

class discord.ext.reactioncommands.ReactionContext(bot, payload, author, **attrs)¶

It’s a context, ye…

author¶

Warning

This is not the message author. It is the user who added reactions.

Type: Union[discord.Member, discord.User, ProxyBase]

payload¶

The payload this context came from, type depends on if this context came from raw method or not.

Type: Union[ProxyPayload, discord.RawReactionActionEvent]

message¶

Will be a full discord.Message if not from a raw event.

Warning

There’s no full message from payload, so ctx.message is a discord.PartialMessage. This PartialMessage’s channel and guild attributes might be a ProxyBase and becuase of that ctx.channel and ctx.guild might also be.

Use get() or fetch() to get the full message.

Type: Union[discord.Message, discord.PartialMessage]

reaction_command¶

Whether this ctx was invoked from reactions

Type: bool

full_emojis¶

String of all the emojis (except prefix and listening_emojis) that the user added or removed.

Type: str

listening_emoji¶

The listening emoji that was used with this ctx

Type: Optional[str]

remove_after¶

Tuples of emoji and the user to remove after command invoke.

List of tuples. Tuples are (emoji, user)

Type: list[tuple[str, discord.User]]

async fetch()¶

Shortcut to ctx.message.fetch().

Updates ReactionContext.message with the fetched message and returns it.

Raises: discord.HTTPException – Fetching the message failed
Returns: The message the PartialMessage was representing.
Return type: discord.Message

get(*, reverse=True)¶

Searches Bot.cached_messages for a message where ctx.message.id == message.id. Returns None if the message was not found.

If found, updates ReactionContext.message with the message and returns it.

Parameters: reverse (bool) – Whether should search reversed() cached_messages (newest messages first). Defaults to True.
Returns: The message or None
Return type: Optional[discord.Message]

ReactionHelp¶

Even comes with a help command. If you want to customize it there’s not really a simple way so you’re basically subclassing help.

class discord.ext.reactioncommands.ReactionHelp(*args, **kwargs)¶

Help command for reaction commands and normal commands. Subclassed from DefaultHelpCommand.

Refer to normal help command guides.

You can make use of ReactionCommand.emojis for which emojis that can invoke a command, ReactionContext.reaction_command to know if help was invoked from reactions or a message, and isinstance(cmd, ReactionCommandMixin) to check if a command is a ReactionCommand or similar.

emojis¶

String or list of strings for emojis to invoke the help command with. Defaults to ['🇭'].

Type: Union[str, list]

match_command_type¶

Whether commands should be also be filtered based on if help command was invoked from reactions or messages.

Only show reaction commands from reaction invoke, only show commands that can be invoked from a message from message invoke.

Type: bool

filter_regional(emojis)¶

Helper method that uses regex to sub in ‘\u200b’ to prevent regional indicators from forming flags but not splitting multi char emojis.

Parameters: emojis (str) – The emojis to split regional indicators
Returns: The input with ‘\u200b’ added in
Return type: str

get_ending_note()¶: Modified to show different text based on reaction or message invoke

get_command_signature(command)¶: Modified to add ReactionCommand.emojis to the signature if command is a ReactionCommand

add_indented_commands(commands, *, heading, max_size=None)¶: Modified to also show ReactionCommand.emojis

async filter_commands(commands, *, sort=False, key=None)¶: Modified to also filter ReactionHelp.match_command_type.

async command_callback(ctx, *, command=None)¶: Nothing changed if help was invoked from a message.

Note

If invoked from reactions, modified to use ReactionContext.full_emojis as command input so you can get help for specific commands with reactions.

Uses the same method of invoking subcommands to get help for a specific command. Add the emojis after ReactionHelp.emojis and listening_emoji.

Misc things¶

Things that were small enough and didn’t want to make a new page

Util functions¶

discord.ext.reactioncommands.utils.scrub_emojis(emoji)¶

Uses regex to remove skin color modifiers and gender modifiers.

Ex: 👍🏿/👍🏾/👍🏽/👍🏼/👍🏻 –> 👍

🧙‍♂️/🧙‍♀️ –> 🧙

Parameters: emoji (str) – text/emojis to remove modifiers from
Returns: the input text scrubbed of modifiers
Return type: str

Error¶

Just one for now

exception discord.ext.reactioncommands.ReactionOnlyCommand(message=None, *args)¶: Subclass of CommandError. Similar to DisabledCommand. Nothing added here.