Merge pull request #4884 from ckan/chain-better-docs

Improved docs for chained action functions

CHANGELOG.rst

@@ -376,6 +376,7 @@ Major changes:
  * Common requests code for Flask and Pylons (#3212)
  * Generate complete datastore dump files (#3344)
  * A new system for asynchronous background jobs (#3165)
+ * Chaining of action functions (#3494)
 
 Minor changes:
  * Renamed example theme plugin (#3576)

ckan/logic/__init__.py

@@ -413,9 +413,9 @@ def get_action(action):
     fetched_actions = {}
     chained_actions = defaultdict(list)
     for plugin in p.PluginImplementations(p.IActions):
-        for name, auth_function in plugin.get_actions().items():
-            if _is_chained_action(auth_function):
-                chained_actions[name].append(auth_function)
+        for name, action_function in plugin.get_actions().items():
+            if _is_chained_action(action_function):
+                chained_actions[name].append(action_function)
             elif name in resolved_action_plugins:
                 raise NameConflict(
                     'The action %r is already implemented in %r' % (
@@ -427,8 +427,8 @@ def get_action(action):
                 resolved_action_plugins[name] = plugin.name
                 # Extensions are exempted from the auth audit for now
                 # This needs to be resolved later
-                auth_function.auth_audit_exempt = True
-                fetched_actions[name] = auth_function
+                action_function.auth_audit_exempt = True
+                fetched_actions[name] = action_function
     for name, func_list in chained_actions.iteritems():
         if name not in fetched_actions and name not in _actions:
             # nothing to override from plugins or core

ckan/plugins/interfaces.py

@@ -917,15 +917,19 @@ def get_actions(self):
         request (as well as the usual POST request) through the Action API.
 
         By decorating a function with 'ckan.plugins.toolkit.chained_action`,
-        the action will be chained to another function defined in plugins with
-        a "first plugin wins" pattern, which means the first plugin declaring a
-        chained action should be called first. Chained actions must be
-        defined as `action_function(original_action, context, data_dict)`,
-        where the first parameter will be set to the action function in
-        the next plugin or in core ckan. The chained action may call the
-        original_action function, optionally passing different values,
-        handling exceptions, returning different values and/or raising
-        different exceptions to the caller.
+        the action will 'intercept' calls to an existing action function. This
+        allows a plugin to modify the behaviour of an existing action function.
+        Chained actions must be defined as
+        `action_function(original_action, context, data_dict)`, where the
+        function's name matches the original action function it intercepts, the
+        first parameter is the action function it intercepts (in the next
+        plugin or in core ckan). The chained action may call the
+        original_action function, optionally passing different values, handling
+        exceptions, returning different values and/or raising different
+        exceptions to the caller. When multiple plugins chain to an action, the
+        first plugin declaring is called first, and if it chooses to call the
+        original_action, then the chained action in the next plugin to be
+        declared next is called, and so on.
         '''