API Reference¶

The following section outlines the API of guilded.py’s command extension.

Bots¶

Bot¶

class guilded.ext.commands.Bot(command_prefix, *, help_command=<default-help-command>, description=None, owner_id=None, owner_ids=None, **options)¶

A Guilded bot with commands.

This is a subclass of Client, and thus it implements all the functionality of Client but comes with commands-related features.

Parameters

internal_server_id (Optional[str]) – The ID of the bot’s internal server.
command_prefix (Union[list, str]) – The command prefix or list of command prefixes to listen for.
description (Optional[str]) – A description of this bot. Will show up in the default help command, when it is created.
owner_id (Optional[str]) – The user’s ID who owns this bot. Used for the is_owner() decorator. Must not be specified with owner_ids.
owner_ids (Optional[List[str]]) – The users’ IDs who own this bot. Used for the is_owner() decorator. Must not be specified with owner_id.
max_messages (Optional[int]) – The maximum number of messages to store in the internal message cache. This defaults to 1000. Passing in None disables the message cache.
loop (Optional[asyncio.AbstractEventLoop]) – The asyncio.AbstractEventLoop to use for asynchronous operations. Defaults to None, in which case the default event loop is used via asyncio.get_event_loop().

command_prefix¶

The command prefix or list of command prefixes to listen for.

Type: Union[list, str]

commands¶

A list of all the Command s registered to this bot.

Type: list

description¶

A description of this bot.

Type: Optional[str]

owner_id¶

The user’s ID who owns this bot.

Type: Optional[str]

owner_ids¶

The users’ IDs who own this bot.

Type: Optional[List[str]]

loop¶

The event loop that the client uses for HTTP requests and websocket operations.

Type: asyncio.AbstractEventLoop

ws¶

The websocket gateway the client is currently connected to. Could be None.

Type: Optional[GuildedWebsocket]

add_cog(cog, *, override=False)¶

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.
override (bool) – If a previously loaded cog with the same name should be ejected instead of raising an error.

Raises

TypeError – The cog does not inherit from Cog.
CommandError – An error happened during loading.
.ClientException – A cog with the same name is already loaded.

add_command(command)¶

Add a Command to the internal list of commands.

Parameters: command (Command) – The command to register.
Raises: CommandRegistrationError – This command has a duplicate name or alias to one that is already registered.

property cached_messages¶

The list of cached messages that the client has seen recently.

Type: List[ChatMessage]

await close()¶

This function is a coroutine.

Close the current connection.

property cogs¶

A read-only mapping of cog name to cog.

Type: Mapping[str, Cog]

property dm_channels¶

The private/DM channels that the client can see.

Type: List[DMChannel]

property emotes¶

The list of emotes that the client can see.

Type: List[Emote]

event(coro)¶

A decorator to register an event for the library to automatically dispatch when appropriate.

You can find more info about the events on the documentation below.

The events must be a coroutine, if not, TypeError is raised.

Example

@client.event
async def on_ready():
    print('Ready!')

Raises: TypeError – The function passed is not actually a coroutine.

property extensions¶

A read-only mapping of extension name to extension.

Type: Mapping[str, types.ModuleType]

await fetch_channel(channel_id)¶

This function is a coroutine.

Fetch a channel from the API.

Returns: The channel from the ID.
Return type: ServerChannel

await fetch_invite(invite_id)¶

This function is a coroutine.

Fetch an invite from the API.

Note

This method does not support vanity invites or full URLs.

Returns: The invite from the ID.
Return type: Invite

await fetch_public_server(server_id, /)¶

This function is a coroutine.

Fetch a public server from the API.

The client does not need to be a member of the server to use this method, but the server must have “Discoverable” enabled in its privacy settings.

This method will be limiting for you if you are a member of the server and are permitted to see non-public information. If this is the case, use fetch_server() instead.

Returns: The server from the ID.
Return type: Server
Raises: NotFound – The server does not exist or it is private.

await fetch_server(server_id, /)¶

This function is a coroutine.

Fetch a server from the API.

Returns: The server from the ID.
Return type: Server

await fetch_servers()¶

This function is a coroutine.

Fetch your list of servers from the API.

New in version 1.8.

Returns: The servers you are a member of.
Return type: List[Server]

await fetch_user(user_id, /)¶

This function is a coroutine.

Fetch a user from the API.

Returns: The user from the ID.
Return type: User

for ... in get_all_channels()¶

A generator that retrieves every ServerChannel the client can see.

This is equivalent to:

for server in client.servers:
    for channel in server.channels:
        yield channel

Yields: ServerChannel – A channel the client can see.

for ... in get_all_members()¶

Returns a generator yielding every Member that the client can see.

This is equivalent to:

for server in client.servers:
    for member in server.members:
        yield member

Yields: Member – A member the client can see.

get_channel(channel_id, /)¶: Optional[ServerChannel]: Get a server channel or DM channel from your channels.

get_cog(name)¶

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)¶

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 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: Optional[Command]

get_emote(emote_id, /)¶: Optional[Emote]: Get an emote from your emotes.

get_message(message_id, /)¶

Optional[ChatMessage]: Get a message from your cached_messages.

As messages frequently enter and exit cache, you generally should not rely on this method. Instead, use abc.Messageable.fetch_message().

get_partial_messageable(id, *, server_id=None, group_id=None, type=None, guild_id=None)¶

Returns a partial messageable with the given channel ID.

This is useful if you have a channel ID but don’t want to do an API call to send messages to it.

New in version 1.4.

Parameters

id (str) – The channel ID to create a partial messageable for.
server_id (Optional[str]) – The server ID that the channel is in. This is not required to send messages, but it is necessary for the jump_url and server properties to work properly.
group_id (Optional[str]) – The group ID that the channel is in. This is not required to send messages, but when combined with server_id, it helps the jump_url property to render properly in the client, and it allows the group property to work properly.
type (Optional[ChannelType]) – The underlying channel type for the partial messageable. This does not have to be a messageable type, but Guilded will reject the request if you attempt to send to a non-messageable channel.

Returns

The partial messageable that was created.

Return type

PartialMessageable

Raises

ValueError – Cannot provide both server_id and guild_id

await get_prefix(message, /)¶

This function is a coroutine.

Retrieves the prefix the bot is listening to with the message as a context.

Parameters: message (Message) – The message context to get the prefix of.
Returns: A list of prefixes or a single prefix that the bot is listening for.
Return type: Union[List[str], str]

get_server(server_id, /)¶: Optional[Server]: Get a server from your servers.

get_user(user_id, /)¶: Optional[User]: Get a user from your users.

await getch_channel(channel_id)¶

This function is a coroutine.

Try to get a channel from internal cache, and if not found, try to fetch from the API.

Returns: The channel from the ID.
Return type: ServerChannel

await getch_server(server_id, /)¶

This function is a coroutine.

Try to get a server from internal cache, and if not found, try to fetch from the API.

Returns: The server from the ID.
Return type: Server

await getch_user(user_id, /)¶

This function is a coroutine.

Try to get a user from internal cache, and if not found, try to fetch from the API.

Returns: The user from the ID.
Return type: User

property guilds¶

This exists for compatibility with discord.py bots. It may be removed in a later version.

This is an alias of servers.

The list of servers that the client can see.

Type: List[Server]

await is_owner(user)¶

This function is a coroutine.

Checks if a User or Member is the owner of this bot. If an owner_id or owner_ids are not set, this function will always return False, unless the user provided is the bot itself.

Parameters: user (abc.User) – The user to check for.
Returns: Whether the user is the owner.
Return type: bool

load_extension(name, *, package=None)¶

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.
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 to None.

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 on_command_error(context, exception)¶

This function is a coroutine.

The default command error handler provided by the bot.

By default this prints to sys.stderr however it could be overridden to have a different implementation.

This only fires if you do not specify any listeners for command error.

await on_message(event)¶

This function is a coroutine.

The default handler for on_message() provided by the bot.

If you are overriding this, remember to call process_commands() or all commands will be ignored.

property private_channels¶

This exists for compatibility with discord.py bots. It may be removed in a later version.

This is an alias of dm_channels.

The private/DM channels that the client can see.

Type: List[DMChannel]

await process_commands(message)¶

This function is a coroutine.

This function processes the commands that have been registered to the bot and other groups. Without this coroutine, no commands will be triggered.

By default, this coroutine is called inside the on_message() event. If you choose to override the on_message() event, then you should invoke this coroutine as well.

This is built using other low level tools, and is equivalent to a call to get_context() followed by a call to invoke().

This also checks if the message’s author is a bot and doesn’t call get_context() or invoke() if so.

Parameters: message (ChatMessage) – The message to process commands for.

reload_extension(name, *, package=None)¶

Atomically reloads an extension.

This replaces the extension with the same extension, only refreshed. This is equivalent to a unload_extension() followed by a load_extension() except done in an atomic way. That is, if an operation fails mid-reload then the bot will roll-back to the prior working state.

Parameters

name (str) – The extension name to reload. 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.
package (Optional[str]) – The package name to resolve relative imports with. This is required when reloading an extension using a relative path, e.g .foo.test. Defaults to None.

Raises

ExtensionNotLoaded – The extension was not loaded.
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.
NoEntryPointError – The extension does not have a setup function.
ExtensionFailed – The extension setup function had an execution error.

remove_cog(name)¶

Removes a cog from the bot and returns it.

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.
Returns: The cog that was removed. None if not found.
Return type: Optional[Cog]

remove_command(name)¶

Remove a Command 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: Optional[Command]

await remove_status()¶

This function is a coroutine.

Remove your custom status.

run(token, *, reconnect=True)¶

Connect to Guilded’s gateway and start the event loop. This is a blocking call; nothing after it will be called until the bot has been closed.

Parameters

token (str) – The bot’s auth token.
reconnect (Optional[bool]) – Whether to reconnect on loss/interruption of gateway connection.

property servers¶

The list of servers that the client can see.

Type: List[Server]

await set_status(emote, *, content=...)¶

This function is a coroutine.

Update your custom status.

This method cannot be used to remove your status. Instead, use remove_status().

Parameters

emote (Emote) –
The emote displayed to the left of the content.

Note

Perhaps unexpectedly, this parameter is required by Guilded. If you do not wish to provide it, 90002547 is the default emote ID used by the desktop client.
content (Optional[str]) – The text content of the status.

await setup_hook()¶

This function is a coroutine.

A coroutine to be called to setup the bot, by default this is blank. To perform asynchronous setup after the bot is logged in but before it has connected to the Websocket, overwrite this method.

This is only called once, in login(), and will be called before any events are dispatched, making it a better solution than doing such setup in the on_ready() event.

Warning

Since this is called before the websocket connection is made therefore anything that waits for the websocket will deadlock, this includes things like wait_for() and wait_until_ready().

unload_extension(name, *, package=None)¶

Unloads an extension.

When the extension is unloaded, all commands, listeners, and cogs are removed from the bot and the module is un-imported.

The extension can provide an optional global function, teardown, to do miscellaneous clean-up if necessary. This function takes a single parameter, the bot, similar to setup from load_extension().

Parameters

name (str) – The extension name to unload. 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.
package (Optional[str]) – The package name to resolve relative imports with. This is required when unloading an extension using a relative path, e.g .foo.test. Defaults to None.

Raises

ExtensionNotFound – The name of the extension could not be resolved using the provided package parameter.
ExtensionNotLoaded – The extension was not loaded.

property user¶

The in-Guilded user data of the client. None if not logged in.

Type: Optional[ClientUser]

property users¶

The list of users that the client can see. A user is not the same as a member, which is a server-specific representation. To get all members, use get_all_members().

Type: List[User]

wait_for(event, *, check=None, timeout=None)¶

This function is a coroutine.

Waits for a WebSocket event to be dispatched.

This could be used to wait for a user to reply to a message, or to react to a message, or to edit a message in a self-contained way.

The timeout parameter is passed onto asyncio.wait_for(). By default, it does not timeout. Note that this does propagate the asyncio.TimeoutError for you in case of timeout and is provided for ease of use.

In case the event returns multiple arguments, a tuple containing those arguments is returned instead. Please check the documentation for a list of events and their parameters.

This function returns the first event that meets the requirements.

Examples

Waiting for a user reply:

@client.event
async def on_message(message):
    if message.content.startswith('$greet'):
        channel = message.channel
        await channel.send('Say hello!')

        def check(m):
            return m.content == 'hello' and m.channel == channel

        msg = await client.wait_for('message', check=check)
        await channel.send(f'Hello {msg.author}!')

Waiting for a thumbs up reaction from the message author:

@client.event
async def on_message(message):
    if message.content.startswith('$thumb'):
        channel = message.channel
        await channel.send('Send me that 👍 reaction, mate')

        def check(reaction):
            return reaction.user == message.author and reaction.emote.id == 90001164  # https://gist.github.com/shayypy/8e492ad2d8801bfd38415986f68a547e

        try:
            reaction = await client.wait_for('message_reaction_add', timeout=60.0, check=check)
        except asyncio.TimeoutError:
            await channel.send('👎')
        else:
            await channel.send('👍')

Parameters

event (str) – The event name, similar to the event reference, but without the on_ prefix, to wait for.
check (Optional[Callable[…, bool]]) – A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for.
timeout (Optional[float]) – The number of seconds to wait before timing out and raising asyncio.TimeoutError.

Raises

asyncio.TimeoutError – If a timeout is provided and it was reached.

Returns

Returns no arguments, a single argument, or a tuple of multiple arguments that mirrors the parameters passed in the event reference.

Return type

Any

await wait_until_ready()¶

This function is a coroutine.

Waits until the client’s internal cache is all ready.

Event Reference¶

Events detailed here are exclusive to the commands extension.

guilded.ext.commands.on_command_error(ctx, error)¶

An error was raised while executing a command - be it user input error or an error in the command function itself.

Parameters

ctx (Context) – The invocation context.
error (Inherited from CommandError) – The error that was raised.

guilded.ext.commands.on_command(ctx)¶

A command was executed in chat. This event is called before the command function, and is thus agnostic to whether or not the command completed successfully.

Parameters: ctx (Context) – The invocation context.

guilded.ext.commands.on_command_completion(ctx)¶

A command finished execution with no errors.

Parameters: ctx (Context) – The invocation context.

Commands¶

Decorators¶

guilded.ext.commands.command(name=None, cls=<class 'guilded.ext.commands.core.Command'>, **kwargs)¶

A decorator that transforms a function into a Command or if called with group(), Group.

By default the help attribute is received automatically from the docstring of the function and is cleaned up with the use of inspect.cleandoc. If the docstring is bytes, then it is decoded into str using utf-8 encoding.

All checks added using the check() & co. decorators are added into the function. There is no way to supply your own checks through this decorator.

Parameters

name (str) – The name to create the command with. By default this uses the function name unchanged.
cls – The class to construct with. By default this is Command. You usually do not change this.
attrs – Keyword arguments to pass into the construction of the class denoted by cls.

Raises

TypeError – If the function is not a coroutine or is already a command.

guilded.ext.commands.group(name=None, cls=<class 'guilded.ext.commands.core.Group'>, **kwargs)¶

A decorator that transforms a function into a Group.

This is similar to the command() decorator but the cls parameter is set to Group by default.

Command¶

class guilded.ext.commands.Command(*args, **kwargs)¶

property full_parent_name¶

Retrieves the fully qualified parent command name.

This the base command name required to execute it. For example, in ?one two three the parent name would be one two.

Type: str

property parents¶

Retrieves the parents of this command.

If the command has no parents then it returns an empty list.

For example in commands ?a b c test, the parents are [c, b, a].

Type: List[Group]

property root_parent¶

Retrieves the root parent of this command.

If the command has no parents then it returns None.

For example in commands ?a b c test, the root parent is a.

Type: Optional[Group]

property qualified_name¶

Retrieves the fully qualified command name.

This is the full parent name with the command name as well. For example, in ?one two three the qualified name would be one two three.

Type: str

property short_doc¶

Gets the “short” documentation of a command.

By default, this is the brief attribute. If that lookup leads to an empty string then the first line of the help attribute is used instead.

Type: str

property signature¶

Returns a POSIX-like signature useful for help command output.

Type: str

property clean_params¶

Dict[str, inspect.Parameter]: Retrieves the parameter dictionary without the context or self parameters.

Useful for inspecting signature.

property cooldown¶

The cooldown of a command when invoked or None if the command doesn’t have a registered cooldown.

New in version 1.5.

Type: Optional[Cooldown]

copy()¶

Creates a copy of this command.

Returns: A new instance of this command.
Return type: Command

is_on_cooldown(ctx, /)¶

Checks whether the command is currently on cooldown.

New in version 1.5.

Parameters: ctx (Context) – The invocation context to use when checking the command’s cooldown status.
Returns: A boolean indicating if the command is on cooldown.
Return type: bool

reset_cooldown(ctx, /)¶

Resets the cooldown on this command.

New in version 1.5.

Parameters: ctx (Context) – The invocation context to reset the cooldown under.

get_cooldown_retry_after(ctx, /)¶

Retrieves the amount of seconds before this command can be tried again.

New in version 1.5.

Parameters: ctx (Context) – The invocation context to retrieve the cooldown from.
Returns: The amount of time left on this command’s cooldown in seconds. If this is 0.0 then the command isn’t on cooldown.
Return type: float

before_invoke(coro)¶

A decorator that registers a coroutine as a pre-invoke hook.

A pre-invoke hook is called directly before the command is called. This makes it a useful function to set up database connections or any type of set up required.

This pre-invoke hook takes a sole parameter, a Context.

See Bot.before_invoke() for more info.

Parameters: coro (coroutine) – The coroutine to register as the pre-invoke hook.
Raises: TypeError – The coroutine passed is not actually a coroutine.

after_invoke(coro)¶

A decorator that registers a coroutine as a post-invoke hook.

A post-invoke hook is called directly after the command is called. This makes it a useful function to clean-up database connections or any type of clean up required.

This post-invoke hook takes a sole parameter, a Context.

See Bot.after_invoke() for more info.

Parameters: coro (coroutine) – The coroutine to register as the post-invoke hook.
Raises: TypeError – The coroutine passed is not actually a coroutine.

await can_run(ctx)¶

This function is a coroutine.

Checks if the command can be executed by checking all the predicates inside the checks attribute. This also checks whether the command is disabled.

Parameters: ctx (Context) – The ctx of the command currently being invoked.
Raises: CommandError – Any command error that was raised during a check call will be propagated by this function.
Returns: A boolean indicating if the command can be invoked.
Return type: bool

Group¶

class guilded.ext.commands.Group(*args, **kwargs)¶

all_commands¶

A class that implements a grouping protocol for commands to be executed as subcommands.

This class is a subclass of Command and thus all options valid for Command are valid for this as well.

invoke_without_command¶

Indicates if the group callback should begin parsing and invocation only if no subcommand was found. Useful for making it an error handling function to tell the user that no subcommand was found or to have different functionality in case no subcommand was found. If this is False, then the group callback will always be invoked first. This means that the checks and the parsing dictated by its parameters will be executed. Defaults to False.

Type: bool

case_insensitive¶

Indicates if the group’s commands should be case insensitive. Defaults to False.

Type: bool

property commands¶

A unique set of commands without aliases that are registered.

Type: Set[Command]

copy()¶

Creates a copy of this Group.

Returns: The copied instance of this group.
Return type: Group

add_command(command)¶

Adds a Command 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

.CommandRegistrationError – If the command or its alias is already registered by different command.
TypeError – If the command passed is not a subclass of Command.

remove_command(name)¶

Remove a Command 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: Optional[Command]

for ... in walk_commands()¶

An iterator that recursively walks through all commands and subcommands.

Yields: Union[Command, Group] – A command or group from the internal list of commands.

get_command(name)¶

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 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: Optional[Command]

command(name=None, cls=<class 'guilded.ext.commands.core.Command'>, *args, **kwargs)¶

A shortcut decorator that invokes command() and adds it to the internal command list via add_command().

Returns: A decorator that converts the provided method into a Command, adds it to the bot, then returns it.
Return type: Callable[…, Command]

group(name=None, cls=None, *args, **kwargs)¶

A shortcut decorator that invokes group() and adds it to the internal command list via add_command().

Returns: A decorator that converts the provided method into a Group, adds it to the bot, then returns it.
Return type: Callable[…, Group]

Cogs¶

Cog¶

class guilded.ext.commands.Cog(*args, **kwargs)¶

The base class that all cogs must inherit from.

A cog is a collection of commands, listeners, and optional state to help group commands together. More information on them can be found on the Cogs page.

When inheriting from this class, the options shown in CogMeta are equally valid here.

get_commands()¶

Returns

A list of Commands that are defined inside this cog.

Note

This does not include subcommands.

Return type

List[Command]

property qualified_name¶

Returns the cog’s specified name, not the class name.

Type: str

property description¶

Returns the cog’s description, typically the cleaned docstring.

Type: str

for ... in walk_commands()¶

An iterator that recursively walks through this cog’s commands and subcommands.

Yields: Union[Command, Group] – A command or group from the cog.

get_listeners()¶

Returns a list of (name, function) listener pairs that are defined in this cog.

Returns: The listeners defined in this cog.
Return type: List[Tuple[str, coroutine]]

classmethod listener(name=None)¶

A decorator that marks a function as a listener.

This is the cog equivalent of Bot.listen().

Parameters: name (str) – The name of the event being listened to. If not provided, it defaults to the function’s name.
Raises: TypeError – The function is not a coroutine function or a string was not passed as the name.

has_error_handler()¶: bool: Checks whether the cog has an error handler.

cog_unload()¶

A special method that is called when the cog gets removed.

This function cannot be a coroutine. It must be a regular function.

Subclasses must replace this if they want special unloading behaviour.

bot_check_once(ctx)¶

A special method that registers as a Bot.check_once() check.

This function can be a coroutine and must take a sole parameter, ctx, to represent the Context.

bot_check(ctx)¶

A special method that registers as a Bot.check() check.

This function can be a coroutine and must take a sole parameter, ctx, to represent the Context.

cog_check(ctx)¶

A special method that registers as a check() for every command and subcommand in this cog.

This function can be a coroutine and must take a sole parameter, ctx, to represent the Context.

await cog_command_error(ctx, error)¶

A special method that is called whenever an error is dispatched inside this cog.

This is similar to on_command_error() except only applying to the commands inside this cog.

This must be a coroutine.

Parameters

ctx (Context) – The invocation context where the error happened.
error (CommandError) – The error that happened.

await cog_before_invoke(ctx)¶

A special method that acts as a cog local pre-invoke hook.

This is similar to Command.before_invoke().

This must be a coroutine.

Parameters: ctx (Context) – The invocation context.

await cog_after_invoke(ctx)¶

A special method that acts as a cog local post-invoke hook.

This is similar to Command.after_invoke().

This must be a coroutine.

Parameters: ctx (Context) – The invocation context.

CogMeta¶

class guilded.ext.commands.CogMeta(*args, **kwargs)¶

A metaclass for defining a cog.

Note that you should probably not use this directly. It is exposed purely for documentation purposes along with making custom metaclasses to intermix with other metaclasses such as the abc.ABCMeta metaclass.

For example, to create an abstract cog mixin class, the following would be done.

import abc

class CogABCMeta(commands.CogMeta, abc.ABCMeta):
    pass

class SomeMixin(metaclass=abc.ABCMeta):
    pass

class SomeCogMixin(SomeMixin, commands.Cog, metaclass=CogABCMeta):
    pass

Note

When passing an attribute of a metaclass that is documented below, note that you must pass it as a keyword-only argument to the class creation like the following example:

class MyCog(commands.Cog, name='My Cog'):
    pass

name¶

The cog name. By default, it is the name of the class with no modification.

Type: str

description¶

The cog description. By default, it is the cleaned docstring of the class.

Type: str

command_attrs¶

A list of attributes to apply to every command inside this cog. The dictionary is passed into the Command options at __init__. If you specify attributes inside the command attribute in the class, it will override the one specified inside this attribute. For example:

class MyCog(commands.Cog, command_attrs=dict(hidden=True)):
    @commands.command()
    async def foo(self, ctx):
        pass # hidden -> True

    @commands.command(hidden=False)
    async def bar(self, ctx):
        pass # hidden -> False

Type: dict

Help Commands¶

HelpCommand¶

class guilded.ext.commands.HelpCommand(*args, **kwargs)¶

The base implementation for help command formatting.

Note

Internally instances of this class are deep copied every time the command itself is invoked to prevent a race condition mentioned in Rapptz/discord.py#2123.

This means that relying on the state of this class to be the same between command invocations would not work as expected.

context¶

The context that invoked this help formatter. This is generally set after the help command assigned, command_callback(), has been called.

Type: Optional[Context]

show_hidden¶

Specifies if hidden commands should be shown in the output. Defaults to False.

Type: bool

verify_checks¶

Specifies if commands should have their Command.checks called and verified. If True, always calls Command.checks. If None, only calls Command.checks in a guild setting. If False, never calls Command.checks. Defaults to True.

Type: Optional[bool]

command_attrs¶

A dictionary of options to pass in for the construction of the help command. This allows you to change the command behaviour without actually changing the implementation of the command. The attributes will be the same as the ones passed in the Command constructor.

Type: dict

add_check(func)¶

Adds a check to the help command.

Parameters: func – The function that will be used as a check.

remove_check(func)¶

Removes a check from the help command.

This function is idempotent and will not raise an exception if the function is not in the command’s checks.

Parameters: func – The function to remove from the checks.

get_bot_mapping()¶: Retrieves the bot mapping passed to send_bot_help().

property invoked_with¶

Similar to Context.invoked_with except properly handles the case where Context.send_help() is used.

If the help command was used regularly then this returns the Context.invoked_with attribute. Otherwise, if it the help command was called using Context.send_help() then it returns the internal command name of the help command.

Returns: The command name that triggered this invocation.
Return type: str

get_command_signature(command)¶

Retrieves the signature portion of the help page.

Parameters: command (Command) – The command to get the signature of.
Returns: The signature for the command.
Return type: str

remove_mentions(string)¶

Removes mentions from the string to prevent abuse.

This includes @everyone, @here, member mentions and role mentions.

Returns: The string with mentions removed.
Return type: str

property cog¶

A property for retrieving or setting the cog for the help command.

When a cog is set for the help command, it is as-if the help command belongs to that cog. All cog special methods will apply to the help command and it will be automatically unset on unload.

To unbind the cog from the help command, you can set it to None.

Returns: The cog that is currently set for the help command.
Return type: Optional[Cog]

command_not_found(string)¶

This function could be a coroutine.

A method called when a command is not found in the help command. This is useful to override for i18n.

Defaults to No command called {0} found.

Parameters: string (str) – The string that contains the invalid command. Note that this has had mentions removed to prevent abuse.
Returns: The string to use when a command has not been found.
Return type: str

subcommand_not_found(command, string)¶

This function could be a coroutine.

A method called when a command did not have a subcommand requested in the help command. This is useful to override for i18n.

Defaults to either:

'Command "{command.qualified_name}" has no subcommands.'
- If there is no subcommand in the command parameter.
'Command "{command.qualified_name}" has no subcommand named {string}'
- If the command parameter has subcommands but not one named string.

Parameters

command (Command) – The command that did not have the subcommand requested.
string (str) – The string that contains the invalid subcommand. Note that this has had mentions removed to prevent abuse.

Returns

The string to use when the command did not have the subcommand requested.

Return type

str

await filter_commands(commands, *, sort=False, key=None)¶

This function is a coroutine.

Returns a filtered list of commands and optionally sorts them.

This takes into account the verify_checks and show_hidden attributes.

Parameters

commands (Iterable[Command]) – An iterable of commands that are getting filtered.
sort (bool) – Whether to sort the result.
key (Optional[Callable[Command, Any]]) – An optional key function to pass to sorted() that takes a Command as its sole parameter. If sort is passed as True then this will default as the command name.

Returns

A list of commands that passed the filter.

Return type

List[Command]

get_max_size(commands)¶

Returns the largest name length of the specified command list.

Parameters: commands (Sequence[Command]) – A sequence of commands to check for the largest size.
Returns: The maximum width of the commands.
Return type: int

get_destination()¶

Returns the Messageable where the help command will be output.

You can override this method to customise the behaviour.

By default this returns the context’s channel.

Returns: The destination where the help command will be output.
Return type: abc.Messageable

await send_error_message(error)¶

This function is a coroutine.

Handles the implementation when an error happens in the help command. For example, the result of command_not_found() will be passed here.

You can override this method to customise the behaviour.

By default, this sends the error message to the destination specified by get_destination().

Note

You can access the invocation context with HelpCommand.context.

Parameters: error (str) – The error message to display to the user. Note that this has had mentions removed to prevent abuse.

await on_help_command_error(ctx, error)¶

This function is a coroutine.

The help command’s error handler, as specified by Error Handling.

Useful to override if you need some specific behaviour when the error handler is called.

By default this method does nothing and just propagates to the default error handlers.

Parameters

ctx (Context) – The invocation context.
error (CommandError) – The error that was raised.

await send_bot_help(mapping)¶

This function is a coroutine.

Handles the implementation of the bot command page in the help command. This function is called when the help command is called with no arguments.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

Also, the commands in the mapping are not filtered. To do the filtering you will have to call filter_commands() yourself.

Parameters: mapping (Mapping[Optional[Cog], List[Command]]) – A mapping of cogs to commands that have been requested by the user for help. The key of the mapping is the Cog that the command belongs to, or None if there isn’t one, and the value is a list of commands that belongs to that cog.

await send_cog_help(cog)¶

This function is a coroutine.

Handles the implementation of the cog page in the help command. This function is called when the help command is called with a cog as the argument.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

To get the commands that belong to this cog see Cog.get_commands(). The commands returned not filtered. To do the filtering you will have to call filter_commands() yourself.

Parameters: cog (Cog) – The cog that was requested for help.

await send_group_help(group)¶

This function is a coroutine.

Handles the implementation of the group page in the help command. This function is called when the help command is called with a group as the argument.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

To get the commands that belong to this group without aliases see Group.commands. The commands returned not filtered. To do the filtering you will have to call filter_commands() yourself.

Parameters: group (Group) – The group that was requested for help.

await send_command_help(command)¶

This function is a coroutine.

Handles the implementation of the single command page in the help command.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

Showing Help

There are certain attributes and methods that are helpful for a help command to show such as the following:

Command.help
Command.brief
Command.short_doc
Command.description
get_command_signature()

There are more than just these attributes but feel free to play around with these to help you get started to get the output that you want.

Parameters: command (Command) – The command that was requested for help.

await prepare_help_command(ctx, command=None)¶

This function is a coroutine.

A low level method that can be used to prepare the help command before it does anything. For example, if you need to prepare some state in your subclass before the command does its processing then this would be the place to do it.

The default implementation does nothing.

Note

This is called inside the help command callback body. So all the usual rules that happen inside apply here as well.

Parameters

ctx (Context) – The invocation context.
command (Optional[str]) – The argument passed to the help command.

await command_callback(ctx, *, command=None)¶

This function is a coroutine.

The actual implementation of the help command.

It is not recommended to override this method and instead change the behaviour through the methods that actually get dispatched.

send_bot_help()
send_cog_help()
send_group_help()
send_command_help()
get_destination()
command_not_found()
subcommand_not_found()
send_error_message()
on_help_command_error()
prepare_help_command()

DefaultHelpCommand¶

class guilded.ext.commands.DefaultHelpCommand(*args, **kwargs)¶

The implementation of the default help command.

This inherits from HelpCommand.

It extends it with the following attributes.

width¶

The maximum number of characters that fit in a line. Defaults to 80.

Type: int

sort_commands¶

Whether to sort the commands in the output alphabetically. Defaults to True.

Type: bool

dm_help¶

A tribool that indicates if the help command should DM the user instead of sending it to the channel it received it from. If the boolean is set to True, then all help output is DM’d. If False, none of the help output is DM’d. If None, then the bot will only DM when the help message becomes too long (dictated by more than dm_help_threshold characters). Defaults to False.

Type: Optional[bool]

dm_help_threshold¶

The number of characters the paginator must accumulate before getting DM’d to the user if dm_help is set to None. Defaults to 1000.

Type: Optional[int]

indent¶

How much to indent the commands from a heading. Defaults to 2.

Type: int

commands_heading¶

The command list’s heading string used when the help command is invoked with a category name. Useful for i18n. Defaults to "Commands:"

Type: str

no_category¶

The string used when there is a command which does not belong to any category(cog). Useful for i18n. Defaults to "No Category"

Type: str

paginator¶

The paginator used to paginate the help command output.

Type: Paginator

shorten_text(text)¶: str: Shortens text to fit into the width.

get_ending_note()¶: str: Returns help command’s ending note. This is mainly useful to override for i18n purposes.

add_indented_commands(commands, *, heading, max_size=None)¶

Indents a list of commands after the specified heading.

The formatting is added to the paginator.

The default implementation is the command name indented by indent spaces, padded to max_size followed by the command’s Command.short_doc and then shortened to fit into the width.

Parameters

commands (Sequence[Command]) – A list of commands to indent for output.
heading (str) – The heading to add to the output. This is only added if the list of commands is greater than 0.
max_size (Optional[int]) – The max size to use for the gap between indents. If unspecified, calls get_max_size() on the commands parameter.

await send_pages()¶: A helper utility to send the page output from paginator to the destination.

add_command_formatting(command)¶

A utility function to format the non-indented block of commands and groups.

Parameters: command (Command) – The command to format.

get_destination()¶

Returns the Messageable where the help command will be output.

You can override this method to customise the behaviour.

By default this returns the context’s channel.

Returns: The destination where the help command will be output.
Return type: abc.Messageable

await prepare_help_command(ctx, command)¶

This function is a coroutine.

A low level method that can be used to prepare the help command before it does anything. For example, if you need to prepare some state in your subclass before the command does its processing then this would be the place to do it.

The default implementation does nothing.

Note

This is called inside the help command callback body. So all the usual rules that happen inside apply here as well.

Parameters

ctx (Context) – The invocation context.
command (Optional[str]) – The argument passed to the help command.

await send_bot_help(mapping)¶

This function is a coroutine.

Handles the implementation of the bot command page in the help command. This function is called when the help command is called with no arguments.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

Also, the commands in the mapping are not filtered. To do the filtering you will have to call filter_commands() yourself.

Parameters: mapping (Mapping[Optional[Cog], List[Command]]) – A mapping of cogs to commands that have been requested by the user for help. The key of the mapping is the Cog that the command belongs to, or None if there isn’t one, and the value is a list of commands that belongs to that cog.

await send_command_help(command)¶

This function is a coroutine.

Handles the implementation of the single command page in the help command.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

Showing Help

There are certain attributes and methods that are helpful for a help command to show such as the following:

Command.help
Command.brief
Command.short_doc
Command.description
get_command_signature()

There are more than just these attributes but feel free to play around with these to help you get started to get the output that you want.

Parameters: command (Command) – The command that was requested for help.

await send_group_help(group)¶

This function is a coroutine.

Handles the implementation of the group page in the help command. This function is called when the help command is called with a group as the argument.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

To get the commands that belong to this group without aliases see Group.commands. The commands returned not filtered. To do the filtering you will have to call filter_commands() yourself.

Parameters: group (Group) – The group that was requested for help.

await send_cog_help(cog)¶

This function is a coroutine.

Handles the implementation of the cog page in the help command. This function is called when the help command is called with a cog as the argument.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

To get the commands that belong to this cog see Cog.get_commands(). The commands returned not filtered. To do the filtering you will have to call filter_commands() yourself.

Parameters: cog (Cog) – The cog that was requested for help.

add_check(func)¶

Adds a check to the help command.

Parameters: func – The function that will be used as a check.

property cog¶

A property for retrieving or setting the cog for the help command.

When a cog is set for the help command, it is as-if the help command belongs to that cog. All cog special methods will apply to the help command and it will be automatically unset on unload.

To unbind the cog from the help command, you can set it to None.

Returns: The cog that is currently set for the help command.
Return type: Optional[Cog]

await command_callback(ctx, *, command=None)¶

This function is a coroutine.

The actual implementation of the help command.

It is not recommended to override this method and instead change the behaviour through the methods that actually get dispatched.

send_bot_help()
send_cog_help()
send_group_help()
send_command_help()
get_destination()
command_not_found()
subcommand_not_found()
send_error_message()
on_help_command_error()
prepare_help_command()

command_not_found(string)¶

This function could be a coroutine.

A method called when a command is not found in the help command. This is useful to override for i18n.

Defaults to No command called {0} found.

Parameters: string (str) – The string that contains the invalid command. Note that this has had mentions removed to prevent abuse.
Returns: The string to use when a command has not been found.
Return type: str

await filter_commands(commands, *, sort=False, key=None)¶

This function is a coroutine.

Returns a filtered list of commands and optionally sorts them.

This takes into account the verify_checks and show_hidden attributes.

Parameters

commands (Iterable[Command]) – An iterable of commands that are getting filtered.
sort (bool) – Whether to sort the result.
key (Optional[Callable[Command, Any]]) – An optional key function to pass to sorted() that takes a Command as its sole parameter. If sort is passed as True then this will default as the command name.

Returns

A list of commands that passed the filter.

Return type

List[Command]

get_bot_mapping()¶: Retrieves the bot mapping passed to send_bot_help().

get_command_signature(command)¶

Retrieves the signature portion of the help page.

Parameters: command (Command) – The command to get the signature of.
Returns: The signature for the command.
Return type: str

get_max_size(commands)¶

Returns the largest name length of the specified command list.

Parameters: commands (Sequence[Command]) – A sequence of commands to check for the largest size.
Returns: The maximum width of the commands.
Return type: int

property invoked_with¶

Similar to Context.invoked_with except properly handles the case where Context.send_help() is used.

If the help command was used regularly then this returns the Context.invoked_with attribute. Otherwise, if it the help command was called using Context.send_help() then it returns the internal command name of the help command.

Returns: The command name that triggered this invocation.
Return type: str

await on_help_command_error(ctx, error)¶

This function is a coroutine.

The help command’s error handler, as specified by Error Handling.

Useful to override if you need some specific behaviour when the error handler is called.

By default this method does nothing and just propagates to the default error handlers.

Parameters

ctx (Context) – The invocation context.
error (CommandError) – The error that was raised.

remove_check(func)¶

Removes a check from the help command.

This function is idempotent and will not raise an exception if the function is not in the command’s checks.

Parameters: func – The function to remove from the checks.

remove_mentions(string)¶

Removes mentions from the string to prevent abuse.

This includes @everyone, @here, member mentions and role mentions.

Returns: The string with mentions removed.
Return type: str

await send_error_message(error)¶

This function is a coroutine.

Handles the implementation when an error happens in the help command. For example, the result of command_not_found() will be passed here.

You can override this method to customise the behaviour.

By default, this sends the error message to the destination specified by get_destination().

Note

You can access the invocation context with HelpCommand.context.

Parameters: error (str) – The error message to display to the user. Note that this has had mentions removed to prevent abuse.

subcommand_not_found(command, string)¶

This function could be a coroutine.

A method called when a command did not have a subcommand requested in the help command. This is useful to override for i18n.

Defaults to either:

'Command "{command.qualified_name}" has no subcommands.'
- If there is no subcommand in the command parameter.
'Command "{command.qualified_name}" has no subcommand named {string}'
- If the command parameter has subcommands but not one named string.

Parameters

command (Command) – The command that did not have the subcommand requested.
string (str) – The string that contains the invalid subcommand. Note that this has had mentions removed to prevent abuse.

Returns

The string to use when the command did not have the subcommand requested.

Return type

str

MinimalHelpCommand¶

class guilded.ext.commands.MinimalHelpCommand(*args, **kwargs)¶

An implementation of a help command with minimal output.

This inherits from HelpCommand.

sort_commands¶

Whether to sort the commands in the output alphabetically. Defaults to True.

Type: bool

commands_heading¶

The command list’s heading string used when the help command is invoked with a category name. Useful for i18n. Defaults to "Commands"

Type: str

aliases_heading¶

The alias list’s heading string used to list the aliases of the command. Useful for i18n. Defaults to "Aliases:".

Type: str

dm_help¶

A tribool that indicates if the help command should DM the user instead of sending it to the channel it received it from. If the boolean is set to True, then all help output is DM’d. If False, none of the help output is DM’d. If None, then the bot will only DM when the help message becomes too long (dictated by more than dm_help_threshold characters). Defaults to False.

Type: Optional[bool]

dm_help_threshold¶

The number of characters the paginator must accumulate before getting DM’d to the user if dm_help is set to None. Defaults to 1000.

Type: Optional[int]

no_category¶

The string used when there is a command which does not belong to any category(cog). Useful for i18n. Defaults to "No Category"

Type: str

paginator¶

The paginator used to paginate the help command output.

Type: Paginator

await send_pages()¶: A helper utility to send the page output from paginator to the destination.

get_opening_note()¶

Returns help command’s opening note. This is mainly useful to override for i18n purposes.

The default implementation returns :: none

Use {prefix}{command_name} [command] for more info on a command. You can also use {prefix}{command_name} [category] for more info on a category.

Returns: The help command opening note.
Return type: str

get_command_signature(command)¶

Retrieves the signature portion of the help page.

Parameters: command (Command) – The command to get the signature of.
Returns: The signature for the command.
Return type: str

get_ending_note()¶

Return the help command’s ending note. This is mainly useful to override for i18n purposes.

The default implementation does nothing.

Returns: The help command ending note.
Return type: str

add_bot_commands_formatting(commands, heading)¶

Adds the minified bot heading with commands to the output.

The formatting should be added to the paginator.

The default implementation is a bold underline heading followed by commands separated by an EN SPACE (U+2002) in the next line.

Parameters

commands (Sequence[Command]) – A list of commands that belong to the heading.
heading (str) – The heading to add to the line.

add_subcommand_formatting(command)¶

Adds formatting information on a subcommand.

The formatting should be added to the paginator.

The default implementation is the prefix and the Command.qualified_name optionally followed by an En dash and the command’s Command.short_doc.

Parameters: command (Command) – The command to show information of.

add_aliases_formatting(aliases)¶

Adds the formatting information on a command’s aliases.

The formatting should be added to the paginator.

The default implementation is the aliases_heading bolded followed by a comma separated list of aliases.

This is not called if there are no aliases to format.

Parameters: aliases (Sequence[str]) – A list of aliases to format.

add_command_formatting(command)¶

A utility function to format commands and groups.

Parameters: command (Command) – The command to format.

get_destination()¶

Returns the Messageable where the help command will be output.

You can override this method to customise the behaviour.

By default this returns the context’s channel.

Returns: The destination where the help command will be output.
Return type: abc.Messageable

await prepare_help_command(ctx, command)¶

This function is a coroutine.

A low level method that can be used to prepare the help command before it does anything. For example, if you need to prepare some state in your subclass before the command does its processing then this would be the place to do it.

The default implementation does nothing.

Note

This is called inside the help command callback body. So all the usual rules that happen inside apply here as well.

Parameters

ctx (Context) – The invocation context.
command (Optional[str]) – The argument passed to the help command.

await send_bot_help(mapping)¶

This function is a coroutine.

Handles the implementation of the bot command page in the help command. This function is called when the help command is called with no arguments.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

Also, the commands in the mapping are not filtered. To do the filtering you will have to call filter_commands() yourself.

Parameters: mapping (Mapping[Optional[Cog], List[Command]]) – A mapping of cogs to commands that have been requested by the user for help. The key of the mapping is the Cog that the command belongs to, or None if there isn’t one, and the value is a list of commands that belongs to that cog.

add_check(func)¶

Adds a check to the help command.

Parameters: func – The function that will be used as a check.

property cog¶

A property for retrieving or setting the cog for the help command.

When a cog is set for the help command, it is as-if the help command belongs to that cog. All cog special methods will apply to the help command and it will be automatically unset on unload.

To unbind the cog from the help command, you can set it to None.

Returns: The cog that is currently set for the help command.
Return type: Optional[Cog]

await command_callback(ctx, *, command=None)¶

This function is a coroutine.

The actual implementation of the help command.

It is not recommended to override this method and instead change the behaviour through the methods that actually get dispatched.

send_bot_help()
send_cog_help()
send_group_help()
send_command_help()
get_destination()
command_not_found()
subcommand_not_found()
send_error_message()
on_help_command_error()
prepare_help_command()

command_not_found(string)¶

This function could be a coroutine.

A method called when a command is not found in the help command. This is useful to override for i18n.

Defaults to No command called {0} found.

Parameters: string (str) – The string that contains the invalid command. Note that this has had mentions removed to prevent abuse.
Returns: The string to use when a command has not been found.
Return type: str

await filter_commands(commands, *, sort=False, key=None)¶

This function is a coroutine.

Returns a filtered list of commands and optionally sorts them.

This takes into account the verify_checks and show_hidden attributes.

Parameters

commands (Iterable[Command]) – An iterable of commands that are getting filtered.
sort (bool) – Whether to sort the result.
key (Optional[Callable[Command, Any]]) – An optional key function to pass to sorted() that takes a Command as its sole parameter. If sort is passed as True then this will default as the command name.

Returns

A list of commands that passed the filter.

Return type

List[Command]

get_bot_mapping()¶: Retrieves the bot mapping passed to send_bot_help().

get_max_size(commands)¶

Returns the largest name length of the specified command list.

Parameters: commands (Sequence[Command]) – A sequence of commands to check for the largest size.
Returns: The maximum width of the commands.
Return type: int

property invoked_with¶

Similar to Context.invoked_with except properly handles the case where Context.send_help() is used.

If the help command was used regularly then this returns the Context.invoked_with attribute. Otherwise, if it the help command was called using Context.send_help() then it returns the internal command name of the help command.

Returns: The command name that triggered this invocation.
Return type: str

await on_help_command_error(ctx, error)¶

This function is a coroutine.

The help command’s error handler, as specified by Error Handling.

Useful to override if you need some specific behaviour when the error handler is called.

By default this method does nothing and just propagates to the default error handlers.

Parameters

ctx (Context) – The invocation context.
error (CommandError) – The error that was raised.

remove_check(func)¶

Removes a check from the help command.

This function is idempotent and will not raise an exception if the function is not in the command’s checks.

Parameters: func – The function to remove from the checks.

remove_mentions(string)¶

Removes mentions from the string to prevent abuse.

This includes @everyone, @here, member mentions and role mentions.

Returns: The string with mentions removed.
Return type: str

await send_cog_help(cog)¶

This function is a coroutine.

Handles the implementation of the cog page in the help command. This function is called when the help command is called with a cog as the argument.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

To get the commands that belong to this cog see Cog.get_commands(). The commands returned not filtered. To do the filtering you will have to call filter_commands() yourself.

Parameters: cog (Cog) – The cog that was requested for help.

await send_error_message(error)¶

This function is a coroutine.

Handles the implementation when an error happens in the help command. For example, the result of command_not_found() will be passed here.

You can override this method to customise the behaviour.

By default, this sends the error message to the destination specified by get_destination().

Note

You can access the invocation context with HelpCommand.context.

Parameters: error (str) – The error message to display to the user. Note that this has had mentions removed to prevent abuse.

subcommand_not_found(command, string)¶

This function could be a coroutine.

A method called when a command did not have a subcommand requested in the help command. This is useful to override for i18n.

Defaults to either:

'Command "{command.qualified_name}" has no subcommands.'
- If there is no subcommand in the command parameter.
'Command "{command.qualified_name}" has no subcommand named {string}'
- If the command parameter has subcommands but not one named string.

Parameters

command (Command) – The command that did not have the subcommand requested.
string (str) – The string that contains the invalid subcommand. Note that this has had mentions removed to prevent abuse.

Returns

The string to use when the command did not have the subcommand requested.

Return type

str

await send_group_help(group)¶

This function is a coroutine.

Handles the implementation of the group page in the help command. This function is called when the help command is called with a group as the argument.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

To get the commands that belong to this group without aliases see Group.commands. The commands returned not filtered. To do the filtering you will have to call filter_commands() yourself.

Parameters: group (Group) – The group that was requested for help.

await send_command_help(command)¶

This function is a coroutine.

Handles the implementation of the single command page in the help command.

It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use get_destination() to know where to send, as this is a customisation point for other users.

You can override this method to customise the behaviour.

Note

You can access the invocation context with HelpCommand.context.

Showing Help

There are certain attributes and methods that are helpful for a help command to show such as the following:

Command.help
Command.brief
Command.short_doc
Command.description
get_command_signature()

There are more than just these attributes but feel free to play around with these to help you get started to get the output that you want.

Parameters: command (Command) – The command that was requested for help.

Paginator¶

class guilded.ext.commands.Paginator(prefix='```', suffix='```', max_size=2000, linesep='\n')¶

A class that aids in paginating code blocks for Guilded messages.

len(x): Returns the total number of characters in the paginator.

prefix¶

The prefix inserted to every page. e.g. three backticks.

Type: str

suffix¶

The suffix appended at the end of every page. e.g. three backticks.

Type: str

max_size¶

The maximum amount of codepoints allowed in a page.

Type: int

linesep¶

The character string inserted between lines. e.g. a newline character.

Type: str

clear()¶: Clears the paginator to have no pages.

add_line(line='', *, empty=False)¶

Adds a line to the current page.

If the line exceeds the max_size then an exception is raised.

Parameters

line (str) – The line to add.
empty (bool) – Indicates if another empty line should be added.

Raises

RuntimeError – The line was too big for the current max_size.

close_page()¶: Prematurely terminate a page.

property pages¶

Returns the rendered list of pages.

Type: List[str]

Checks¶

@guilded.ext.commands.check(predicate)¶

A decorator that adds a check to the Command or its subclasses. These checks could be accessed via Command.checks.

These checks should be predicates that take in a single parameter taking a Context. If the check returns a False-like value then during invocation a CheckFailure exception is raised and sent to the on_command_error() event.

If an exception should be thrown in the predicate then it should be a subclass of CommandError. Any exception not subclassed from it will be propagated while those subclassed will be sent to on_command_error().

A special attribute named predicate is bound to the value returned by this decorator to retrieve the predicate passed to the decorator. This allows the following introspection and chaining to be done:

def owner_or_permissions(**perms):
    original = commands.has_permissions(**perms).predicate
    async def extended_check(ctx):
        if ctx.server is None:
            return False
        return ctx.server.owner_id == ctx.author.id or await original(ctx)
    return commands.check(extended_check)

Note

The function returned by predicate is always a coroutine, even if the original function was not a coroutine.

Examples

Creating a basic check to see if the command invoker is you.

def check_if_it_is_me(ctx):
    return ctx.message.author.id == 'EdVMVKR4'

@bot.command()
@commands.check(check_if_it_is_me)
async def only_for_me(ctx):
    await ctx.send('I know you!')

Transforming common checks into its own decorator:

def is_me():
    def predicate(ctx):
        return ctx.message.author.id == 'EdVMVKR4'
    return commands.check(predicate)

@bot.command()
@is_me()
async def only_me(ctx):
    await ctx.send('Only you!')

Parameters: predicate (Callable[[Context], bool]) – The predicate to check if the command should be invoked.

@guilded.ext.commands.before_invoke(coro)¶

A decorator that registers a coroutine as a pre-invoke hook.

This allows you to refer to one before invoke hook for several commands that do not have to be within the same cog.

Example

async def record_usage(ctx):
    print(ctx.author, 'used', ctx.command, 'at', ctx.message.created_at)

@bot.command()
@commands.before_invoke(record_usage)
async def who(ctx): # Output: <User> used who at <Time>
    await ctx.send('i am a bot')

class What(commands.Cog):

    @commands.before_invoke(record_usage)
    @commands.command()
    async def when(self, ctx): # Output: <User> used when at <Time>
        await ctx.send(f'and i have existed since {ctx.bot.user.created_at}')

    @commands.command()
    async def where(self, ctx): # Output: <Nothing>
        await ctx.send('on Guilded')

    @commands.command()
    async def why(self, ctx): # Output: <Nothing>
        await ctx.send('because someone made me')

bot.add_cog(What())

@guilded.ext.commands.after_invoke(coro)¶

A decorator that registers a coroutine as a post-invoke hook.

This allows you to refer to one after invoke hook for several commands that do not have to be within the same cog.

@guilded.ext.commands.server_only()¶

A check() that indicates this command must only be used in a server context only. Basically, no private messages are allowed when using the command.

This check raises a special exception, NoPrivateMessage that is inherited from CheckFailure.

@guilded.ext.commands.guild_only()¶

A check() that indicates this command must only be used in a server context only. Basically, no private messages are allowed when using the command.

This check raises a special exception, NoPrivateMessage that is inherited from CheckFailure.

@guilded.ext.commands.is_owner()¶

A check() that checks if the person invoking this command is the owner of the bot.

This is powered by Bot.is_owner().

This check raises a special exception, NotOwner that is derived from CheckFailure.

@guilded.ext.commands.is_nsfw()¶

This exists for compatibility with discord.py bots. It may be removed in a later version.

A check() that checks if the channel is a NSFW channel.

In a server context, this always raises NSFWChannelRequired, which is derived from CheckFailure.

@guilded.ext.commands.cooldown()¶

A decorator that adds a cooldown to a Command

A cooldown allows a command to only be used a specific amount of times in a specific time frame. These cooldowns can be based either on a per-guild, per-channel, per-user, per-role, per-group, or global basis. Denoted by the third argument of type which must be of enum type BucketType.

If a cooldown is triggered, then CommandOnCooldown is triggered in on_command_error() and the local error handler.

A command can only have a single cooldown.

Parameters

rate (int) – The number of times a command can be used before triggering a cooldown.
per (float) – The amount of seconds to wait for a cooldown when it’s been triggered.
type (Union[BucketType, Callable[[Context], Any]]) – The type of cooldown to have. If callable, should return a key for the mapping.

@guilded.ext.commands.dynamic_cooldown()¶

A decorator that adds a dynamic cooldown to a Command

This differs from cooldown() in that it takes a function that accepts a single parameter of type Context and must return a Cooldown or None. If None is returned then that cooldown is effectively bypassed.

A cooldown allows a command to only be used a specific amount of times in a specific time frame. These cooldowns can be based either on a per-guild, per-channel, per-user, per-role or global basis. Denoted by the third argument of type which must be of enum type BucketType.

If a cooldown is triggered, then CommandOnCooldown is triggered in on_command_error() and the local error handler.

A command can only have a single cooldown.

New in version 1.5.

Parameters

cooldown (Callable[[Context], Optional[Cooldown]]) – A function that takes a message and returns a cooldown that will apply to this invocation or None if the cooldown should be bypassed.
type (BucketType) – The type of cooldown to have.

@guilded.ext.commands.max_concurrency()¶

A decorator that adds a maximum concurrency to a Command or its subclasses.

This enables you to only allow a certain number of command invocations at the same time, for example if a command takes too long or if only one user can use it at a time. This differs from a cooldown in that there is no set waiting period or token bucket – only a set number of people can run the command.

New in version 1.5.

Parameters

number (int) – The maximum number of invocations of this command that can be running at the same time.
per (BucketType) – The bucket that this concurrency is based on, e.g. BucketType.server would allow it to be used up to number times per server.
wait (bool) – Whether the command should wait for the queue to be over. If this is set to False then instead of waiting until the command can run again, the command raises MaxConcurrencyReached to its error handler. If this is set to True then the command waits until it can be executed.

@guilded.ext.commands.has_role()¶

A check() that is added that checks if the member invoking the command has the role specified via the name or ID specified.

If a string is specified, you must give the exact name of the role, including caps and spelling.

If an integer is specified, you must give the ID of the role.

This check raises one of two special exceptions, MissingRole if the user is missing a role, or NoPrivateMessage if it is used in a private message. Both inherit from CheckFailure.

New in version 1.9.

Parameters: item (Union[int, str]) – The name or ID of the role to check.

@guilded.ext.commands.has_any_role()¶

A check() that is added that checks if the member invoking the command has any of the roles specified. This means that if they have one out of the three roles specified, then this check will return True.

Similar to has_role(), the names or IDs passed in must be exact.

This check raises one of two special exceptions, MissingAnyRole if the user is missing all roles, or NoPrivateMessage if it is used in a private message. Both inherit from CheckFailure.

New in version 1.9.

Parameters: items (List[Union[str, int]]) – An argument list of names or IDs to check for roles that the member has.

Example

@bot.command()
@commands.has_any_role('Library Developer', 'Moderator', 23218717)
async def cool(ctx):
    await ctx.send('You are cool indeed')

@guilded.ext.commands.bot_has_role()¶

Similar to has_role() except checks if the bot itself has the role.

This check raises one of two special exceptions, BotMissingRole if the bot is missing the role, or NoPrivateMessage if it is used in a private message. Both inherit from CheckFailure.

New in version 1.9.

@guilded.ext.commands.bot_has_any_role()¶

Similar to has_any_role() except checks if the bot itself has any of the roles listed.

This check raises one of two special exceptions, BotMissingAnyRole if the bot is missing all roles, or NoPrivateMessage if it is used in a private message. Both inherit from CheckFailure.

New in version 1.9.

@guilded.ext.commands.has_server_permissions()¶

A check() that is added that checks if the member has all of the permissions necessary at the server level.

The permissions passed in must be exactly like the properties shown under Permissions.

This check raises a special exception, MissingPermissions that is inherited from CheckFailure.

If this check is called in a DM context, it will raise an exception, NoPrivateMessage.

New in version 1.9.

Parameters: perms – An argument list of permissions to check for.

Example

@bot.command()
@commands.has_server_permissions(manage_messages=True)
async def test(ctx):
    await ctx.send('You can manage messages in this server.')

@guilded.ext.commands.has_guild_permissions()¶

A check() that is added that checks if the member has all of the permissions necessary at the server level.

The permissions passed in must be exactly like the properties shown under Permissions.

This check raises a special exception, MissingPermissions that is inherited from CheckFailure.

If this check is called in a DM context, it will raise an exception, NoPrivateMessage.

New in version 1.9.

Parameters: perms – An argument list of permissions to check for.

Example

@bot.command()
@commands.has_server_permissions(manage_messages=True)
async def test(ctx):
    await ctx.send('You can manage messages in this server.')

@guilded.ext.commands.bot_has_server_permissions()¶: Identical to has_server_permissions() but for the bot member’s permissions.

New in version 1.9.

@guilded.ext.commands.bot_has_guild_permissions()¶: Identical to has_server_permissions() but for the bot member’s permissions.

New in version 1.9.

Context¶

class guilded.ext.commands.Context(**attrs)¶

property clean_prefix¶

The cleaned up invoke prefix. i.e. mentions are @name instead of <@id>.

Type: str

await reply(content=..., *, embed=..., embeds=..., reference=..., reply_to=..., mention_author=None, silent=None, private=False, delete_after=None)¶

This function is a coroutine.

Reply to the invoking message.

This is identical to abc.Messageable.send(), but the reply_to parameter already includes the context message.

await create_thread(name, *, message=None, visibility=None)¶

This function is a coroutine.

Create a new thread in the channel.

Warning

Be careful with this method! It is very easy to accidentally cause a loop if you create a thread on a message that caused the creation of its thread.

Depending on the type of the parent channel, this method requires different permissions:

Parent Type	Permission
`chat`	`Permissions.read_messages`
`voice`	`Permissions.hear_voice`
`stream`	`Permissions.view_streams`

New in version 1.9.

Parameters

name (str) – The thread’s name. Can include spaces.
message (Optional[ChatMessage]) – The message to create the thread with. If a private message is passed (i.e. ChatMessage.private is True), then the thread is private too.
visibility (Optional[ChannelVisibility]) –
What users can access the channel. Currently, this can only be private or None.

New in version 1.10.

Returns

The created thread.

Return type

Thread

Raises

NotFound – The server, channel, or message provided does not exist.
Forbidden – You are not allowed to create a thread in this channel.
HTTPException – Failed to create a thread.

await fetch_message(message_id, /)¶

This function is a coroutine.

Fetch a message.

Returns: The message from the ID.
Return type: ChatMessage

await history(*, before=None, after=None, limit=50, include_private=False)¶

This function is a coroutine.

Fetch the message history of this channel.

All parameters are optional.

Parameters

before (datetime.datetime) – Fetch messages sent before this timestamp.
after (datetime.datetime) – Fetch messages sent after this timestamp.
limit (int) – The maximum number of messages to fetch. Defaults to 50.
include_private (bool) – Whether to include private messages in the response. Defaults to False. If the client is a user account, this has no effect and is always True.

Return type

List[ChatMessage]

await send(content=..., *, embed=..., embeds=..., reference=..., reply_to=..., mention_author=None, silent=None, private=False, delete_after=None, hide_preview_urls=...)¶

This function is a coroutine.

Send a message to a Guilded channel.

Warning

Replying with both silent and private set to True (a private reply with no mention) will not send the reply to the author of the message(s) until they refresh the channel. This is a Guilded bug.

Parameters

content (str) – The text content to send with the message.
embed (Embed) – An embed to send with the message. This parameter cannot be meaningfully combined with embeds.
embeds (List[Embed]) – A list of embeds to send with the message. This can contain at most 1 value. This parameter cannot be meaningfully combined with embed.
reply_to (List[ChatMessage]) – A list of up to 5 messages to reply to.
silent (bool) – Whether this message should not mention the members mentioned in it, including the authors of messages it is in reply to, if any. Defaults to False.
private (bool) – Whether this message should only be visible to its author (the bot) and the authors of the messages it is replying to. Defaults to False. You should not include sensitive data in these because private replies can still be visible to server moderators.
delete_after (float) – If provided, the number of seconds to wait in the background before deleting the sent message. If the deletion fails, then it is silently ignored.
hide_preview_urls (List[str]) – URLs in content to prevent unfurling as a link preview when displaying in Guilded.

Converters¶

class guilded.ext.commands.Converter(*args, **kwargs)¶

The base class of custom converters that require the Context to be passed to be useful.

This allows you to implement converters that function similar to the special cased guilded classes.

Classes that derive from this should override the convert() method to do its conversion logic. This method must be a coroutine.

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.ObjectConverter(*args, **kwargs)¶

Converts to a Object.

This is generally not useful unless you simply want to make sure something is a possibly-valid Guilded object, even if you don’t care what it is.

The lookup strategy is as follows (in order):

Lookup by member, role, or channel mention
Lookup by ID

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.MemberConverter(*args, **kwargs)¶

Converts to a Member.

All lookups are via the current server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name
Lookup by nickname

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.UserConverter(*args, **kwargs)¶

Converts to a User.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.ServerChannelConverter(*args, **kwargs)¶

Converts to a ServerChannel.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name.

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.AnnouncementChannelConverter(*args, **kwargs)¶

Converts to a AnnouncementChannel.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.ChatChannelConverter(*args, **kwargs)¶

Converts to a ChatChannel.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

guilded.ext.commands.TextChannelConverter¶: alias of guilded.ext.commands.converters.ChatChannelConverter

class guilded.ext.commands.DocsChannelConverter(*args, **kwargs)¶

Converts to a DocsChannel.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.ForumChannelConverter(*args, **kwargs)¶

Converts to a ForumChannel.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.MediaChannelConverter(*args, **kwargs)¶

Converts to a MediaChannel.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.ListChannelConverter(*args, **kwargs)¶

Converts to a ListChannel.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.SchedulingChannelConverter(*args, **kwargs)¶

Converts to a SchedulingChannel.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.ThreadConverter(*args, **kwargs)¶

Converts to a Thread.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.VoiceChannelConverter(*args, **kwargs)¶

Converts to a VoiceChannel.

All lookups are via the local server. If in a DM context, then the lookup is done by the global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.ServerConverter(*args, **kwargs)¶

Converts to a Server.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by name

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

guilded.ext.commands.GuildConverter¶: alias of guilded.ext.commands.converters.ServerConverter

class guilded.ext.commands.ChatMessageConverter(*args, **kwargs)¶

Converts to a ChatMessage.

The lookup strategy is as follows (in order):

Lookup by ID (the message must be in the context channel)
Lookup by message share URL

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

guilded.ext.commands.MessageConverter¶: alias of guilded.ext.commands.converters.ChatMessageConverter

class guilded.ext.commands.ColourConverter(*args, **kwargs)¶

Converts to a Colour.

The following formats are accepted:

0x<hex>
#<hex>
0x#<hex>
rgb(<number>, <number>, <number>)
Any of the classmethods in Colour
- The _ in the name can be optionally replaced with spaces.

Like CSS, <number> can be either 0-255 or 0-100% and <hex> can be either a 6 digit hex number or a 3 digit hex shortcut (e.g. #fff).

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

guilded.ext.commands.ColorConverter¶: alias of guilded.ext.commands.converters.ColourConverter

class guilded.ext.commands.EmoteConverter(*args, **kwargs)¶

Converts to a Emote.

All lookups are done for the local server first, if available. If that lookup fails, then it checks the client’s global cache.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by extracting ID from the emote
Lookup by name

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

guilded.ext.commands.EmojiConverter¶: alias of guilded.ext.commands.converters.EmoteConverter

class guilded.ext.commands.RoleConverter(*args, **kwargs)¶

Converts to a Role.

All lookups are via the local server. If in a DM context, the converter raises the NoPrivateMessage exception.

The lookup strategy is as follows (in order):

Lookup by ID
Lookup by mention
Lookup by name

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

class guilded.ext.commands.Greedy¶

A special converter that greedily consumes arguments until it can’t. As a consequence of this behaviour, most input errors are silently discarded, since it is used as an indicator of when to stop parsing.

When a parser error is met the greedy converter stops converting, undoes the internal string parsing routine, and continues parsing regularly.

For example, in the following code:

@commands.command()
async def test(ctx, numbers: Greedy[int], reason: str):
    await ctx.send("numbers: {}, reason: {}".format(numbers, reason))

An invocation of [p]test 1 2 3 4 5 6 hello would pass numbers with [1, 2, 3, 4, 5, 6] and reason with hello.

For more information, check Special Converters.

class guilded.ext.commands.clean_content(*, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False, remove_markdown=False)¶

Converts the argument to a mention-scrubbed version of itself.

fix_channel_mentions¶

Whether to clean channel mentions.

Type: bool

use_nicknames¶

Whether to use nicknames when transforming mentions.

Type: bool

escape_markdown¶

Whether to also escape special markdown characters.

Type: bool

remove_markdown¶

Whether to also remove special markdown characters. This option is not supported with escape_markdown

Type: bool

await convert(ctx, argument)¶

This function is a coroutine.

The method to override to do conversion logic. If an error is found while converting, it is recommended to raise a CommandError derived exception as it will properly propagate to the error handlers.

Parameters

ctx (Context) – The invocation context that the argument is being used in.
argument (str) – The argument that is being converted.

Raises

.CommandError – A generic exception occurred when converting the argument.
.BadArgument – The converter failed to convert the argument.

await guilded.ext.commands.run_converters(ctx, converter, argument, param)¶

This function is a coroutine.

Runs converters for a given converter, argument, and parameter.

This function does the same work that the library does under the hood.

Parameters

ctx (Context) – The invocation context to run the converters under.
converter (Any) – The converter to run, this corresponds to the annotation in the function.
argument (str) – The argument to convert to.
param (inspect.Parameter) – The parameter being converted. This is mainly for error reporting.

Raises

CommandError – The converter failed to convert.

Returns

The resulting conversion.

Return type

Any

Exceptions¶

exception guilded.ext.commands.CommandRegistrationError(name, *, alias_conflict=False)¶

An exception raised when the command can’t be added because the name is already taken by a different command.

This inherits from guilded.ClientException

name¶

The command name that had the error.

Type: str

alias_conflict¶

Whether the name that conflicts is an alias of the command we try to add.

Type: bool

exception guilded.ext.commands.CommandError(message=None, *args)¶

The base exception type for all command related errors.

This inherits from guilded.GuildedException.

This exception and exceptions inherited from it are handled in a special way as they are caught and passed into a special event from Bot, on_command_error().

exception guilded.ext.commands.ConversionError(converter, original)¶

Exception raised when a Converter class raises non-CommandError.

This inherits from CommandError.

converter¶

The converter that failed.

Type: guilded.ext.commands.Converter

original¶

The original exception that was raised. You can also get this via the __cause__ attribute.

Type: Exception

exception guilded.ext.commands.UserInputError(message=None, *args)¶

The base exception type for errors that involve errors regarding user input.

This inherits from CommandError.

exception guilded.ext.commands.MissingRequiredArgument(param)¶

Exception raised when parsing a command and a parameter that is required is not encountered.

This inherits from UserInputError

param¶

The argument that is missing.

Type: inspect.Parameter

exception guilded.ext.commands.TooManyArguments(message=None, *args)¶

Exception raised when the command was passed too many arguments and its Command.ignore_extra attribute was not set to True.

This inherits from UserInputError

exception guilded.ext.commands.BadArgument(message=None, *args)¶

Exception raised when a parsing or conversion failure is encountered on an argument to pass into a command.

This inherits from UserInputError

exception guilded.ext.commands.BadUnionArgument(param, converters, errors)¶

Exception raised when a typing.Union converter fails for all its associated types.

This inherits from UserInputError

param¶

The parameter that failed being converted.

Type: inspect.Parameter

converters¶

A tuple of converters attempted in conversion, in order of failure.

Type: Tuple[Type, …]

errors¶

A list of errors that were caught from failing the conversion.

Type: List[CommandError]

exception guilded.ext.commands.BadLiteralArgument(param, literals, errors)¶

Exception raised when a typing.Literal converter fails for all its associated values.

This inherits from UserInputError

param¶

The parameter that failed being converted.

Type: inspect.Parameter

literals¶

A tuple of values compared against in conversion, in order of failure.

Type: Tuple[Any, ...]

errors¶

A list of errors that were caught from failing the conversion.

Type: List[CommandError]

exception guilded.ext.commands.ArgumentParsingError(message=None, *args)¶

An exception raised when the parser fails to parse a user’s input.

This inherits from UserInputError.

There are child classes that implement more granular parsing errors for i18n purposes.

exception guilded.ext.commands.UnexpectedQuoteError(quote)¶

An exception raised when the parser encounters a quote mark inside a non-quoted string.

This inherits from ArgumentParsingError.

quote¶

The quote mark that was found inside the non-quoted string.

Type: str

exception guilded.ext.commands.InvalidEndOfQuotedStringError(char)¶

An exception raised when a space is expected after the closing quote in a string but a different character is found.

This inherits from ArgumentParsingError.

char¶

The character found instead of the expected string.

Type: str

exception guilded.ext.commands.ExpectedClosingQuoteError(close_quote)¶

An exception raised when a quote character is expected but not found.

This inherits from ArgumentParsingError.

close_quote¶

The quote character expected.

Type: str

exception guilded.ext.commands.CommandNotFound(message=None, *args)¶

Exception raised when a command is attempted to be invoked but no command under that name is found.

This is not raised for invalid subcommands, rather just the initial main command that is attempted to be invoked.

This inherits from CommandError.

exception guilded.ext.commands.CheckFailure(message=None, *args)¶

Exception raised when the predicates in Command.checks have failed.

This inherits from CommandError

exception guilded.ext.commands.CheckAnyFailure(checks, errors)¶

Exception raised when all predicates in check_any() fail.

This inherits from CheckFailure.

errors¶

A list of errors that were caught during execution.

Type: List[CheckFailure]

checks¶

A list of check predicates that failed.

Type: List[Callable[[Context], bool]]

exception guilded.ext.commands.PrivateMessageOnly(message=None)¶

Exception raised when an operation does not work outside of private message contexts.

This inherits from CheckFailure

exception guilded.ext.commands.NoPrivateMessage(message=None)¶

Exception raised when an operation does not work in private message contexts.

This inherits from CheckFailure

exception guilded.ext.commands.NotOwner(message=None, *args)¶

Exception raised when the message author is not the owner of the bot.

This inherits from CheckFailure

exception guilded.ext.commands.MissingRole(missing_role)¶

Exception raised when the command invoker lacks a role to run a command.

This inherits from CheckFailure

missing_role¶

The required role that is missing. This is the parameter passed to has_role().

Type: Union[str, int]

exception guilded.ext.commands.BotMissingRole(missing_role)¶

Exception raised when the bot’s member lacks a role to run a command.

This inherits from CheckFailure

missing_role¶

The required role that is missing. This is the parameter passed to has_role().

Type: Union[str, int]

exception guilded.ext.commands.MissingAnyRole(missing_roles)¶

Exception raised when the command invoker lacks any of the roles specified to run a command.

This inherits from CheckFailure

missing_roles¶

The roles that the invoker is missing. These are the parameters passed to has_any_role().

Type: List[Union[str, int]]

exception guilded.ext.commands.BotMissingAnyRole(missing_roles)¶

Exception raised when the bot’s member lacks any of the roles specified to run a command.

This inherits from CheckFailure

missing_roles¶

The roles that the bot’s member is missing. These are the parameters passed to has_any_role().

Type: List[Union[str, int]]

exception guilded.ext.commands.NSFWChannelRequired(channel)¶

Exception raised when a channel does not have the required NSFW setting.

This inherits from CheckFailure.

New in version 1.5.

channel¶

The channel that does not have NSFW enabled.

Type: abc.ServerChannel

exception guilded.ext.commands.MissingPermissions(missing_perms, *args)¶

Exception raised when the command invoker lacks permissions to run a command.

This inherits from CheckFailure

missing_permissons¶

The required permissions that are missing.

Type: list

exception guilded.ext.commands.BotMissingPermissions(missing_perms, *args)¶

Exception raised when the bot’s member lacks permissions to run a command.

This inherits from CheckFailure

missing_permissons¶

The required permissions that are missing.

Type: list

exception guilded.ext.commands.DisabledCommand(message=None, *args)¶

Exception raised when the command being invoked is disabled.

This inherits from CommandError

exception guilded.ext.commands.CommandInvokeError(e)¶

Exception raised when the command being invoked raised an exception.

This inherits from CommandError

original¶

The original exception that was raised. You can also get this via the __cause__ attribute.

Type: Exception

exception guilded.ext.commands.CommandOnCooldown(cooldown, retry_after, type)¶

Exception raised when the command being invoked is on cooldown.

This inherits from CommandError

cooldown¶

A class with attributes rate, per, and type similar to the cooldown() decorator.

Type: Cooldown

retry_after¶

The amount of seconds to wait before you can retry again.

Type: float

type¶

The type associated with the cooldown.

Type: BucketType

exception guilded.ext.commands.MaxConcurrencyReached(number, per)¶

Exception raised when the command being invoked has reached its maximum concurrency.

This inherits from CommandError.

number¶

The maximum number of concurrent invokers allowed.

Type: int

per¶

The bucket type passed to the max_concurrency() decorator.

Type: BucketType

exception guilded.ext.commands.ExtensionError(message=None, *args, name)¶

Base exception for extension related errors.

This inherits from GuildedException.

name¶

The extension that had an error.

Type: str

exception guilded.ext.commands.ExtensionAlreadyLoaded(name)¶

An exception raised when an extension has already been loaded.

This inherits from ExtensionError

exception guilded.ext.commands.ExtensionNotLoaded(name)¶

An exception raised when an extension was not loaded.

This inherits from ExtensionError

exception guilded.ext.commands.NoEntryPointError(name)¶

An exception raised when an extension does not have a setup entry point function.

This inherits from ExtensionError

exception guilded.ext.commands.ExtensionFailed(name, original)¶

An exception raised when an extension failed to load during execution of the module or setup entry point.

This inherits from ExtensionError

name¶

The extension that had the error.

Type: str

original¶

The original exception that was raised. You can also get this via the __cause__ attribute.

Type: Exception

exception guilded.ext.commands.ExtensionNotFound(name)¶

An exception raised when an extension is not found.

This inherits from ExtensionError

name¶

The extension that had the error.

Type: str

Hierarchy¶

Exception
- GuildedException
  ClientException
  
  CommandRegistrationError
  
  CommandError
  
  ConversionError
  
  UserInputError
  
  MissingRequiredArgument
  
  TooManyArguments
  
  BadArgument
  
  BadUnionArgument
  
  BadLiteralArgument
  
  ArgumentParsingError
  
  UnexpectedQuoteError
  
  InvalidEndOfQuotedStringError
  
  ExpectedClosingQuoteError
  
  CommandNotFound
  
  CheckFailure
  
  CheckAnyFailure
  
  PrivateMessageOnly
  
  NoPrivateMessage
  
  NotOwner
  
  MissingRole
  
  BotMissingRole
  
  MissingAnyRole
  
  BotMissingAnyRole
  
  NSFWChannelRequired
  
  MissingPermissions
  
  BotMissingPermissions
  
  DisabledCommand
  
  CommandInvokeError
  
  CommandOnCooldown
  
  MaxConcurrencyReached
  
  ExtensionError
  
  ExtensionAlreadyLoaded
  
  ExtensionNotLoaded
  
  NoEntryPointError
  
  ExtensionFailed
  
  ExtensionNotFound