Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.perm.IPermissionRequestor

Timestamp:

Jun 3, 2011, 6:28:56 PM (13 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.perm.IPermissionRequestor

@@ +1 @@
+== Extension Point : ''IPermissionRequestor'' ==
+
+||'''Interface'''||''IPermissionRequestor''||'''Since'''||0.9||
+||'''Module'''||''trac.perm''||'''Source'''||[source:trunk/trac/perm.py#L60 perm.py]||
+
+
+The (somewhat confusingly named) ''IPermissionRequestor'' simply allows components to define permission actions (and meta permission actions and their relations to other permission actions).
+
+== Purpose ==
+
+Many of Trac's features are only available to users with certain permissions. By default these are the coarse permissions described in TracPermissions. More fine-grained per-resource permissions as described by TracFineGrainedPermissions are also possible.
+
+While a component can check for any permissions already defined by other components, it might want to define its own permission types for its actions on resources.
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+Only one method has to be defined: {{{get_permission_actions()}}}. This method should return a list of permission actions. Each action is either the name of the action (a simple string) or, for so called ''meta permissions'' a tuple, where the first tuple item is the name of the action, and the second tuple item is a list of subsumed action names. (The meta permission covers all listed permissions. If multiple implementations return the same meta permission, they are combined.)
+
+Action names should be in ALL_CAPS_WITH_UNDERSCORES and usually consist of two parts:
+ * The resource type / module name.
+ * The action to perform on that resource.
+
+The most common action is VIEW, to allow basic usage (viewing) of a resource. It is often required for components implementing [wiki:TracDev/PluginDevelopment/ExtensionPoints/IRequestHandler IRequestHandler], where {{{process_request()}}} would check for permissions categorically ({{{req.perm.require('RESOURCE_VIEW')}}}) or selectively ({{{if 'RESOURCE_ACTION' in req.perm:}}}). (Such an IRequestHandler - or any other kind of checked resource access - could also be implemented by any other Component.)
+
+Anyone with access to a ''perm'' (trac.perm.PermissionCache) can perform permission check. It is usually obtained from ''req'' (a trac.web.api.Request). More fine-grained per-resource permission checks can be performed by obtaining a specialized cache using {{{req.perm(resource)}}} or {{{req.perm(realm, resource_id)}}}.
+
+A slightly more complex pattern is to return multiple simple RESOURCE_ACTION permission actions and one RESOURCE_ADMIN meta permission action covering the others. Even more complex hierarchies of permissions are possible. (See [#Ticket])
+
+== Examples ==
+
+=== Minimal ===
+
+An almost minimal example defining two new permissions to be checked elsewhere:
+{{{#!python
+from trac.core import Component, implements
+from trac.perm import IPermissionRequestor
+
+class CoffeePermissions(Component):
+    implements(IPermissionRequestor)
+
+    def get_permission_actions(self):
+        return ('COFFEE_BREW', 'COFFEE_DRINK') 
+}}}
+
+=== Upgrade example ===
+
+If a new version of a component renames / merges / splits existing permissions of an older version, it might want to implement an environment upgrade ([wiki:TracDev/PluginDevelopment/ExtensionPoints/IEnvironmentSetupParticipant IEnvironmentSetupParticipant]).
+
+A real example would be [h:TracPastePlugin], which changed from a single permission PASTEBIN_USE to multiple permissions PASTEBIN_VIEW and PASTEBIN_CREATE. In [h:changeset:4983 this changeset], ({{{environment_needs_upgrade}}} checks {{{_has_old_permission}}} for any of the old permissions and {{{upgrade_environment}}} calls {{{convert_use_permissions}}} (via the {{{version_map}}} if required) to convert them to the new permissions.
+
+== Available Implementations ==
+
+=== Simple === #Simple
+
+One of the simplest use cases is to define one permission to view the resources of that module:
+
+ * [source:trunk/trac/timeline/web_ui.py#L80 trac.timeline.web_ui.TimelineModule]
+{{{#!python
+return ['TIMELINE_VIEW']
+}}}
+
+ * [source:trunk/trac/search/web_ui.py#L72 trac.search.web_ui.SearchModule]
+{{{#!python
+return ['SEARCH_VIEW']
+}}}
+
+ * [source:trunk/trac/about.py#L49 trac.about.AboutModule]
+{{{#!python
+return ['CONFIG_VIEW']
+}}}
+
+=== Ticket === #Ticket
+
+The most complex example in Trac itself. Various meta permissions subsume certain / all other permissions for convenience.
+
+ * [source:trunk/trac/ticket/api.py#L417 trac.ticket.api.TicketSystem]
+{{{#!python
+return ['TICKET_APPEND', 'TICKET_CREATE', 'TICKET_CHGPROP',
+        'TICKET_VIEW', 'TICKET_EDIT_CC', 'TICKET_EDIT_DESCRIPTION',
+        'TICKET_EDIT_COMMENT',
+        ('TICKET_MODIFY', ['TICKET_APPEND', 'TICKET_CHGPROP']),
+        ('TICKET_ADMIN', ['TICKET_CREATE', 'TICKET_MODIFY',
+                          'TICKET_VIEW', 'TICKET_EDIT_CC',
+                          'TICKET_EDIT_DESCRIPTION',
+                          'TICKET_EDIT_COMMENT'])]
+}}}
+
+ * [source:trunk/trac/ticket/report.py#L77 trac.ticket.report.ReportModule]
+{{{#!python
+actions = ['REPORT_CREATE', 'REPORT_DELETE', 'REPORT_MODIFY', 
+           'REPORT_SQL_VIEW', 'REPORT_VIEW'] 
+return actions + [('REPORT_ADMIN', actions)]  
+}}}
+
+=== Roadmap === #Roadmap
+
+For historical reasons a bit unintuitive. Planned to be simplified in the future (see #4292 / #3022)
+
+ * [source:trunk/trac/ticket/roadmap.py#L361 trac.ticket.roadmap.RoadmapModule]
+{{{#!python
+actions = ['MILESTONE_CREATE', 'MILESTONE_DELETE', 'MILESTONE_MODIFY',
+           'MILESTONE_VIEW', 'ROADMAP_VIEW']
+return ['ROADMAP_VIEW'] + [('ROADMAP_ADMIN', actions)]
+}}}
+
+ * [source:trunk/trac/ticket/roadmap.py#L562 MilestoneModule]
+{{{#!python
+actions = ['MILESTONE_CREATE', 'MILESTONE_DELETE', 'MILESTONE_MODIFY',
+           'MILESTONE_VIEW']
+return actions + [('MILESTONE_ADMIN', actions)]
+}}}
+
+=== Wiki === #Wiki
+
+ * [source:trunk/trac/wiki/web_ui.py#L96 trac.wiki.web_ui.WikiModule]
+{{{#!python
+actions = ['WIKI_CREATE', 'WIKI_DELETE', 'WIKI_MODIFY', 'WIKI_RENAME',
+           'WIKI_VIEW']
+return actions + [('WIKI_ADMIN', actions)]
+}}}
+
+As an interesting peculiarity: Permissions to manipulate permissions:
+
+ * [source:trunk/trac/admin/web_ui.py#L347 trac.admin.web_ui.PermissionAdminPanel]
+{{{#!python
+actions = ['PERMISSION_GRANT', 'PERMISSION_REVOKE']
+return actions + [('PERMISSION_ADMIN', actions)]
+}}}
+
+=== Version control === #VersionControl
+
+An example of a component to combine permissions of other components into a meta permission.
+
+ * [source:trunk/trac/versioncontrol/admin.py#L156 trac.versioncontrol.admin.VersionControlAdmin]
+{{{#!python
+return [('VERSIONCONTROL_ADMIN', ['BROWSER_VIEW', 'CHANGESET_VIEW',
+                                  'FILE_VIEW', 'LOG_VIEW'])]
+}}}
+
+ * [source:trunk/trac/versioncontrol/web_ui/browser.py#L301 trac.versioncontrol.web_ui.browser.BrowserModule]
+{{{#!python
+return ['BROWSER_VIEW', 'FILE_VIEW']
+}}}
+
+ * [source:trunk/trac/versioncontrol/web_ui/changeset.py#L176 trac.versioncontrol.web_ui.changeset.ChangesetModule]
+{{{#!python
+return ['CHANGESET_VIEW']
+}}}
+
+ * [source:trunk/trac/versioncontrol/web_ui/log.py#L66 trac.versioncontrol.web_ui.log.LogModule]
+{{{#!python
+return ['LOG_VIEW']
+}}}
+
+== Additional Information and References ==
+
+ * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_perm.html#trac.perm.IPermissionRequestor API Reference]
+ * Ticket about extending exsting meta-permissions: #8036
+ * Mailing list [http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/3119 message] about the initial design of IPermissionRequestor, [wiki:TracDev/PluginDevelopment/ExtensionPoints/IPermissionStore IPermissionStore] and [wiki:TracDev/PluginDevelopment/ExtensionPoints/IPermissionGroupProvider IPermissionGroupProvider]