X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=mediagoblin%2Ftools%2Fpluginapi.py;h=3f98aa8a5f751415f3f181658c4bb1dfe23d1b5a;hb=c33a34d45964a7e49a5eeeabde0ef4a8132ac591;hp=283350a8eb0289207363ba9a419e152ddaf9b3d7;hpb=0a5c6ec9011f678d9759183cb22e747d1084769f;p=mediagoblin.git

diff --git a/mediagoblin/tools/pluginapi.py b/mediagoblin/tools/pluginapi.py
index 283350a8..3f98aa8a 100644
--- a/mediagoblin/tools/pluginapi.py
+++ b/mediagoblin/tools/pluginapi.py
@@ -274,68 +274,94 @@ def get_hook_templates(hook_name):
     return PluginManager().get_template_hooks(hook_name)
 
 
-###########################
-# Callable convenience code
-###########################
+#############################
+## Hooks: The Next Generation
+#############################
 
-class CantHandleIt(Exception):
-    """
-    A callable may call this method if they look at the relevant
-    arguments passed and decide it's not possible for them to handle
-    things.
-    """
-    pass
 
-class UnhandledCallable(Exception):
-    """
-    Raise this method if no callables were available to handle the
-    specified hook.  Only used by callable_runone.
+def hook_handle(hook_name, *args, **kwargs):
     """
-    pass
+    Run through hooks attempting to find one that handle this hook.
 
+    All callables called with the same arguments until one handles
+    things and returns a non-None value.
 
-def callable_runone(hookname, *args, **kwargs):
-    """
-    Run the callable hook HOOKNAME... run until the first response,
-    then return.
+    (If you are writing a handler and you don't have a particularly
+    useful value to return even though you've handled this, returning
+    True is a good solution.)
 
-    This function will run stop at the first hook that handles the
-    result.  Hooks raising CantHandleIt will be skipped.
+    Note that there is a special keyword argument:
+      if "default_handler" is passed in as a keyword argument, this will
+      be used if no handler is found.
 
-    Unless unhandled_okay is True, this will error out if no hooks
-    have been registered to handle this function.
+    Some examples of using this:
+     - You need an interface implemented, but only one fit for it
+     - You need to *do* something, but only one thing needs to do it.
     """
-    callables = PluginManager().get_hook_callables(hookname)
+    default_handler = kwargs.pop('default_handler', None)
+
+    callables = PluginManager().get_hook_callables(hook_name)
 
-    unhandled_okay = kwargs.pop("unhandled_okay", False)
+    result = None
 
     for callable in callables:
-        try:
-            return callable(*args, **kwargs)
-        except CantHandleIt:
-            continue
+        result = callable(*args, **kwargs)
 
-    if unhandled_okay is False:
-        raise UnhandledCallable(
-            "No hooks registered capable of handling '%s'" % hookname)
+        if result is not None:
+            break
 
+    if result is None and default_handler is not None:
+        result = default_handler(*args, **kwargs)
+
+    return result
 
-def callable_runall(hookname, *args, **kwargs):
-    """
-    Run all callables for HOOKNAME.
 
-    This method will run *all* hooks that handle this method (skipping
-    those that raise CantHandleIt), and will return a list of all
-    results.
+def hook_runall(hook_name, *args, **kwargs):
+    """
+    Run through all callable hooks and pass in arguments.
+
+    All non-None results are accrued in a list and returned from this.
+    (Other "false-like" values like False and friends are still
+    accrued, however.)
+
+    Some examples of using this:
+     - You have an interface call where actually multiple things can
+       and should implement it
+     - You need to get a list of things from various plugins that
+       handle them and do something with them
+     - You need to *do* something, and actually multiple plugins need
+       to do it separately
     """
-    callables = PluginManager().get_hook_callables(hookname)
+    callables = PluginManager().get_hook_callables(hook_name)
 
     results = []
 
     for callable in callables:
-        try:
-            results.append(callable(*args, **kwargs))
-        except CantHandleIt:
-            continue
+        result = callable(*args, **kwargs)
+
+        if result is not None:
+            results.append(result)
 
     return results
+
+
+def hook_transform(hook_name, arg):
+    """
+    Run through a bunch of hook callables and transform some input.
+
+    Note that unlike the other hook tools, this one only takes ONE
+    argument.  This argument is passed to each function, which in turn
+    returns something that becomes the input of the next callable.
+
+    Some examples of using this:
+     - You have an object, say a form, but you want plugins to each be
+       able to modify it.
+    """
+    result = arg
+
+    callables = PluginManager().get_hook_callables(hook_name)
+
+    for callable in callables:
+        result = callable(result)
+
+    return result