From b617873a991d7989f06694de3596911d6fdac4a8 Mon Sep 17 00:00:00 2001 From: Chris Yeoh Date: Fri, 21 Jun 2013 13:55:00 +0930 Subject: [PATCH] Update docstrings for map exception propagation Updates docstrings related to map exception propagation and the history.rst file --- docs/source/history.rst | 6 +++++- stevedore/dispatch.py | 17 ++++++++++++++--- stevedore/enabled.py | 4 ++++ stevedore/extension.py | 8 +++++++- stevedore/named.py | 4 ++++ 5 files changed, 34 insertions(+), 5 deletions(-) diff --git a/docs/source/history.rst b/docs/source/history.rst index 0c6fe3b..8e6589f 100644 --- a/docs/source/history.rst +++ b/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 - Add ``name_order`` parameter to :class:`~stevedore.named.NamedExtensionManager` to coerce :func:`map` into processing the extensions in the order they are diff --git a/stevedore/dispatch.py b/stevedore/dispatch.py index f96e731..53b11e7 100644 --- a/stevedore/dispatch.py +++ b/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. diff --git a/stevedore/enabled.py b/stevedore/enabled.py index 0c96a1b..5cb0033 100644 --- a/stevedore/enabled.py +++ b/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 """ diff --git a/stevedore/extension.py b/stevedore/extension.py index 063cf1a..8e7801e 100644 --- a/stevedore/extension.py +++ b/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() diff --git a/stevedore/named.py b/stevedore/named.py index 63ee386..e4cf857 100644 --- a/stevedore/named.py +++ b/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,