The help command

NioBot comes with a built-in help command, which can be used to display information about other commands.

This built-in command is simple, slick, and most importantly, helpful. It takes one optional argument, command, which changes the output to display information about a specific command.

The command list

If a command name is not passed to the help command, it will instead display a list of all available commands. The information that will be displayed will be:

• The command's name
• Any aliases the command has
• The command's short description (usually first 100 characters of first line of the command's callback docstring)
• Any arguments that're required or optional (required are encased in <brackets>, optional in [brackets])

The command is only listed if:

• The command is not disabled (i.e. disabled=True is passed, or omitted entirely)
• The command is not hidden (i.e. hidden=True is not passed (or is ommitted entirely))
• The user passes all of the checks for the command

The command list is sorted alphabetically by command name, and is not paginated or seperated at all. If you want a pretty help command, you should write your own - the default one is just meant to be a happy middle ground between pretty and functional. See the next section for more information on how to do this.

---

Registering your own help command

If you would like to register your own help command, you need to be aware of the following:

• The help command is a command, much like any other command, and is registered as such. You should be aware of aliases, case sensitivity, command states (e.g. disabled/enabled) and visibility (hidden/shown), checks, etc.
• A help command is almost always a user's first impression of your bot. You should make sure that it works 100% of the time, is insanely simple to use, and is very helpful. A help command that just says "You can use command like ?info" is not helpful at all, and will likely turn many users away.

As of v1.2.0, the help command is now a class that you can easily subclass. This is the recommended way of doing this.

The only function that you NEED to change is respond, which is the function that is called when the help command is run. The rest is, quite literally, just dectoration.

Here's an example of a custom help command:

from niobot import DefaultHelpCommand, NioBot


class MyHelpCommand(DefaultHelpCommand):
    async def respond(self, ctx, command=None):
        if command is None:
            # No argument was given to !help
            await ctx.respond("This is a custom help command!")
        else:
            # a command name was given to !help
            await ctx.respond(f"Help for command {command} goes here!")


client = NioBot(help_command=MyHelpCommand().respond)

Now, when someone runs !help, they will get a custom response from the MyHelpCommand class.

help_command should be a full Command instance.

While the above code gives the response function to the help_command parameter, it is not the ideal way to do this. You should pass a niobot.Command instance to the help command instead, as this gives you a more consistent experience, with fine-grained control over the command's state, aliases, etc.

For the sake of berevity, the above code is used to demonstrate the concept of a custom help command.

The DefaultHelpCommand class

The default help command for NioBot.

This is a very basic help command which lists available commands, their arguments, and a short descrption, and allows for further information by specifying the command name as an argument.

clean_output staticmethod

clean_output(
    text: str,
    *,
    escape_user_mentions: bool = True,
    escape_room_mentions: bool = True,
    escape_room_references: bool = False,
    escape_all_periods: bool = False,
    escape_all_at_signs: bool = False,
    escape_method: Optional[Callable[[str], str]] = None
) -> str

Escapes given text and sanitises it, ready for outputting to the user.

This should always be used when echoing any sort of user-provided content, as we all know there will be some annoying troll who will just go @room for no apparent reason every 30 seconds.

Do not rely on this!

This function is not guaranteed to escape all possible mentions, and should not be relied upon to do so. It is only meant to be used as a convenience function for simple commands.

Parameters:

Name	Type	Description	Default
text	str	The text to sanitise	required
escape_user_mentions	bool	Escape all @user:homeserver.tld mentions	True
escape_room_mentions	bool	Escape all @room mentions	True
escape_room_references	bool	Escape all #room:homeserver.tld references	False
escape_all_periods	bool	Escape all literal . characters (can be used to escape all links)	False
escape_all_at_signs	bool	Escape all literal @ characters (can be used to escape all mentions)	False
escape_method	Optional[Callable[[str], str]]	A custom escape method to use instead of the built-in one (which just wraps characters in \u200b)	None

Returns:

Type	Description
str	The cleaned text

format_command_name staticmethod

format_command_name(command: Command) -> str

Formats the command name with its aliases if applicable

format_command_line

format_command_line(prefix: str, command: Command) -> str

Formats a command line, including name(s) & usage.

get_short_description staticmethod

get_short_description(command: Command) -> str

Generates a short (<100 characters) help description for a command.

get_long_description staticmethod

get_long_description(command: Command) -> str

Gets the full help text for a command.

get_default_help async

get_default_help(
    ctx: Context, command_name: str = None
) -> str

Gets the default help text

respond async

respond(ctx: Context, command_name: str = None) -> None

Displays help information about available commands