Nadir Chowdhury
4 weeks ago
committed by
GitHub
GitHub
1 changed files with 268 additions and 0 deletions
@ -0,0 +1,268 @@ |
|||
.. currentmodule:: discord |
|||
|
|||
.. _ext_commands_help: |
|||
|
|||
The Help Command |
|||
=================== |
|||
|
|||
Using The Help Command |
|||
------------------------- |
|||
|
|||
There is a help command made for you. It walks through your commands and formats them like |
|||
``<Command Name> Description``. Commands are then sorted into categories by their Cog. By default, your commands will be |
|||
in ``No Category``, which is always at the bottom of the commands list. |
|||
|
|||
Here is a simple example of the default behaviour: |
|||
|
|||
:: |
|||
|
|||
An example bot to showcase the discord.ext.commands extension module. |
|||
|
|||
There are a number of utility commands being showcased here. |
|||
|
|||
MyCoolCog: |
|||
cool Says if a user is cool. |
|||
No Category: |
|||
add Adds two numbers together. |
|||
choose Chooses between multiple choices. |
|||
help Shows this message |
|||
joined Says when a member joined. |
|||
repeat Repeats a message multiple times. |
|||
roll Rolls a dice in NdN format. |
|||
|
|||
Type !help command for more info on a command. |
|||
You can also type !help category for more info on a category. |
|||
|
|||
You may want to send help if the user doesn't use a command correctly. Here is an example of how to do this: |
|||
|
|||
.. code-block:: python3 |
|||
:caption: sos.py |
|||
:emphasize-lines: 8, 10, 18 |
|||
|
|||
from discord.ext import commands |
|||
|
|||
bot = commands.Bot(command_prefix='!', description="Nothing to worry about here.") |
|||
|
|||
@bot.command() |
|||
async def sos(ctx, what: str = None): |
|||
"""Send Help!""" |
|||
if not what: |
|||
return await ctx.send_help(sos) |
|||
await ctx.send('Sending help for {0}!'.format(what)) |
|||
await ctx.send_help(what) |
|||
|
|||
class MyCoolCog(commands.Cog): |
|||
"""It's OK, we saved the damsel.""" |
|||
|
|||
@commands.command() |
|||
async def damsel(self, ctx): |
|||
"""There's a damsel in distress!""" |
|||
await ctx.send_help(self) # TODO not sure about this change |
|||
|
|||
bot.add_cog(MyCoolCog()) |
|||
|
|||
:meth:`~.commands.Context.send_help` allows you to specify a :class:`~.commands.Command`, :class:`~commands.Cog`, or |
|||
even a regular string. |
|||
|
|||
Let's take a look at this code step by step: |
|||
|
|||
1. In the command ``sos``, there is a parameter called ``what``. |
|||
- If the parameter is not passed, it will send help for itself a :meth:`~.commands.Command` instance. |
|||
- If the parameter is passed, it will attempt to send help for a matching cog name or command. |
|||
- Doing ``!sos damsel`` would invoke :meth:`~.commands.HelpCommand.send_command_help` with ``command`` being |
|||
``damsel``, and send the help for it. |
|||
|
|||
2. In the cog ``MyCoolCog``, there is a docstring provided for help commands. |
|||
|
|||
3. In the command ``damsel``, it will send help for the cog called ``MyCoolCog``. |
|||
- This would send the docstring of ``MyCoolCog``, and its commands. |
|||
|
|||
:: |
|||
|
|||
It's OK, we saved the damsel. |
|||
|
|||
Commands: |
|||
damsel There's a damsel in distress! |
|||
|
|||
Type !help command for more info on a command. |
|||
You can also type !help category for more info on a category. |
|||
|
|||
Replacing The Help Command |
|||
----------------------------- |
|||
|
|||
If you don't like the default help command, you can replace the normal help command by setting |
|||
:attr:`~commands.Bot.help_command` to a subclass of :class:`~.commands.HelpCommand` or ``None`` to remove it. |
|||
|
|||
Here is an example of an alternative help command you can set, :class:`~.commands.MinimalHelpCommand` |
|||
|
|||
.. code-block:: python3 |
|||
:caption: mini_help_bot.py |
|||
:emphasize-lines: 5 |
|||
|
|||
from discord.ext import commands |
|||
|
|||
description = """Hey! I am your local test bot.""" |
|||
bot = commands.Bot(command_prefix='!', description=description, |
|||
help_command=commands.MinimalHelpCommand()) |
|||
|
|||
By default, the help command appears in ``No Category``, which can seem like a bit of a nuisance when categorising |
|||
commands. One way of doing this is by setting the :attr:`~.commands.DefaultHelpCommand.no_category`, an attribute also |
|||
found on :attr:`~.commands.MinimalHelpCommand`. |
|||
|
|||
.. code-block:: python3 |
|||
:emphasize-lines: 4 |
|||
|
|||
from discord.ext import commands |
|||
|
|||
bot = commands.Bot(command_prefix='!', description="There is no saviour.", |
|||
help_command=commands.DefaultHelpCommand(no_category='Help Me!')) |
|||
|
|||
You can also set the :class:`~commands.Cog` of a help command, simply by setting :attr:`~commands.HelpCommand.cog`. |
|||
However, if you plan on having the ability to reload or disable extensions containing cogs, just setting it isn't wise |
|||
idea. |
|||
|
|||
To counter this, you could set the new help command to default, during the teardown of an extension. |
|||
|
|||
.. code-block:: python3 |
|||
:emphasize-lines: 22-23 |
|||
|
|||
from discord.ext import commands |
|||
|
|||
|
|||
class Help(commands.Cog): |
|||
"""This isn't the right place for help.""" |
|||
|
|||
@commands.command() |
|||
async def sos(self, ctx, what: str = None): |
|||
"""Send Help!""" |
|||
if not what: |
|||
return await ctx.send_help(self.sos) |
|||
await ctx.send('Sending help for {0}!'.format(what)) |
|||
await ctx.send_help(what) |
|||
|
|||
|
|||
def setup(bot): |
|||
help_cog = Help() |
|||
bot.add_cog(help_cog) |
|||
bot.help_command = commands.DefaultHelpCommand(no_category='Help.') |
|||
bot.help_command.cog = help_cog |
|||
|
|||
|
|||
def teardown(bot): |
|||
bot.help_command = commands.DefaultHelpCommand() |
|||
|
|||
Here is an example of what you are able to do by subclassing :class:`~.commands.MinimalHelpCommand`: |
|||
|
|||
.. code-block:: python3 |
|||
|
|||
from discord.ext import commands |
|||
|
|||
class MyHelp(commands.MinimalHelpCommand): |
|||
def __init__(self): |
|||
super().__init__(no_category='Misc') |
|||
|
|||
def add_bot_commands_formatting(self, commands, heading): |
|||
if commands: |
|||
joined = ', '.join('`{0}`'.format(c.name) for c in commands) |
|||
self.paginator.add_line('Category: [__**%s**__]' % heading) |
|||
self.paginator.add_line(joined) |
|||
|
|||
bot = commands.Bot(command_prefix='!', help_command=MyHelp()) |
|||
|
|||
Writing A Help Command |
|||
------------------------- |
|||
|
|||
For this tutorial, we will be using the standard :class:`~.commands.HelpCommand`. |
|||
|
|||
|
|||
The Help Command Name |
|||
~~~~~~~~~~~~~~~~~~~~~ |
|||
|
|||
If you would like to use a different name for the help command, there is an option to change it: |
|||
|
|||
.. code-block:: python3 |
|||
|
|||
class MyHelpCommand(commands.HelpCommand): |
|||
def __init__(self): |
|||
super().__init__(command_attrs={'name': 'commands'}) |
|||
|
|||
This allows the help command to be called via ``!commands``. |
|||
|
|||
|
|||
Bot Help |
|||
~~~~~~~~ |
|||
|
|||
The main help sent when ``!help`` is called, this calls :meth:`~discord.ext.commands.HelpCommand.send_bot_help`. |
|||
|
|||
This is the default implementation: |
|||
|
|||
:: |
|||
|
|||
This is my cool bot made in discord.py! ]--- Description |
|||
|
|||
Help: ]--- Cog Name |
|||
sos Send Help! ]--- Cog Command |
|||
No Category: ]--- No Cog |
|||
add Adds two numbers together. \ |
|||
choose Chooses between multiple choices. This will get cut... | |
|||
cool Says if a user is cool. | |
|||
help Shows this message. |--- No Cog Commands |
|||
joined Says when a member joined. | |
|||
repeat Repeats a message multiple times. | |
|||
roll Rolls a dice in NdN format. / |
|||
|
|||
Type ?help command for more info on a command. \___ Ending Note |
|||
You can also type ?help category for more info on a category. / |
|||
|
|||
To make it a little easier, it should start off with: |
|||
|
|||
.. code-block:: python3 |
|||
|
|||
async def send_bot_help(self, mapping): |
|||
ctx = self.context |
|||
bot = ctx.bot |
|||
|
|||
|
|||
Description |
|||
+++++++++++ |
|||
|
|||
By default, the description is set when :class:`commands.Bot` is instantiated, with the |
|||
``description`` keyword argument: ``commands.Bot(description='Hey! This is my Cool Bot:tm:')``. |
|||
|
|||
However, it is possible to disregard that, as it is only used in :meth:`~commands.DefaultHelpCommand.send_bot_help`. |
|||
This can be done by adding the line ``self.paginator.add_line('My Description!', empty=True)`` to the end of |
|||
the function. |
|||
|
|||
In the default help command, the description is added first, then the category and commands are added. |
|||
The position of the description is entirely your choice. |
|||
|
|||
|
|||
Cog Name |
|||
++++++++ |
|||
|
|||
The cog name is usually determined by :attr:`~commands.Cog.qualified_name` - or ``No Category`` - and is formatted to |
|||
be: ``My Cog:`` or ``No Category:``. |
|||
|
|||
In the default help command it is done as so: |
|||
|
|||
.. code-block:: python3 |
|||
:emphasize-lines: 1-5 |
|||
|
|||
no_category = '\u200b{0.no_category}:'.format(self) |
|||
|
|||
def get_category(command, *, no_category=no_category): |
|||
cog = command.cog |
|||
return cog.qualified_name + ':' if cog is not None else no_category |
|||
|
|||
filtered = await self.filter_commands(bot.commands, sort=True, key=get_category) |
|||
max_size = self.get_max_size(filtered) |
|||
to_iterate = itertools.groupby(filtered, key=get_category) |
|||
|
|||
self.no_category is set to ``No Category:`` when you instantiate :class:`commands.DefaultHelpCommand`, however you can |
|||
pass ``no_category='...'`` to the HelpCommand constructor to this. The next local function, ``get_category`` |
|||
determines :attr:`commands.Command.cog`'s name via :attr:`commands.Cog.qualified_name`. |
|||
|
|||
|
|||
Command |
|||
+++++++ |
|||
|
|||
Loading…
Reference in new issue