Bot¶
RedBase¶
-
class
redbot.core.bot.
RedBase
(*args, cli_flags=None, bot_dir=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jack1142-red-prs/checkouts/stable/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.
-
add_command
(command)[source]¶ Adds a
Command
into the internal list of commands.This is usually not called, instead the
command()
orgroup()
shortcut decorators are used instead.Changed in version 1.4: Raise
CommandRegistrationError
instead of genericClientException
-
add_dev_env_value
(name, value)[source]¶ Add a custom variable to the dev environment (
[p]debug
,[p]eval
, and[p]repl
commands). If dev mode is disabled, nothing will happen.Example
class MyCog(commands.Cog): def __init__(self, bot): self.bot = bot bot.add_dev_env_value("mycog", lambda ctx: self) bot.add_dev_env_value("mycogdata", lambda ctx: self.settings[ctx.guild.id]) def cog_unload(self): self.bot.remove_dev_env_value("mycog") self.bot.remove_dev_env_value("mycogdata")
Once your cog is loaded, the custom variables
mycog
andmycogdata
will be included in the environment of dev commands.- Parameters
name (str) – The name of your custom variable.
value (Callable[[commands.Context], Any]) – The function returning the value of the variable. It must take a
commands.Context
as its sole parameter
- Raises
TypeError –
value
argument isn’t a callable.ValueError – The passed callable takes no or more than one argument.
RuntimeError – The name of the custom variable is either reserved by a variable from the default environment or already taken by some other custom variable.
-
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, andNone
to default to normal behaviour.- Parameters
hook – A command check predicate which returns
True
,False
orNone
.
-
await
allowed_by_whitelist_blacklist
(who=None, *, who_id=None, guild=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 caseIf 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 (Optional[discord.Guild]) – When used in conjunction with a provided value for
who_id
, checks the lists for the corresponding guild as well. This is ignored whenwho
is passed.guild_id (Optional[int]) – When used in conjunction with a provided value for
who_id
, checks the lists for the corresponding guild as well. This should not be used as it has unfixable bug that can cause it to raise an exception when the guild with the given ID couldn’t have been found. This is ignored whenwho
is passed.Will be deprecated in version 3.4.8, and removed in the first minor version that gets released after 30 days since deprecation: Use
guild
parameter instead.role_ids (Optional[List[int]]) – When used with both
who_id
andguild_id
, checks the role ids provided. This is required for accurate checking of members in a guild if providing ids. This is ignored whenwho
is passed.
- Raises
TypeError – Did not provide
who
orwho_id
- Returns
- Return type
-
await
before_identify_hook
(shard_id, *, initial=False)[source]¶ A hook that is called before IDENTIFYing a session. Same as in discord.py, but also dispatches “on_red_identify” bot event.
-
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
cog (commands.Cog) –
guild (Optional[discord.Guild]) –
- Returns
- Return type
-
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
-
await
embed_requested
(channel, user, command=None)[source]¶ Determine if an embed is requested for a response.
- Parameters
channel (
discord.abc.GuildChannel
ordiscord.abc.PrivateChannel
) – The channel to check embed settings for.user (
discord.abc.User
) – The user to check embed settings for.command (
commands.Command
, optional) – The command ran.
- Returns
True
if an embed is requested- Return type
-
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.- Returns
The cog that was requested. If not found, returns
None
.- Return type
Optional[
Cog
]
-
get_command
(name)[source]¶ Get a
Command
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 subcommandbar
of the group commandfoo
. If a subcommand is not found thenNone
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
Optional[
Command
]
-
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_or_fetch_member
(guild, member_id)[source]¶ Retrieves a
discord.Member
from a guild and a member ID.Warning
This method may make an API call if the user is not found in the bot cache. For general usage, consider
discord.Guild.get_member
instead.- Parameters
guild (discord.Guild) – The guild which the member should be retrieved from.
member_id (int) – The ID of the member that should be retrieved.
- Raises
Errors – Please refer to
discord.Guild.fetch_member
.- Returns
The user you requested.
- Return type
-
await
get_or_fetch_user
(user_id)[source]¶ Retrieves a
discord.User
based on their ID. You do not have to share any guilds with the user to get this information, however many operations do require that you do.Warning
This method may make an API call if the user is not found in the bot cache. For general usage, consider
bot.get_user
instead.- Parameters
user_id (int) – The ID of the user that should be retrieved.
- Raises
Errors – Please refer to
discord.Client.fetch_user
.- Returns
The user you requested.
- Return type
Gets the shared API tokens for a service, or all of them if no argument specified.
- Parameters
service_name (str, optional) – The service to get tokens for. Leave empty to get tokens for all services.
- Returns
A Mapping of token names to tokens. This mapping exists because some services have multiple tokens. If
service_name
isNone
, this method will return a mapping with mappings for all services.- Return type
-
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.
-
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
orcommands.Context
ordiscord.abc.User
ordiscord.Role
) – Something to check if it would be immune- Returns
True
if immune- Return type
-
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
-
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, thebot
.- 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 importfoo/test.py
.package (Optional[
str
]) –The package name to resolve relative imports with. This is required when loading an extension using a relative path, e.g
.foo.test
. Defaults toNone
.New in version 1.7.
- Raises
ExtensionNotFound – The extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided
package
parameter.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
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
-
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
from the internal list of commands.This could also be used as a way to remove aliases.
-
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.
Removes shared API services, as well as keys and tokens associated with them.
- Parameters
*service_names (str) – The services to remove.
Examples
Removing the youtube service
>>> await ctx.bot.remove_shared_api_services("youtube")
Removes shared API tokens
- Parameters
Examples
Removing the api_key for youtube
>>> await ctx.bot.remove_shared_api_tokens("youtube", "api_key")
-
reset_help_formatter
()[source]¶ Resets Red’s help formatter.
Warning
This method is provisional.
This exists for use in
cog_unload
for cogs which replace the formatter as well as for a rescue command in core_commands.
-
staticmethod await
send_filtered
(destination, filter_mass_mentions=True, filter_invite_links=True, filter_all_links=False, **kwargs)[source]¶ This is a convenience 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 don’t take any user input have no need of this
- Returns
The message that was sent.
- Return type
-
await
send_help_for
(ctx, help_for, *, from_help_command=False)[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
-
set_help_formatter
(formatter)[source]¶ Set’s Red’s help formatter.
Warning
This method is provisional.
The formatter must implement all methods in
commands.help.HelpFormatterABC
Cogs which set a help formatter should inform users of this. Users should not use multiple cogs which set a help formatter.
This should specifically be an instance of a formatter. This allows cogs to pass a config object or similar to the formatter prior to the bot using it.
See
commands.help.HelpFormatterABC
for more details.- Raises
RuntimeError – If the default formatter has already been replaced
TypeError – If given an invalid formatter
-
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 stringsValueError – If empty list is passed to
prefixes
when setting global prefixes
Sets shared API tokens for a service
In most cases, this should not be used. Users should instead be using the
set api
commandThis 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 code26
. 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 returnedFalse
,True
if any hooks returnTrue
and none returnedFalse
,None
otherwise.- Return type
Optional[bool]
-
Red¶
-
class
redbot.core.bot.
Red
(*args, cli_flags=None, bot_dir=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jack1142-red-prs/checkouts/stable/docs'), **kwargs)[source]¶ Bases:
redbot.core.bot.RedBase
Our subclass of discord.ext.commands.AutoShardedBot