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>

tests/cogs/test_permissions.py

@@ -0,0 +1,67 @@
+
+from redbot.cogs.permissions.permissions import Permissions, GLOBAL
+
+
+def test_schema_update():
+    old = {
+        GLOBAL: {
+            "owner_models": {
+                "cogs": {
+                    "Admin": {"allow": [78631113035100160], "deny": [96733288462286848]},
+                    "Audio": {"allow": [133049272517001216], "default": "deny"},
+                },
+                "commands": {
+                    "cleanup bot": {"allow": [78631113035100160], "default": "deny"},
+                    "ping": {
+                        "allow": [96733288462286848],
+                        "deny": [96733288462286848],
+                        "default": "allow",
+                    },
+                },
+            }
+        },
+        43733288462286848: {
+            "owner_models": {
+                "cogs": {
+                    "Admin": {
+                        "allow": [24231113035100160],
+                        "deny": [35533288462286848, 24231113035100160],
+                    },
+                    "General": {"allow": [133049272517001216], "default": "deny"},
+                },
+                "commands": {
+                    "cleanup bot": {"allow": [17831113035100160], "default": "allow"},
+                    "set adminrole": {
+                        "allow": [87733288462286848],
+                        "deny": [95433288462286848],
+                        "default": "allow",
+                    },
+                },
+            }
+        },
+    }
+    new = Permissions._get_updated_schema(old)
+    assert new == (
+        {
+            "Admin": {
+                GLOBAL: {78631113035100160: True, 96733288462286848: False},
+                43733288462286848: {24231113035100160: True, 35533288462286848: False},
+            },
+            "Audio": {GLOBAL: {133049272517001216: True, "default": False}},
+            "General": {43733288462286848: {133049272517001216: True, "default": False}},
+        },
+        {
+            "cleanup bot": {
+                GLOBAL: {78631113035100160: True, "default": False},
+                43733288462286848: {17831113035100160: True, "default": True},
+            },
+            "ping": {GLOBAL: {96733288462286848: True, "default": True}},
+            "set adminrole": {
+                43733288462286848: {
+                    87733288462286848: True,
+                    95433288462286848: False,
+                    "default": True,
+                }
+            },
+        },
+    )

tests/core/test_utils.py

@@ -101,7 +101,7 @@ async def test_bounded_gather():
         if isinstance(result, RuntimeError):
             num_failed += 1
         else:
-            assert result == i  # verify original orde
+            assert result == i  # verify_permissions original orde
             assert 0 <= result < num_tasks
 
     assert 0 < status[1] <= num_concurrent