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

Timestamp:

Aug 21, 2011, 10:07:00 PM (13 years ago)

Author:

Peter Suter

Comment:

Replace minimal example with more meaningful ComponentModuleExamples; fix links

TracDev/PluginDevelopment/ExtensionPoints/trac.perm.IPermissionRequestor

@@ -23 +23 @@
  * 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.)
+The most common action is VIEW, to allow basic usage (viewing) of a resource. It is often required for components implementing [../trac.web.api.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)}}}.
+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])
@@ -33 +33 @@
 === Minimal ===
 
-An almost minimal example defining two new permissions to be checked elsewhere:
+A minimal IPermissionRequestor in isolation is not very useful (but possible) and usually accompanied by implementations of other interfaces that require these permissions. Hence the following example is best understood in context of the ComponentModuleExamples.
+
+In Trac, [TicketComponent components] have no associated permissions. The following example defines two new permissions to be checked elsewhere:
 {{{#!python
 from trac.core import Component, implements
 from trac.perm import IPermissionRequestor
 
-class CoffeePermissions(Component):
+class ComponentModule(Component):
     implements(IPermissionRequestor)
 
     def get_permission_actions(self):
-        return ('COFFEE_BREW', 'COFFEE_DRINK') 
+        return ('COMPONENT_LIST', 'COMPONENT_VIEW') 
 }}}
 
 === 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]).
+If a new version of a component renames / merges / splits existing permissions of an older version, it might want to implement an environment upgrade ([../trac.env.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.
@@ -159 +161 @@
  * [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]
+ * Mailing list [http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/3119 message] about the initial design of IPermissionRequestor, [../trac.perm.IPermissionStore IPermissionStore] and [../trac.perm.IPermissionGroupProvider IPermissionGroupProvider]