From 6728627f787769a975452b12ec82036026e178bc Mon Sep 17 00:00:00 2001 From: James Lu Date: Sun, 25 Dec 2016 11:17:10 -0800 Subject: [PATCH] docs: document the permissions API for developers Closes #368. --- docs/technical/README.md | 11 +++++++++-- docs/technical/permissions-api.md | 23 +++++++++++++++++++++++ 2 files changed, 32 insertions(+), 2 deletions(-) create mode 100644 docs/technical/permissions-api.md diff --git a/docs/technical/README.md b/docs/technical/README.md index 869e2b3..8910a81 100644 --- a/docs/technical/README.md +++ b/docs/technical/README.md @@ -14,11 +14,18 @@ PyLink is an a modular, plugin-based IRC services framework. It uses swappable p ## Contents - [Writing plugins for PyLink](writing-plugins.md) -- [PyLink protocol module specification](pmodule-spec.md) - [PyLink hooks reference](hooks-reference.md) +- [Services bot API/Creating your own service bots](services-api.md) +- [Permissions API Introduction](permissions-api.md) + +---- + +- [PyLink protocol module specification](pmodule-spec.md) - [Supported named channel modes](channel-modes.csv) - [Supported named user modes](user-modes.csv) -- [Services bot API/Creating your own service bots](services-api.md) + +---- + - [Release Process for PyLink](release-process.md) ### Future topics (not yet available) diff --git a/docs/technical/permissions-api.md b/docs/technical/permissions-api.md new file mode 100644 index 0000000..8c1548e --- /dev/null +++ b/docs/technical/permissions-api.md @@ -0,0 +1,23 @@ +# The Permissions API + +Permissions were introduced in PyLink 1.0 as a better (but optional) way for plugins to manage access to commands. 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. + +## 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. + +## Assigning default permissions + +Plugins are also allowed to assign default permissions to their commands, though this should be used sparingly to ensure maximum configurability (explicitly removing permissions isn't supported yet). Default permissions are specified as a `dict` mapping targets to permission lists. + +Example of this in [Automode](https://github.com/GLolol/PyLink/blob/1.1-alpha1/plugins/automode.py#L38-L39): + +```python +# The default set of Automode permissions. +default_permissions = {"$ircop": ['automode.manage.relay_owned', 'automode.sync.relay_owned', + 'automode.list']} +``` + +Default permissions are registered in a plugin's `main()` function via `permissions.addDefaultPermissions(default_permissions_dict)`, and should always be erased on `die()` through `permissions.removeDefaultPermissions(default_permissions_dict)`.