Bot¶
RedBase¶
-
class
redbot.core.bot.
RedBase
(*args, cli_flags=None, bot_dir=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/edu-discordbot/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.
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.
- TypeError – The cog does not inherit from
-
add_command
(command)[source]¶ Adds a
Command
or its subclasses into the internal list of commands.This is usually not called, instead the
command()
orgroup()
shortcut decorators are used instead.Parameters: command (
Command
) – The command to add.Raises:
-
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_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 wellParameters: 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
andguild_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
orwho_id
Returns: Return type: - who_id (Optional[int]) – The id of the user or member to check
If not providing a value for
-
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
- guild_id (Optional[int]) – The guild ID to wipe permission overrides for. If
-
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 – (Optional) the command ran.
Returns: True
if an embed is requestedReturn type: - channel (
-
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 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: 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
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
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 of where the command is being run.) – Returns: True
if commands are allowed in the channel,False
otherwiseReturn type: bool
-
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 immuneReturns: True
if immuneReturn type: bool
-
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
-
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
.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
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.
Removes shared API tokens
Parameters: 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
- prefixes (List[str]) – The prefixes you want to set. Passing empty list will reset prefixes for the
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/edu-discordbot/checkouts/stable/docs'), **kwargs)[source]¶ Bases:
redbot.core.bot.RedBase
Our subclass of discord.ext.commands.AutoShardedBot