From 4cf7b36b7b264406766883a4be6e931370b348b7 Mon Sep 17 00:00:00 2001 From: James Lu Date: Fri, 8 Sep 2017 19:02:03 -0700 Subject: [PATCH] permissions-api: clarify how globs are processed [skip ci] --- docs/technical/permissions-api.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/technical/permissions-api.md b/docs/technical/permissions-api.md index ea0d4c2..bc85785 100644 --- a/docs/technical/permissions-api.md +++ b/docs/technical/permissions-api.md @@ -2,7 +2,7 @@ Permissions were introduced in PyLink 1.0 as a way for plugins to manage command access, replacing the old `irc.checkAuthenticated()`. The permissions system in PyLink is fairly simple, globally assigning a list of permissions to each hostmask/exttarget. -Permissions take the format `pluginname.commandname.optional_extra_portion(s)`, and support wildcards in matching. Permission nodes are case-insensitive and casemapping aware, but are conventionally defined as being all lowercase. +Permissions conventionally take the format `pluginname.commandname.optional_extra_portion(s)`, and support globs**\*** in matching. Permission nodes are case-insensitive and casemapping aware, but are defined as being all lowercase for consistency. The permissions module is available as `pylinkirc.coremods.permissions`. Usually, plugins import it this format: @@ -10,9 +10,11 @@ The permissions module is available as `pylinkirc.coremods.permissions`. Usually from pylinkirc.coremods import permissions ``` +**\*** The globbing used by the permissions module is just generic IRC-style globbing. For example, anyone with `*`, `perm.*`, `perm.?`, `*.1`, etc. in their permissions list will be allowed to use a command checking for a permission named `perm.1`. + ## Checking for permissions -Individual functions check for permissions using the `permissions.checkPermissions(irc, source, ['perm.1', 'perm.2'])` function, where the last argument is an OR'ed list of permissions (i.e. users only need one out of all of them). This function returns `True` when a permission check passes, and raises `utils.NotAuthorizedError` when a check fails, automatically aborting the execution of the command function. +Individual functions check for permissions using the `permissions.checkPermissions(irc, source, ['perm.1', 'perm.2'])` function, where the last argument is an OR'ed list of permissions matched against a list of permission string globs that a user may have. If the user has any of the permissions in the permission list, they will be allowed to call the command. This function returns `True` when a permission check passes, and raises `utils.NotAuthorizedError` when a check fails, automatically aborting the execution of the command function. `utils.NotAuthorizedError` can be treated like any other exception, so it's possible to wrap it around `try:` / `except:` for more complex access checking ([example in the Automode plugin](https://github.com/GLolol/PyLink/blob/1.1.1/plugins/automode.py#L64-L68)).