Introduce on_exception handler.

ChangeLog

@@ -1,6 +1,12 @@
 CHANGES
 =======
 
+0.9.4
+-----
+
+* Add on_exception parameter accepting a handler called when exception is captured.
+  The callback can also be used to handle the exception and interrupt further retries.
+
 0.9.3
 -----
 

README.rst

@@ -40,7 +40,8 @@ retry decorator
 
 .. code:: python
 
-    def retry(exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1, jitter=0, logger=logging_logger):
+    def retry(exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1, jitter=0, logger=logging_logger,
+              on_exception=None):
         """Return a retry decorator.
 
         :param exceptions: an exception or a tuple of exceptions to catch. default: Exception.
@@ -52,6 +53,9 @@ retry decorator
                        fixed if a number, random if a range tuple (min, max)
         :param logger: logger.warning(fmt, error, delay) will be called on failed attempts.
                        default: retry.logging_logger. if None, logging is disabled.
+        :param on_exception: handler called when exception occurs. will be passed the captured
+                             exception as an argument. further retries are stopped when handler
+                             returns True. default: None
         """
 
 Various retrying logic can be achieved by combination of arguments.
@@ -109,8 +113,7 @@ retry_call
 .. code:: python
 
     def retry_call(f, fargs=None, fkwargs=None, exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1,
-                   jitter=0,
-                   logger=logging_logger):
+                   jitter=0, logger=logging_logger, on_exception=None):
         """
         Calls a function and re-executes it if it failed.
 
@@ -126,6 +129,9 @@ retry_call
                        fixed if a number, random if a range tuple (min, max)
         :param logger: logger.warning(fmt, error, delay) will be called on failed attempts.
                        default: retry.logging_logger. if None, logging is disabled.
+        :param on_exception: handler called when exception occurs. will be passed the captured
+                             exception as an argument. further retries are stopped when handler
+                             returns True. default: None
         :returns: the result of the f function.
         """
 

retry/api.py

@@ -10,7 +10,7 @@
 
 
 def __retry_internal(f, exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1, jitter=0,
-                     logger=logging_logger, log_traceback=False):
+                     logger=logging_logger, log_traceback=False, on_exception=None):
     """
     Executes a function and retries it if it failed.
 
@@ -24,13 +24,20 @@ def __retry_internal(f, exceptions=Exception, tries=-1, delay=0, max_delay=None,
                    fixed if a number, random if a range tuple (min, max)
     :param logger: logger.warning(fmt, error, delay) will be called on failed attempts.
                    default: retry.logging_logger. if None, logging is disabled.
+    :param on_exception: handler called when exception occurs. will be passed the captured
+                         exception as an argument. further retries are stopped when handler
+                         returns True. default: None
     :returns: the result of the f function.
     """
     _tries, _delay = tries, delay
     while _tries:
         try:
             return f()
         except exceptions as e:
+            if on_exception is not None:
+                if on_exception(e):
+                    break
+
             _tries -= 1
             if not _tries:
                 raise
@@ -58,7 +65,7 @@ def __retry_internal(f, exceptions=Exception, tries=-1, delay=0, max_delay=None,
 
 
 def retry(exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1, jitter=0, logger=logging_logger,
-          log_traceback=False):
+          log_traceback=False, on_exception=None):
     """Returns a retry decorator.
 
     :param exceptions: an exception or a tuple of exceptions to catch. default: Exception.
@@ -70,6 +77,9 @@ def retry(exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1, ji
                    fixed if a number, random if a range tuple (min, max)
     :param logger: logger.warning(fmt, error, delay) will be called on failed attempts.
                    default: retry.logging_logger. if None, logging is disabled.
+    :param on_exception: handler called when exception occurs. will be passed the captured
+                         exception as an argument. further retries are stopped when handler
+                         returns True. default: None
     :returns: a retry decorator.
     """
 
@@ -78,13 +88,13 @@ def retry_decorator(f, *fargs, **fkwargs):
         args = fargs if fargs else list()
         kwargs = fkwargs if fkwargs else dict()
         return __retry_internal(partial(f, *args, **kwargs), exceptions, tries, delay, max_delay, backoff, jitter,
-                                logger, log_traceback=log_traceback)
+                                logger, log_traceback, on_exception)
 
     return retry_decorator
 
 
 def retry_call(f, fargs=None, fkwargs=None, exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1,
-               jitter=0, logger=logging_logger, log_traceback=False):
+               jitter=0, logger=logging_logger, log_traceback=False, on_exception=None):
     """
     Calls a function and re-executes it if it failed.
 
@@ -100,9 +110,12 @@ def retry_call(f, fargs=None, fkwargs=None, exceptions=Exception, tries=-1, dela
                    fixed if a number, random if a range tuple (min, max)
     :param logger: logger.warning(fmt, error, delay) will be called on failed attempts.
                    default: retry.logging_logger. if None, logging is disabled.
+    :param on_exception: handler called when exception occurs. will be passed the captured
+                         exception as an argument. further retries are stopped when handler
+                         returns True. default: None
     :returns: the result of the f function.
     """
     args = fargs if fargs else list()
     kwargs = fkwargs if fkwargs else dict()
     return __retry_internal(partial(f, *args, **kwargs), exceptions, tries, delay, max_delay, backoff, jitter, logger,
-                            log_traceback=log_traceback)
+                            log_traceback, on_exception)

tests/test_retry.py

@@ -189,6 +189,17 @@ def f(value=0):
     assert f_mock.call_count == 1
 
 
+def test_call_on_exception():
+    exception = RuntimeError()
+    f_mock = MagicMock(side_effect=exception)
+    callback_mock = MagicMock()
+    try:
+        retry_call(f_mock, tries=1, on_exception=callback_mock)
+    except RuntimeError:
+        pass
+    callback_mock.assert_called_once_with(exception)
+
+
 def test_logs_function_details(monkeypatch):
     mock_sleep_time = [0]