e965a675c1
Some checks failed
Deploy MkDocs / deploy (push) Has been cancelled
Makes commonly used classes, functions, and decorators from `disagreement.ext` and `disagreement.ui` submodules directly accessible under the `disagreement` namespace. This change simplifies import statements for users, leading to cleaner and more concise code. Documentation and examples have been updated to reflect these new, simplified import paths.
69 lines
1.6 KiB
Markdown
69 lines
1.6 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
|
|
```
|
|
|
|
The help command will show each command's brief description if provided.
|
|
|
|
## 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`.
|