help_formatter.md

News Post

Big breaking change to people who use help formatters. HelpFormatter has been redesigned.

First thing's first, it should be noted that the implementation of the help command was moved over to two classes, HelpCommand which implements the base logic and everything revolving the actual help command and DefaultHelpCommand which deals with the formatting of the actual default help command that most bots have.

There are a lot of injection points in the core HelpCommand interface to help creation of help commands. Going forward, I believe most help commands will just use this special construction. With that being said, these are the injection points:

• send_bot_help: Called when requested for entire bot help
• send_cog_help: Called when requested for a specific cog's help
• send_group_help: Called when requested for a Group's help.
• send_command_help: Called when requested for a Command's help
• get_destination: Called to know where to send the help messages to. e.g. DMs or not.
• command_not_found: Function that returns a presentable no command found string.
• subcommand_not_found: Function that returns a string when a subcommand is not found.
• send_error_message: A coroutine that gets passed the result of those two functions up there. By default it just sends the message. But you can e.g. override it to put it in an embed or what have you.
• on_help_command_error: The error handler for the help command if you want to add one.
• prepare_help_command: A coroutine that is called right before the help command processing is done. You can consider it a special form of before_invoke except it's done inside the body of the command.

There are currently two implementations of HelpCommand in the library.

• DefaultHelpCommand, the current help command.
• MinimalHelpCommand, a more slimmed down version of a help command that aims to not spam many pages.

Continued

Due to the difference in design and the bundling of all help command related things into a single class, I hope that future help commands will utilise this design instead of carelessly removing the command and then replacing it with their own. Granted, there is nothing stopping you from doing so but I hope these cases significantly lower in the next coming days.

The DefaultHelpCommand was implemented to be mostly compatible with the old HelpFormatter. The new MinimalHelpCommand is significantly slimmed down, taking way less space and using no code blocks. It's still paginated if necessary.

A frequent request that was asked was if you could associate a help command with a cog. This is easy to do, it's just bot.help_command.cog = cog. After this assignment the help command will pretend to be part of the cog and everything should work as expected. When the cog is unloaded then the help command will be "unbound" from the cog.

Changelog

Please be sure to read the docs .

The following breaking changes happened in Bot:

• In __init__:
  • formatter attribute was removed.
  • help_attrs was replaced, more on that later.
  • pm_help was removed.
  • command_not_found and command_has_no_subcommand were replaced, more on that later.
  • help_command kwarg was added, you can set it to None to disable the default help command.
• Bot.help_command was added to dynamically replace or retrieve the current HelpCommand instance.

The following breaking changes happened in Command

• Command.signature no longer returns alias information.
  • e.g. [a|b|c] <foo> [bar] will now return <foo> [bar].
  • To do alias formatting I recommend doing it in HelpCommand instead.

The following changes happened to commands.Paginator:

• suffix and prefix can now be None to disable sending a prefix or a suffix.

Now, onto finally the meat of the redesign. All of this applies to HelpCommand relative to HelpFormatter.

• In __init__:
  • show_check_failure was renamed to verify_checks
    • Now defaults to True instead of False
  • command_attrs was added
    • Replaces Bot.help_attrs, which was removed.
  • width, commands_heading, no_category have all been removed
    • Put in DefaultHelpCommand instead.
• filter_command_list renamed to filter_commands
• filter_command_list now returns a list of Command instead of a tuple of (name, command).
  • It now accepts an iterable of Command as a required argument.
  • There are two new keyword-only parameters, sort and key.
• Bot.command_not_found and Bot.command_has_no_subcommand are now overridable methods instead of format-based attributes.
• get_command_signature now takes the command object as a parameter.
• max_size property removed
• get_max_size method added, takes a list of commands as its sole parameter.
• remove_mentions method added, this cleans mention syntax for abuse purposes in output.
• shorten_text and get_ending_note have been removed.
  • Put in DefaultHelpCommand instead.

The following applies to DefaultHelpCommand (relative to HelpFormatter)

• In __init__:
  • sort_commands was added to sort commands, defaults to True.
  • indent to control the indent for subcommands in the bot and group help pages.
• paginator is now a public attribute for people to modify at will.

The following customisation points were added (i.e. you can override these to customise the behaviour).

• add_command_formatting
  • Formats the common part of both the group and command help pages.
  • Signature: (command)
• add_indented_commands
  • Formats the subcommand listing in cog, bot, and group pages.
  • Signature: (commands, *, heading, max_size=None)
• get_ending_note
  • Returns the ending note at the end of some of the pages.
  • Signature: ()

The following applies to MinimalHelpCommand

• Basically the same as DefaultHelpCommand in terms of __init__.
  • Has a aliases_heading attribute to customise the "Aliases" label.

The customisation points can be found in the documentation and playing around: https://discordpy.readthedocs.io/en/rewrite/ext/commands/api.html#help-commands