73 lines
1.8 KiB
Markdown
73 lines
1.8 KiB
Markdown
# Commands Extension
|
|
|
|
This guide covers the built-in prefix command system.
|
|
|
|
## Help Command
|
|
|
|
The command handler registers a `help` command automatically. Use it to list all available commands or get information about a single command.
|
|
|
|
```
|
|
!help # lists commands
|
|
!help ping # shows help for the "ping" command
|
|
```
|
|
|
|
Commands are grouped by their Cog name and paginated so that long help
|
|
lists are split into multiple messages using the `Paginator` utility.
|
|
|
|
If you need custom formatting you can subclass
|
|
`HelpCommand` and override `send_command_help` or `send_group_help`.
|
|
|
|
## Checks
|
|
|
|
Use `commands.check` to prevent a command from running unless a predicate
|
|
returns ``True``. Checks may be regular or async callables that accept a
|
|
`CommandContext`.
|
|
|
|
```python
|
|
from disagreement import command, check, CheckFailure
|
|
|
|
def is_owner(ctx):
|
|
return ctx.author.id == "1"
|
|
|
|
@command()
|
|
@check(is_owner)
|
|
async def secret(ctx):
|
|
await ctx.send("Only for the owner!")
|
|
```
|
|
|
|
When a check fails a :class:`CheckFailure` is raised and dispatched through the
|
|
command error handler.
|
|
|
|
## Cooldowns
|
|
|
|
Commands can be rate limited using the ``cooldown`` decorator. The example
|
|
below restricts usage to once every three seconds per user:
|
|
|
|
```python
|
|
from disagreement import command, cooldown
|
|
|
|
@command()
|
|
@cooldown(1, 3.0)
|
|
async def ping(ctx):
|
|
await ctx.send("Pong!")
|
|
```
|
|
|
|
Invoking a command while it is on cooldown raises :class:`CommandOnCooldown`.
|
|
|
|
## Permission Checks
|
|
|
|
Use `commands.requires_permissions` to ensure the invoking member has the
|
|
required permissions in the channel.
|
|
|
|
```python
|
|
from disagreement import command, requires_permissions
|
|
from disagreement import Permissions
|
|
|
|
@command()
|
|
@requires_permissions(Permissions.MANAGE_MESSAGES)
|
|
async def purge(ctx):
|
|
await ctx.send("Purged!")
|
|
```
|
|
|
|
Missing permissions raise :class:`CheckFailure`.
|