mirror of
https://github.com/Cog-Creators/Red-DiscordBot.git
synced 2025-11-20 18:06:08 -05:00
Permissions redesign (#2149)
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>
This commit is contained in:
Toby Harradine
GitHub
@@ -8,100 +8,90 @@ 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
|
||||
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 as if
|
||||
the cog was not loaded.
|
||||
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 will be checked in the following order
|
||||
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.
|
||||
|
||||
1. Owner level command specific settings
|
||||
2. Owner level cog specific settings
|
||||
3. Server level command specific settings
|
||||
4. Server level cog specific settings
|
||||
For each of those, the first rule pertaining to one of the following models will be used:
|
||||
|
||||
For each of those, settings have varying priorities (listed below, highest to lowest priority)
|
||||
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
|
||||
|
||||
1. User whitelist
|
||||
2. User blacklist
|
||||
3. Voice Channel whitelist
|
||||
4. Voice Channel blacklist
|
||||
5. Text Channel whitelist
|
||||
6. Text Channel blacklist
|
||||
7. Role settings (see below)
|
||||
8. Server whitelist
|
||||
9. Server blacklist
|
||||
10. Default settings
|
||||
|
||||
For the role whitelist and blacklist settings,
|
||||
roles will be checked individually in order from highest to lowest role the user has
|
||||
Each role will be checked for whitelist, then blacklist. The first role with a setting
|
||||
found will be the one used.
|
||||
In private messages, only global rules about a user will be checked.
|
||||
|
||||
-------------------------
|
||||
Setting Rules from a file
|
||||
Setting Rules From a File
|
||||
-------------------------
|
||||
|
||||
The permissions cog can set rules from a yaml file:
|
||||
All entries are based on ID.
|
||||
An example of the expected format is shown below.
|
||||
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
|
||||
|
||||
cogs:
|
||||
COG:
|
||||
Admin:
|
||||
allow:
|
||||
- 78631113035100160
|
||||
deny:
|
||||
- 96733288462286848
|
||||
78631113035100160: true
|
||||
96733288462286848: false
|
||||
Audio:
|
||||
allow:
|
||||
- 133049272517001216
|
||||
default: deny
|
||||
commands:
|
||||
133049272517001216: true
|
||||
default: false
|
||||
COMMAND:
|
||||
cleanup bot:
|
||||
allow:
|
||||
- 78631113035100160
|
||||
default: deny
|
||||
78631113035100160: true
|
||||
default: false
|
||||
ping:
|
||||
deny:
|
||||
- 96733288462286848
|
||||
default: allow
|
||||
96733288462286848: false
|
||||
default: true
|
||||
|
||||
----------------------
|
||||
Example configurations
|
||||
----------------------
|
||||
|
||||
Locking Audio cog to approved server(s) as a bot owner
|
||||
Locking the ``[p]play`` command to approved server(s) as a bot owner:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]permissions setglobaldefault Audio deny
|
||||
[p]permissions addglobalrule allow Audio [server ID or name]
|
||||
[p]permissions setglobaldefault play deny
|
||||
[p]permissions addglobalrule allow play [server ID or name]
|
||||
|
||||
Locking Audio to specific voice channel(s) as a serverowner or admin:
|
||||
Locking the ``[p]play`` command to specific voice channel(s) as a serverowner or admin:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]permissions setguilddefault deny play
|
||||
[p]permissions setguilddefault deny "playlist start"
|
||||
[p]permissions addguildrule allow play [voice channel ID or name]
|
||||
[p]permissions addguildrule allow "playlist start" [voice channel ID or name]
|
||||
[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 cleanup
|
||||
Allowing extra roles to use ``[p]cleanup``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]permissions addguildrule allow Cleanup [role ID]
|
||||
[p]permissions addserverrule allow cleanup [role ID]
|
||||
|
||||
Preventing cleanup from being used in channels where message history is important:
|
||||
Preventing ``[p]cleanup`` from being used in channels where message history is important:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]permissions addguildrule deny Cleanup [channel ID or mention]
|
||||
[p]permissions addserverrule deny cleanup [channel ID or mention]
|
||||
|
||||
Reference in New Issue
Block a user