Warning

This document is for Red's development version, which can be significantly different from previous releases. If you're a regular user, you should read the Red documentation for the current stable release.

Bot

RedBase

class redbot.core.bot.RedBase(*args, cli_flags=None, bot_dir=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/red-discordbot/checkouts/latest/docs'), **kwargs)[source]

Bases: redbot.core.commands.commands.GroupMixin, redbot.core.rpc.RPCMixin, discord.ext.commands.bot.AutoShardedBot

The historical reasons for this mixin no longer apply and only remains temporarily to not break people relying on the publicly exposed bases existing.

register_rpc_handler(method)

Registers a method to act as an RPC handler if the internal RPC server is active.

When calling this method through the RPC server, use the naming scheme “cogname__methodname”.

Important

All parameters to RPC handler methods must be JSON serializable objects. The return value of handler methods must also be JSON serializable.

Important

RPC support is included in Red on a provisional basis. Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary.

Parameters

method (coroutine) – The method to register with the internal RPC server.

unregister_rpc_handler(method)

Unregisters an RPC method handler.

This will be called automatically for you on cog unload and will pass silently if the method is not previously registered.

Important

RPC support is included in Red on a provisional basis. Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary.

Parameters

method (coroutine) – The method to unregister from the internal RPC server.

add_cog(cog)[source]

Adds a “cog” to the bot.

A cog is a class that has its own event listeners and commands.

Parameters

cog (Cog) – The cog to register to the bot.

Raises
  • TypeError – The cog does not inherit from Cog.

  • CommandError – An error happened during loading.

add_command(command)[source]

Adds a Command or its subclasses into the internal list of commands.

This is usually not called, instead the command() or group() shortcut decorators are used instead.

Parameters

command (Command) – The command to add.

Raises
  • ClientException – If the command is already registered.

  • TypeError – If the command passed is not a subclass of Command.

add_permissions_hook(hook)[source]

Add a permissions hook.

Permissions hooks are check predicates which are called before calling Requires.verify, and they can optionally return an override: True to allow, False to deny, and None to default to normal behaviour.

Parameters

hook – A command check predicate which returns True, False or None.

await allowed_by_whitelist_blacklist(who=None, *, who_id=None, guild_id=None, role_ids=None)[source]

This checks if a user or member is allowed to run things, as considered by Red’s whitelist and blacklist.

If given a user object, this function will check the global lists

If given a member, this will additionally check guild lists

If omiting a user or member, you must provide a value for who_id

You may also provide a value for guild_id in this case

If providing a member by guild and member ids, you should supply role_ids as well

Parameters

who (Optional[Union[discord.Member, discord.User]]) – The user or member object to check

Other Parameters
  • who_id (Optional[int]) – The id of the user or member to check If not providing a value for who, this is a required parameter.

  • guild_id (Optional[int]) – When used in conjunction with a provided value for who_id, checks the lists for the corresponding guild as well.

  • role_ids (Optional[List[int]]) – When used with both who_id and guild_id, checks the role ids provided. This is required for accurate checking of members in a guild if providing ids.

Raises

TypeError – Did not provide who or who_id

Returns

True if user is allowed to run things, False otherwise

Return type

bool

before_invoke(coro)[source]

Overridden decorator method for Red’s before_invoke behavior.

This can safely be used purely functionally as well.

3rd party cogs should remove any hooks which they register at unload using remove_before_invoke_hook

Below behavior shared with discord.py:

Note

The before_invoke hooks are only called if all checks and argument parsing procedures pass without error. If any check or argument parsing procedures fail then the hooks are not called.

Parameters

coro (Callable[[commands.Context], Awaitable[Any]]) – The coroutine to register as the pre-invoke hook.

Raises

TypeError – The coroutine passed is not actually a coroutine.

clear_permission_rules(guild_id, **kwargs)[source]

Clear all permission overrides in a scope.

Parameters
  • guild_id (Optional[int]) – The guild ID to wipe permission overrides for. If None, this will clear all global rules and leave all guild rules untouched.

  • **kwargs – Keyword arguments to be passed to each required call of commands.Requires.clear_all_rules

await cog_disabled_in_guild(cog, guild)[source]

Check if a cog is disabled in a guild

Parameters
Returns

Return type

bool

await cog_disabled_in_guild_raw(cog_name, guild_id)[source]

Check if a cog is disabled in a guild without the cog or guild object

Parameters
  • cog_name (str) – This should be the cog’s qualified name, not neccessarily the classname

  • guild_id (int) –

Returns

Return type

bool

await embed_requested(channel, user, command=None)[source]

Determine if an embed is requested for a response.

Parameters
Returns

True if an embed is requested

Return type

bool

await get_admin_role_ids(guild_id)[source]

Gets the admin role ids for a guild id.

await get_admin_roles(guild)[source]

Gets the admin roles for a guild.

get_cog(name)[source]

Gets the cog instance requested.

If the cog is not found, None is returned instead.

Parameters

name (str) – The name of the cog you are requesting. This is equivalent to the name passed via keyword argument in class creation or the class name if unspecified.

get_command(name)[source]

Get a Command or subclasses from the internal list of commands.

This could also be used as a way to get aliases.

The name could be fully qualified (e.g. 'foo bar') will get the subcommand bar of the group command foo. If a subcommand is not found then None is returned just as usual.

Parameters

name (str) – The name of the command to get.

Returns

The command that was requested. If not found, returns None.

Return type

Command or subclass

await get_embed_color(location)[source]

Get the embed color for a location. This takes into account all related settings.

Parameters

location (discord.abc.Messageable) – Location to check embed color for.

Returns

Embed color for the provided location.

Return type

discord.Color

await get_embed_colour(location)

Get the embed color for a location. This takes into account all related settings.

Parameters

location (discord.abc.Messageable) – Location to check embed color for.

Returns

Embed color for the provided location.

Return type

discord.Color

await get_mod_role_ids(guild_id)[source]

Gets the mod role ids for a guild id.

await get_mod_roles(guild)[source]

Gets the mod roles for a guild.

await get_owner_notification_destinations()[source]

Gets the users and channels to send to

await get_shared_api_tokens(service_name)[source]

Gets the shared API tokens for a service

Parameters

service_name (str) – The service to get tokens for.

Returns

A Mapping of token names to tokens. This mapping exists because some services have multiple tokens.

Return type

Dict[str, str]

await get_valid_prefixes(guild=None)[source]

This gets the valid prefixes for a guild.

If not provided a guild (or passed None) it will give the DM prefixes.

This is just a fancy wrapper around get_prefix

Parameters

guild (Optional[discord.Guild]) – The guild you want prefixes for. Omit (or pass None) for the DM prefixes

Returns

If a guild was specified, the valid prefixes in that guild. If a guild was not specified, the valid prefixes for DMs

Return type

List[str]

await handle_data_deletion_request(*, requester, user_id)[source]

This tells each cog and extension, as well as any APIs in Red to go delete data

Calling this should be limited to interfaces designed for it.

See redbot.core.commands.Cog.delete_data_for_user for details about the parameters and intent.

Parameters
  • requester

  • user_id

Returns

A named tuple (failed_modules, failed_cogs, unhandled) containing lists with names of failed modules, failed cogs, and cogs that didn’t handle data deletion request.

Return type

DataDeletionResults

await ignored_channel_or_guild(ctx)[source]

This checks if the bot is meant to be ignoring commands in a channel or guild, as considered by Red’s whitelist and blacklist.

Parameters

ctx – Context object of the command which needs to be checked prior to invoking or a Message object which might be intended for use as a command.

Returns

True if commands are allowed in the channel, False otherwise

Return type

bool

await is_admin(member)[source]

Checks if a member is an admin of their guild.

await is_automod_immune(to_check)[source]

Checks if the user, message, context, or role should be considered immune from automated moderation actions.

This will return False in direct messages.

Parameters

to_check (discord.Message or commands.Context or discord.abc.User or discord.Role) – Something to check if it would be immune

Returns

True if immune

Return type

bool

await is_mod(member)[source]

Checks if a member is a mod or admin of their guild.

await is_owner(user)[source]

Determines if the user should be considered a bot owner.

This takes into account CLI flags and application ownership.

By default, application team members are not considered owners, while individual application owners are.

Parameters

user (Union[discord.User, discord.Member]) –

Returns

Return type

bool

staticmethod list_packages()[source]

Lists packages present in the cogs the folder

await load_extension(spec)[source]

Loads an extension.

An extension is a python module that contains commands, cogs, or listeners.

An extension must have a global function, setup defined as the entry point on what to do when the extension is loaded. This entry point must have a single argument, the bot.

Parameters

name (str) – The extension name to load. It must be dot separated like regular Python imports if accessing a sub-module. e.g. foo.test if you want to import foo/test.py.

Raises
  • ExtensionNotFound – The extension could not be imported.

  • ExtensionAlreadyLoaded – The extension is already loaded.

  • NoEntryPointError – The extension does not have a setup function.

  • ExtensionFailed – The extension or its setup function had an execution error.

await logout()[source]

Logs out of Discord and closes all connections.

await message_eligible_as_command(message)[source]

Runs through the things which apply globally about commands to determine if a message may be responded to as a command.

This can’t interact with permissions as permissions is hyper-local with respect to command objects, create command objects for this if that’s needed.

This also does not check for prefix or command conflicts, as it is primarily designed for non-prefix based response handling via on_message_without_command

Parameters

message – The message object to check

Returns

Whether or not the message is eligible to be treated as a command.

Return type

bool

await pre_flight(cli_flags)[source]

This should only be run once, prior to connecting to discord.

await process_commands(message)[source]

Same as base method, but dispatches an additional event for cogs which want to handle normal messages differently to command messages, without the overhead of additional get_context calls per cog.

remove_before_invoke_hook(coro)[source]

Functional method to remove a before_invoke hook.

remove_cog(cogname)[source]

Removes a cog from the bot.

All registered commands and event listeners that the cog has registered will be removed as well.

If no cog is found then this method has no effect.

Parameters

name (str) – The name of the cog to remove.

remove_command(name)[source]

Remove a Command or subclasses from the internal list of commands.

This could also be used as a way to remove aliases.

Parameters

name (str) – The name of the command to remove.

Returns

The command that was removed. If the name is not valid then None is returned instead.

Return type

Command or subclass

remove_permissions_hook(hook)[source]

Remove a permissions hook.

Parameters are the same as those in add_permissions_hook.

Raises

ValueError – If the permissions hook has not been added.

await remove_shared_api_tokens(service_name, *token_names)[source]

Removes shared API tokens

Parameters
  • service_name (str) – The service to remove tokens for

  • *token_names (str) – The name of each token to be removed

Examples

Removing the api_key for youtube

>>> await ctx.bot.remove_shared_api_tokens("youtube", "api_key")
staticmethod await send_filtered(destination, filter_mass_mentions=True, filter_invite_links=True, filter_all_links=False, **kwargs)[source]

This is a convienience wrapper around

discord.abc.Messageable.send

It takes the destination you’d like to send to, which filters to apply (defaults on mass mentions, and invite links) and any other parameters normally accepted by destination.send

This should realistically only be used for responding using user provided input. (unfortunately, including usernames) Manually crafted messages which dont take any user input have no need of this

Returns

The message that was sent.

Return type

discord.Message

await send_help_for(ctx, help_for)[source]

Invokes Red’s helpformatter for a given context and object.

await send_to_owners(content=None, **kwargs)[source]

This sends something to all owners and their configured extra destinations.

This takes the same arguments as discord.abc.Messageable.send

This logs failing sends

await set_prefixes(prefixes, guild=None)[source]

Set global/server prefixes.

If guild is not provided (or None is passed), this will set the global prefixes.

Parameters
  • prefixes (List[str]) – The prefixes you want to set. Passing empty list will reset prefixes for the guild

  • guild (Optional[discord.Guild]) – The guild you want to set the prefixes for. Omit (or pass None) to set the global prefixes

Raises
  • TypeError – If prefixes is not a list of strings

  • ValueError – If empty list is passed to prefixes when setting global prefixes

await set_shared_api_tokens(service_name, **tokens)[source]

Sets shared API tokens for a service

In most cases, this should not be used. Users should instead be using the set api command

This will not clear existing values not specified.

Parameters
  • service_name (str) – The service to set tokens for

  • **tokens – token_name -> token

Examples

Setting the api_key for youtube from a value in a variable my_key

>>> await ctx.bot.set_shared_api_tokens("youtube", api_key=my_key)
await shutdown(*, restart=False)[source]

Gracefully quit Red.

The program will exit with code 0 by default.

Parameters

restart (bool) – If True, the program will exit with code 26. If the launcher sees this, it will attempt to restart the bot.

await start(*args, **kwargs)[source]

Overridden start which ensures cog load and other pre-connection tasks are handled

uptime

Allow access to the value, but we don’t want cog creators setting it

await verify_permissions_hooks(ctx)[source]

Run permissions hooks.

Parameters

ctx (commands.Context) – The context for the command being invoked.

Returns

False if any hooks returned False, True if any hooks return True and none returned False, None otherwise.

Return type

Optional[bool]

await wait_until_red_ready()[source]

Wait until our post connection startup is done.

Red

class redbot.core.bot.Red(*args, cli_flags=None, bot_dir=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/red-discordbot/checkouts/latest/docs'), **kwargs)[source]

Bases: redbot.core.bot.RedBase

Our subclass of discord.ext.commands.AutoShardedBot