Help Commands

This section documents help commands, which aid in creating dynamically generated help messages.

Classes

HelpCommand

Attributes

• cog
• command_attrs
• context
• invoked_with
• show_hidden
• verify_checks

Methods

• defadd_check
• asynccommand_callback
• defcommand_not_found
• asyncfilter_commands
• defget_bot_mapping
• defget_command_signature
• defget_destination
• defget_max_size
• asyncon_help_command_error
• asyncprepare_help_command
• defremove_check
• defremove_mentions
• asyncsend_bot_help
• asyncsend_cog_help
• asyncsend_command_help
• asyncsend_error_message
• asyncsend_group_help
• defsubcommand_not_found

class disnake.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 #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.

Changed in version 1.7.

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.

New in version 1.4.

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.

New in version 1.4.

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 are 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

Attributes

• commands_heading
• dm_help
• dm_help_threshold
• indent
• no_category
• paginator
• sort_commands
• width

Methods

• defadd_command_formatting
• defadd_indented_commands
• defget_destination
• defget_ending_note
• asyncsend_pages
• defshorten_text

class disnake.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)

Shortens text to fit into the width.

Return type:

str

get_ending_note()

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

Return type:

str

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

MinimalHelpCommand

Attributes

• aliases_heading
• commands_heading
• dm_help
• dm_help_threshold
• no_category
• paginator
• sort_commands

Methods

• defadd_aliases_formatting
• defadd_bot_commands_formatting
• defadd_command_formatting
• defadd_subcommand_formatting
• defget_command_signature
• defget_destination
• defget_ending_note
• defget_opening_note
• asyncsend_pages

class disnake.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

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