Help Commands¶
This section documents help commands, which aid in creating dynamically generated help messages.
Classes¶
HelpCommand¶
- 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)[source]¶
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
]
Specifies if hidden commands should be shown in the output. Defaults to
False
.- Type:
- verify_checks¶
Specifies if commands should have their
Command.checks
called and verified. IfTrue
, always callsCommand.checks
. IfNone
, only callsCommand.checks
in a guild setting. IfFalse
, never callsCommand.checks
. Defaults toTrue
.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:
- add_check(func)[source]¶
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)[source]¶
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()[source]¶
Retrieves the bot mapping passed to
send_bot_help()
.
- property invoked_with[source]¶
Similar to
Context.invoked_with
except properly handles the case whereContext.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 usingContext.send_help()
then it returns the internal command name of the help command.- Returns:
The command name that triggered this invocation.
- Return type:
- remove_mentions(string)[source]¶
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:
- property cog[source]¶
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)[source]¶
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.
- subcommand_not_found(command, string)[source]¶
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 namedstring
.
- Parameters:
- Returns:
The string to use when the command did not have the subcommand requested.
- Return type:
- await filter_commands(commands, *, sort=False, key=None)[source]¶
This function is a coroutine.
Returns a filtered list of commands and optionally sorts them.
This takes into account the
verify_checks
andshow_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 tosorted()
that takes aCommand
as its sole parameter. Ifsort
is passed asTrue
then this will default as the command name.
- Returns:
A list of commands that passed the filter.
- Return type:
List[
Command
]
- get_destination()[source]¶
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:
- await send_error_message(error)[source]¶
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)[source]¶
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)[source]¶
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.
- await send_cog_help(cog)[source]¶
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 callfilter_commands()
yourself.- Parameters:
cog (
Cog
) – The cog that was requested for help.
- await send_group_help(group)[source]¶
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 callfilter_commands()
yourself.- Parameters:
group (
Group
) – The group that was requested for help.
- await send_command_help(command)[source]¶
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:
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)[source]¶
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.
DefaultHelpCommand¶
- defadd_command_formatting
- defadd_indented_commands
- defget_destination
- defget_ending_note
- asyncsend_pages
- defshorten_text
- class disnake.ext.commands.DefaultHelpCommand(*args, **kwargs)[source]¶
The implementation of the default help command.
This inherits from
HelpCommand
.It extends it with the following attributes.
- sort_commands¶
Whether to sort the commands in the output alphabetically. Defaults to
True
.- Type:
- 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. IfFalse
, none of the help output is DM’d. IfNone
, then the bot will only DM when the help message becomes too long (dictated by more thandm_help_threshold
characters). Defaults toFalse
.- 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 toNone
. Defaults to 1000.- Type:
Optional[
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:
- 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:
- get_ending_note()[source]¶
Returns help command’s ending note. This is mainly useful to override for i18n purposes.
- Return type:
- add_indented_commands(commands, *, heading, max_size=None)[source]¶
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 tomax_size
followed by the command’sCommand.short_doc
and then shortened to fit into thewidth
.- 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, callsget_max_size()
on the commands parameter.
- await send_pages()[source]¶
A helper utility to send the page output from
paginator
to the destination.
- add_command_formatting(command)[source]¶
A utility function to format the non-indented block of commands and groups.
- Parameters:
command (
Command
) – The command to format.
- get_destination()[source]¶
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:
MinimalHelpCommand¶
- class disnake.ext.commands.MinimalHelpCommand(*args, **kwargs)[source]¶
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:
- 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:
- aliases_heading¶
The alias list’s heading string used to list the aliases of the command. Useful for i18n. Defaults to
"Aliases:"
.- Type:
- 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. IfFalse
, none of the help output is DM’d. IfNone
, then the bot will only DM when the help message becomes too long (dictated by more thandm_help_threshold
characters). Defaults toFalse
.- 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 toNone
. 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:
- await send_pages()[source]¶
A helper utility to send the page output from
paginator
to the destination.
- get_opening_note()[source]¶
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:
- get_ending_note()[source]¶
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:
- add_bot_commands_formatting(commands, heading)[source]¶
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.
- add_subcommand_formatting(command)[source]¶
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’sCommand.short_doc
.- Parameters:
command (
Command
) – The command to show information of.
- add_aliases_formatting(aliases)[source]¶
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)[source]¶
A utility function to format commands and groups.
- Parameters:
command (
Command
) – The command to format.
- get_destination()[source]¶
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: