API Reference¶

CommandsClient¶

class CommandsClient(session, token, *, api_url='https://api.revolt.chat', max_messages=5000, bot=True, help_command=<Missing>, case_insensitive=False)¶

A subclass of Client which has support for commands.

Parameters:

session (ClientSession) – The aiohttp session to use for http request and the websocket
token (str) – The bots token
api_url (str) – The api url for the revolt instance you are connecting to, by default it uses the offical instance hosted at revolt.chat
max_messages (int) – The max amount of messages stored in the cache, by default this is 5k
bot (bool) – Denotes whether the account used is a bot account or user account, by default this it assumes a bot account
help_command (Optional[HelpCommand]) – Sets the custom help command, or remove it if passed None
case_insensitive (bool) – Whether or not commands should be case insensitive

add_cog(cog)¶

Adds a cog, this cog must subclass Cog.

Parameters:: cog (Cog) – The cog to be added

add_command(command)¶

Adds a command, this is typically only used for dynamic commands, you should use the commands.command decorator for most usecases.

Parameters:

name (str) – The name or alias of the command
command (Command) – The command to be added

property commands¶

Gets all commands registered

Returns:: The registered commands
Return type:: list[Command]

get_cog(name)¶

Gets a cog.

Parameters:: name (str) – The name of the cog to get
Returns:: The cog that was requested
Return type:: Cog

get_command(name)¶

Gets a command.

Parameters:: name (str) – The name or alias of the command
Returns:: The command with the name
Return type:: Command

get_context(message)¶

Returns the Context class to use, this can be overwritten to add extra features to context

Returns:: The context class to use
Return type:: type[Context]

get_extension(name)¶

Gets an extension.

Parameters:: name (str) – The name of the extension to get
Returns:: The extension that was requested
Return type:: ExtensionProtocol

async get_prefix(message)¶

Overwrite this function to set the prefix used for commands, this function is called for every message.

Parameters:: message (Message) – The message that was sent
Returns:: The prefix(s) for the commands
Return type:: Union[str, list[str]]

get_view(message)¶

Returns the StringView class to use, this can be overwritten to customize how arguments are parsed

Returns:: The string view class to use
Return type:: type[StringView]

async global_check(context)¶

A global check that stops commands from running on certain criteria.

Parameters:: context (Context) – The context for the invokation of the command
Return type:: bool represents if the command should run or not

load_extension(name)¶

Loads an extension, this takes a module name and runs the setup function inside of it.

Parameters:: name (str) – The name of the extension to be loaded

async process_commands(message)¶

Processes commands, if you overwrite Client.on_message you should manually call this function inside the event.

Parameters:: message (Message) – The message to process commands on
Returns:: The return of the command, if any
Return type:: Any

reload_extension(name)¶

Reloads an extension, this will unload and reload the extension.

Parameters:: name (str) – The name of the extension to be reloaded

remove_cog(cog_name)¶

Removes a cog.

Parameters:: cog_name (str) – The name of the cog to be removed
Returns:: The cog that was removed
Return type:: Cog

remove_command(name)¶

Removes a command.

Parameters:: name (str) – The name or alias of the command
Returns:: The command that was removed
Return type:: Optional[Command]

unload_extension(name)¶

Unloads an extension, this takes a module name and runs the teardown function inside of it.

Parameters:: name (str) – The name of the extension to be unloaded

Context¶

class Context(command, invoked_with, view, message, client)¶

Stores metadata the commands execution.

command¶

The command, this can be None when no command was found and the error handler is being executed

Type:: Optional[Command]

invoked_with¶

The command name that was used, this can be an alias, the commands name or a command that doesnt exist

Type:: str

message¶

The message that was sent to invoke the command

Type:: Message

channel¶

The channel the command was invoked in

Type:: Messageable

server_id¶

The server the command was invoked in

Type:: Optional[Server]

author¶

The user or member that invoked the commad, will be User in DMs

Type:: Union[Member, User]

args¶

The positional arguments being passed to the command

Type:: list[str]

kwargs¶

The keyword arguments being passed to the command

Type:: dict[str, Any]

client¶

The revolt client

Type:: CommandsClient

async can_run(command=None)¶: Runs all of the commands checks, and returns true if all of them pass

async invoke()¶

Invokes the command.

Note

If the command is None, this function will do nothing.

Parameters:: args (list[str]) – The args being passed to the command

property server¶

Server The server this context belongs too

Raises:: LookupError – Raises if the context is not from a server

Command¶

class Command(callback, name, *, aliases=None, usage=None, checks=None, cooldown=None, bucket=None, description=None, hidden=False)¶

Class for holding info about a command.

Parameters:

callback (Callable[..., Coroutine[Any, Any, Any]]) – The callback for the command
name (str) – The name of the command
aliases (list[str]) – The aliases of the command
parent (Optional[Group]) – The parent of the command if this command is a subcommand
cog (Optional[Cog]) – The cog the command is apart of.
usage (Optional[str]) – The usage string for the command
checks (Optional[list[Callable]]) – The list of checks the command has
cooldown (Optional[Cooldown]) – The cooldown for the command to restrict how often the command can be used
description (Optional[str]) – The commands description if it has one
hidden (bool) – Whether or not the command should be hidden from the help command

error(func)¶

Sets the error handler for the command.

Parameters:: func (Callable[..., Coroutine[Any, Any, Any]]) – The function for the error handler

Example

@mycommand.error
async def mycommand_error(self, ctx, error):
    await ctx.send(str(error))

get_usage()¶: Returns the usage string for the command.

async invoke(context, *args, **kwargs)¶

Runs the command and calls the error handler if the command errors.

Parameters:

context (Context) – The context for the command
args (list[str]) – The arguments for the command

property short_description¶: Returns the first line of the description or None if there is no description.

Group¶

class Group(callback, name, aliases)¶

Class for holding info about a group command.

Parameters:

callback (Callable[..., Coroutine[Any, Any, Any]]) – The callback for the group command
name (str) – The name of the command
aliases (list[str]) – The aliases of the group command
subcommands (dict[str, Command]) – The group’s subcommands.

add_command(command)¶

Adds a command, this is typically only used for dynamic commands, you should use the commands.command decorator for most usecases.

Parameters:

name (str) – The name or alias of the command
command (Command) – The command to be added

command(*, name=None, aliases=None, cls=revolt.ext.commands.command.Command[+ClientT_Co_D])¶

A decorator that turns a function into a Command and registers the command as a subcommand.

Parameters:

name (Optional[str]) – The name of the command, this defaults to the functions name
aliases (Optional[list[str]]) – The aliases of the command, defaults to no aliases
cls (type[Command]) – The class used for creating the command, this defaults to Command but can be used to use a custom command subclass

Returns:

A function that takes the command callback and returns a Command

Return type:

Callable[Callable[…, Coroutine], Command]

property commands¶

Gets all commands registered

Returns:: The registered commands
Return type:: list[Command]

get_command(name)¶

Gets a command.

Parameters:: name (str) – The name or alias of the command
Returns:: The command with the name
Return type:: Command

group(*, name=None, aliases=None, cls=None)¶

A decorator that turns a function into a Group and registers the command as a subcommand

Parameters:

name (Optional[str]) – The name of the group command, this defaults to the functions name
aliases (Optional[list[str]]) – The aliases of the group command, defaults to no aliases
cls (type[Group]) – The class used for creating the command, this defaults to Group but can be used to use a custom group subclass

Returns:

A function that takes the command callback and returns a Group

Return type:

Callable[Callable[…, Coroutine], Group]

remove_command(name)¶

Removes a command.

Parameters:: name (str) – The name or alias of the command
Returns:: The command that was removed
Return type:: Optional[Command]

Cog¶

class Cog¶

cog_load()¶: A special method that is called when the cog gets loaded.

cog_unload()¶: A special method that is called when the cog gets removed.

command¶

@command(*, name=None, aliases=None, cls=<class 'revolt.ext.commands.command.Command'>, usage=None)¶

A decorator that turns a function into a Command.n

Parameters:

name (Optional[str]) – The name of the command, this defaults to the functions name
aliases (Optional[list[str]]) – The aliases of the command, defaults to no aliases
cls (type[Command]) – The class used for creating the command, this defaults to Command but can be used to use a custom command subclass
usage (Optional[str]) – The signature for how the command should be called

Returns:

A function that takes the command callback and returns a Command

Return type:

Callable[Callable[…, Coroutine], Command]

group¶

@group(*, name=None, aliases=None, cls=<class 'revolt.ext.commands.group.Group'>)¶

A decorator that turns a function into a Group

Parameters:

name (Optional[str]) – The name of the group command, this defaults to the functions name
aliases (Optional[list[str]]) – The aliases of the group command, defaults to no aliases
cls (type[Group]) – The class used for creating the command, this defaults to Group but can be used to use a custom group subclass

Returns:

A function that takes the command callback and returns a Group

Return type:

Callable[Callable[…, Coroutine], Group]

Checks¶

check¶

@check¶

A decorator for adding command checks

Parameters:: check (Callable[[Context], Union[Any, Coroutine[Any, Any, Any]]]) – The function to be called, must take one parameter, context and optionally be a coroutine, the return value denoating whether the check should pass or fail

is_bot_owner¶

@is_bot_owner¶: A command check for limiting the command to only the bot’s owner

is_server_owner¶

@is_server_owner¶: A command check for limiting the command to only a server’s owner

has_permissions¶

@has_permissions¶

has_channel_permissions¶

@has_channel_permissions¶

Converters¶

IntConverter¶

Converts the parameter to an int

BoolConverter¶

Converts the parameter to a bool

CategoryConverter¶

Converts the parameter to a category

UserConverter¶

Converts the parameter to a category

MemberConverter¶

Converts the parameter to a category

ChannelConverter¶

Converts the parameter to a category

Greedy¶

Converts the parameter to a greedy parameter which will take as many arguments which convert successfully.

Allows you to have var-args in the middle of a signature.

Help Commands¶

HelpCommand¶

class HelpCommand¶

DefaultHelpCommand¶

class DefaultHelpCommand(default_cog_name='No Cog')¶

Exceptions¶

CommandError¶

exception CommandError¶: base error for all command’s related errors

CommandNotFound¶

exception CommandNotFound(command_name)¶

Raised when a command isnt found.

Parameters:: command_name (str) – The name of the command that wasnt found

NoClosingQuote¶

exception NoClosingQuote¶: Raised when there is no closing quote for a command argument

CheckError¶

exception CheckError¶: Raised when a check fails for a command

NotBotOwner¶

exception NotBotOwner¶: Raised when the is_bot_owner check fails

NotServerOwner¶

exception NotServerOwner¶: Raised when the is_server_owner check fails

ServerOnly¶

exception ServerOnly¶: Raised when a check requires the command to be ran in a server

MissingPermissionsError¶

exception MissingPermissionsError(permissions)¶

Raised when a check requires permissions the user does not have

permissions¶

The permissions which the user did not have

Type:: dict[str, bool]

ConverterError¶

exception ConverterError¶: Base class for all converter errors

InvalidLiteralArgument¶

exception InvalidLiteralArgument¶: Raised when the argument is not a valid literal argument

BadBoolArgument¶

exception BadBoolArgument¶: Raised when the bool converter fails

CategoryConverterError¶

exception CategoryConverterError(argument)¶: Raised when the Category conveter fails

ChannelConverterError¶

exception ChannelConverterError(argument)¶: Raised when the Channel conveter fails

UserConverterError¶

exception UserConverterError(argument)¶: Raised when the Category conveter fails

MemberConverterError¶

exception MemberConverterError(argument)¶: Raised when the Category conveter fails

UnionConverterError¶

exception UnionConverterError(argument)¶: Raised when all converters in a union fails

MissingSetup¶

exception MissingSetup¶: Raised when an extension is missing the setup function

CommandOnCooldown¶

exception CommandOnCooldown(retry_after)¶

Raised when a command is on cooldown

retry_after¶

How long the user must wait until the cooldown resets

Type:: float