Update docstrings for map exception propagation

Updates docstrings related to map exception propagation
and the history.rst file

docs/source/history.rst

@@ -3,7 +3,11 @@
 =========
 
 0.9
-
+- Adds ``propagate_map_exceptions`` parameter to all of the extension
+  managers which specifies whether exceptions are propagated up 
+  through the map call or logged and then ignored. The default is to
+  preserve the current behavior of logging and ignoring exceptions.
+  Christopher Yeoh <cyeoh@au1.ibm.com>
 - Add ``name_order`` parameter to
   :class:`~stevedore.named.NamedExtensionManager` to coerce
   :func:`map` into processing the extensions in the order they are

stevedore/dispatch.py

@@ -26,6 +26,10 @@ class DispatchExtensionManager(EnabledExtensionManager):
         the object returned by the entry point. Only used if invoke_on_load
         is True.
     :type invoke_kwds: dict
+    :param propagate_map_exceptions: Boolean controlling whether exceptions
+        are propagated up through the map call or whether they are logged and
+        then ignored
+    :type invoke_on_load: bool
     """
 
     def map(self, filter_func, func, *args, **kwds):
@@ -50,8 +54,9 @@ class DispatchExtensionManager(EnabledExtensionManager):
         The first argument to func(), 'ext', is the
         :class:`~stevedore.extension.Extension` instance.
 
-        Exceptions raised from within filter_func() and func() are
-        logged and ignored.
+        Exceptions raised from within func() are propagated up and
+        processing stopped if self.propagate_map_exceptions is True,
+        otherwise they are logged and ignored.
 
         :param filter_func: Callable to test each extension.
         :param func: Callable to invoke for each extension.
@@ -95,6 +100,10 @@ class NameDispatchExtensionManager(DispatchExtensionManager):
         the object returned by the entry point. Only used if invoke_on_load
         is True.
     :type invoke_kwds: dict
+    :param propagate_map_exceptions: Boolean controlling whether exceptions
+        are propagated up through the map call or whether they are logged and
+        then ignored
+    :type invoke_on_load: bool
 
     """
 
@@ -123,7 +132,9 @@ class NameDispatchExtensionManager(DispatchExtensionManager):
         The first argument to func(), 'ext', is the
         :class:`~stevedore.extension.Extension` instance.
 
-        Exceptions raised from within func() are logged and ignored.
+        Exceptions raised from within func() are propagated up and
+        processing stopped if self.propagate_map_exceptions is True,
+        otherwise they are logged and ignored.
 
         :param names: List or set of name(s) of extension(s) to invoke.
         :param func: Callable to invoke for each extension.

stevedore/enabled.py

@@ -28,6 +28,10 @@ class EnabledExtensionManager(ExtensionManager):
         the object returned by the entry point. Only used if invoke_on_load
         is True.
     :type invoke_kwds: dict
+    :param propagate_map_exceptions: Boolean controlling whether exceptions
+        are propagated up through the map call or whether they are logged and
+        then ignored
+    :type invoke_on_load: bool
 
     """
 

stevedore/extension.py

@@ -51,6 +51,10 @@ class ExtensionManager(object):
         the object returned by the entry point. Only used if invoke_on_load
         is True.
     :type invoke_kwds: dict
+    :param propagate_map_exceptions: Boolean controlling whether exceptions
+        are propagated up through the map call or whether they are logged and
+        then ignored
+    :type invoke_on_load: bool
 
     """
 
@@ -119,7 +123,9 @@ class ExtensionManager(object):
         The first argument to func(), 'ext', is the
         :class:`~stevedore.extension.Extension` instance.
 
-        Exceptions raised from within func() are logged and ignored.
+        Exceptions raised from within func() are propagated up and
+        processing stopped if self.propagate_map_exceptions is True,
+        otherwise they are logged and ignored.
 
         :param func: Callable to invoke for each extension.
         :param args: Variable arguments to pass to func()

stevedore/named.py

@@ -25,6 +25,10 @@ class NamedExtensionManager(ExtensionManager):
     :param name_order: If true, sort the loaded extensions to match the
         order used in ``names``.
     :type name_order: bool
+    :param propagate_map_exceptions: Boolean controlling whether exceptions
+        are propagated up through the map call or whether they are logged and
+        then ignored
+    :type invoke_on_load: bool
     """
 
     def __init__(self, namespace, names,