Changes between Version 5 and Version 6 of TracDev/ComponentArchitecture

Timestamp:

Jul 4, 2007, 3:26:07 PM (17 years ago)

Author:

Dave Abrahams <dave@…>

Comment:

Added usage explanation, syntax highlighting.

TracDev/ComponentArchitecture

@@ -36 +36 @@
 
 {{{
+#!python
 from trac.core import *
 
@@ -45 +46 @@
 
 {{{
+#!python
     comp_mgr = ComponentManager()
     my_comp = MyComponent(comp_mgr)
@@ -52 +54 @@
 
 {{{
+#!python
     my_comp1 = MyComponent(comp_mgr)
     my_comp2 = MyComponent(comp_mgr)
@@ -60 +63 @@
 
 {{{
+#!python
     from trac.core import *
 
@@ -79 +83 @@
 
 {{{
+#!python
     from trac.core import *
     
@@ -107 +112 @@
 
 {{{
+#!python
     class TodoPrinter(Component):
         implements(ITodoObserver)
@@ -126 +132 @@
 
 {{{
+#!python
     comp_mgr = ComponentManager()
     todo_list = TodoList(comp_mgr)
@@ -146 +153 @@
 This output obviously comes from the `TodoPrinter`. Note however that the code snippet above doesn't even mention that class. All that is needed to have it participating in the action is to declare the class. ''(That implies that an extending class needs to be imported by a python script to be registered. The aspect of loading components is however separate from the extension mechanism itself.)''
 
+== How Trac Uses Components ==
+
+The typical use of components in Trac starts with a top-level “service provider” that we'll pick up and use directly. Take, for example, {{{trac.perm.PermissionSystem}}}: 
+{{{
+#!python
+permission_system = trac.perm.PermissionSystem()
+actions = permission_system.get_permission_actions()
+}}}
+
+These are the first few lines of {{{PermissionSystem}}} as of r5790 (or [browser:trunk/trac/perm.py:r5790#L230 in context]):
+{{{
+#!python
+class PermissionSystem(Component):
+    """Sub-system that manages user permissions."""
+
+    implements(IPermissionRequestor)
+
+    requestors = ExtensionPoint(IPermissionRequestor)
+}}}
+
+Note that it has a list of extension points implementing {{{IPermissionRequestor}}} ([browser:trunk/trac/perm.py:r5790#L40 in context]):
+{{{
+#!python
+class IPermissionRequestor(Interface):
+    """Extension point interface for components that define actions."""
+
+    def get_permission_actions():
+        """Return a list of actions defined by this component."""
+}}}
+
+  ''Note that interface authors have not always been consistent about declaring the "{{{self}}}" parameter in signatures.''
+
+When we use {{{PermissionSystem}}}, the plugin system will have automatically gathered up all implementations of {{{IPermissionRequestor}}} and placed them in {{{PermissionSystem}}}'s list of {{{requestors}}}.
+
+ '''Notes that I hope a Trac dev will check:'''
+   * ''As far as I understand,the line in {{{PermissionSystem}}} that declares it to implement {{{IPermissionRequestor}}} is completely superfluous except for documentation purposes, because it will always be used directly''
+   * ''Does something avoid putting {{{PermissionSystem}}} in its own list?'' [[br]]—dave 
+
+Next in {{{PermissionSystem}}} there is a declaration of an {{{ExtensionOption}}} called {{{store}}}:
+{{{
+#!python
+    store = ExtensionOption('trac', 'permission_store', IPermissionStore,
+                            'DefaultPermissionStore',
+        """Name of the component implementing `IPermissionStore`, which is used
+        for managing user and group permissions.""")
+
+}}}
+The above adds an option called {{{permission_store}}} to {{{trac.ini}}}, declares that the component named by the option implements {{{IPermissionStore}}}, and sets its default to {{{DefaultPermissionStore}}}.  See [browser:trunk/trac/config.py trac.config] for {{{ExtensionOption}}} and friends.  Methods of service providers such as {{{PermissionSystem}}} are commonly a thin forwarding layer over such an {{{ExtensionOption}}}.  For example:
+{{{
+#!python
+    def get_all_permissions(self):
+        """Return all permissions for all users.
+
+        The permissions are returned as a list of (subject, action)
+        formatted tuples."""
+        return self.store.get_all_permissions()
+}}}
+Thus, service providers are directly manipulated from Python, and are customized through the automatic aggregation of components implementing {{{ExtensionPoint}}}s and through configuration of {{{ExtensionOption}}}s by Trac administrators.
+
 ----
 See also: TracDev