mirror of
https://github.com/Cog-Creators/Red-DiscordBot.git
synced 2025-11-06 11:18:54 -05:00
0870403299
API changes: - Cogs must now inherit from `commands.Cog` (see #2151 for discussion and more details) - All functions which are not decorators in the `redbot.core.checks` module are now deprecated in favour of their counterparts in `redbot.core.utils.mod`. This is to make this module more consistent and end the confusing naming convention. - `redbot.core.checks.check_overrides` function is now gone, overrideable checks can now be created with the `@commands.permissions_check` decorator - Command, Group, Cog and Context have some new attributes and methods, but they are for internal use so shouldn't concern cog creators (unless they're making a permissions cog!). - `__permissions_check_before` and `__permissions_check_after` have been replaced: A cog method named `__permissions_hook` will be evaluated as permissions hooks in the same way `__permissions_check_before` previously was. Permissions hooks can also be added/removed/verified through the new `*_permissions_hook()` methods on the bot object, and they will be verified even when permissions is unloaded. - New utility method `redbot.core.utils.chat_formatting.humanize_list` - New dependency [`schema`](https://github.com/keleshev/schema) User-facing changes: - When a `@bot_has_permissions` check fails, the bot will respond saying what permissions were actually missing. - All YAML-related `[p]permissions` subcommands now reside under the `[p]permissions acl` sub-group (tbh I still think the whole cog has too many top-level commands) - The YAML schema for these commands has been changed - A rule cannot be set as allow and deny at the same time (previously this would just default to allow) Documentation: - New documentation for `redbot.core.commands.requires` and `redbot.core.checks` modules - Renewed documentation for the permissions cog - `sphinx.ext.doctest` is now enabled Note: standard discord.py checks will still behave exactly the same way, in fact they are checked before `Requires` is looked at, so they are not overrideable. Signed-off-by: Toby Harradine <tobyharradine@gmail.com>
98 lines
2.7 KiB
ReStructuredText
98 lines
2.7 KiB
ReStructuredText
.. Permissions Cog Reference
|
|
|
|
=========================
|
|
Permissions Cog Reference
|
|
=========================
|
|
|
|
------------
|
|
How it works
|
|
------------
|
|
|
|
When loaded, the permissions cog will allow you to define extra custom rules for who can use a
|
|
command.
|
|
|
|
If no applicable rules are found, the command will behave normally.
|
|
|
|
Rules can also be added to cogs, which will affect all commands from that cog. The cog name can be
|
|
found from the help menu.
|
|
|
|
-------------
|
|
Rule priority
|
|
-------------
|
|
|
|
Rules set for subcommands will take precedence over rules set for the parent commands, which
|
|
lastly take precedence over rules set for the cog. So for example, if a user is denied the Core
|
|
cog, but allowed the ``[p]set token`` command, the user will not be able to use any command in the
|
|
Core cog except for ``[p]set token``.
|
|
|
|
In terms of scope, global rules will be checked first, then server rules.
|
|
|
|
For each of those, the first rule pertaining to one of the following models will be used:
|
|
|
|
1. User
|
|
2. Voice channel
|
|
3. Text channel
|
|
4. Channel category
|
|
5. Roles, highest to lowest
|
|
6. Server (can only be in global rules)
|
|
7. Default rules
|
|
|
|
In private messages, only global rules about a user will be checked.
|
|
|
|
-------------------------
|
|
Setting Rules From a File
|
|
-------------------------
|
|
|
|
The permissions cog can also set, display or update rules with a YAML file with the
|
|
``[p]permissions yaml`` command. Models must be represented by ID. Rules must be ``true`` for
|
|
allow, or ``false`` for deny. Here is an example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
COG:
|
|
Admin:
|
|
78631113035100160: true
|
|
96733288462286848: false
|
|
Audio:
|
|
133049272517001216: true
|
|
default: false
|
|
COMMAND:
|
|
cleanup bot:
|
|
78631113035100160: true
|
|
default: false
|
|
ping:
|
|
96733288462286848: false
|
|
default: true
|
|
|
|
----------------------
|
|
Example configurations
|
|
----------------------
|
|
|
|
Locking the ``[p]play`` command to approved server(s) as a bot owner:
|
|
|
|
.. code-block:: none
|
|
|
|
[p]permissions setglobaldefault play deny
|
|
[p]permissions addglobalrule allow play [server ID or name]
|
|
|
|
Locking the ``[p]play`` command to specific voice channel(s) as a serverowner or admin:
|
|
|
|
.. code-block:: none
|
|
|
|
[p]permissions setserverdefault deny play
|
|
[p]permissions setserverdefault deny "playlist start"
|
|
[p]permissions addserverrule allow play [voice channel ID or name]
|
|
[p]permissions addserverrule allow "playlist start" [voice channel ID or name]
|
|
|
|
Allowing extra roles to use ``[p]cleanup``:
|
|
|
|
.. code-block:: none
|
|
|
|
[p]permissions addserverrule allow cleanup [role ID]
|
|
|
|
Preventing ``[p]cleanup`` from being used in channels where message history is important:
|
|
|
|
.. code-block:: none
|
|
|
|
[p]permissions addserverrule deny cleanup [channel ID or mention]
|