Merge pull request #6 from ddmee/log_errors

Add log_errors parameter to the poll() function.

Author: ddmee

README.md

@@ -6,15 +6,22 @@
 polling2
 =============
 
+_Never write another polling function again!_
+
 Polling2 is a powerful python utility used to wait for a function to return a certain expected condition.
+
 Some possible uses cases include:
 
 - Wait for API response to return with code 200
 - Wait for a file to exist (or not exist)
 - Wait for a thread lock on a resource to expire
 
+Polling2 is handy for getting rid of all that duplicated polling-code. Often, applications require retrying until the correct response is returned. Why re-implement the ability to poll again and again? Use Polling2!
+
 Polling2 is a fork of the original [polling](https://github.com/justiniso/polling). It was forked when the original maintainer failed to respond to issues or PRs. 
 
+Polling2 is ++under active development++. Would you like to see a particular feature? Ask and thou shall recieve.
+
 # Installation
 
 ```
@@ -23,7 +30,7 @@ pip install polling2
 
 # Development installation
 
-```
+```shell
 # install lib, but use system links from the repo into sitepackages.
 python setup.py develop
 # install test dependenices.
@@ -139,12 +146,50 @@ This will log the string representation of response object to python's logging m
 A message like this will be sent to the log for each return value. You can change the level by providing
 a different value to the log parameter.
 
-```
+```text
 poll() calls check_success(<Response [200]>)
 ```
 
+There is also an option to log the exceptions that are caught by ignore_exceptions. Note, the full-exception traceback
+will not be printed in the logs. Instead, the error and it's message (using %r formatting) will appear. In the following
+code snippet, the ValueError raised by the function `raises_error()` will be sent to the logger at the 'warning' level.
+
+```python
+import polling2
+import logging
+import mock
+
+# basicConfig should sent warning level messages to the stdout.
+logging.basicConfig()
+
+# Create a function that raises a ValueError, then a RuntimeError.
+raises_error = mock.Mock(side_effect=[ValueError('a message'), RuntimeError])
+
+try:
+    polling2.poll(
+        target=raises_error,
+        step=0.1,
+        max_tries=3,
+        ignore_exceptions=(ValueError),  # Only ignore the ValueError.
+        log_error=logging.WARNING  # Ignored errors should be passed to the logger at warning level.
+    )
+except RuntimeError as _e:
+    print "Un-ignored %r" % _e``
+```
+ 
+# Future extensions
+
+- Add poll_killer(). Specify a hard timeout so that if the function being polled blocks and doesn't return, poll_killer() will raise a timeout.
+  - Add an option to do via multiprocessing.
+  - Add an option to do via threading - probably the default option.
+- Add poll_chain(). Have reason to poll a bunch of functions in a row? poll_chain() allows you to chain a bunch of polling functions together.
+- Allow step to be specificed as 0, so that we can poll continously. (Perhaps it's best to write a poll_continous() method.)
+
 # Release notes
 
+## 0.4.3 
+- Add log_error parameter to the poll signature. Enables logging of ignored exceptions.
+
 ## 0.4.2
 - Add log_value() decorator and log parameter to poll signature. Enables logging of return_values.
 
@@ -170,4 +215,4 @@ poll() calls check_success(<Response [200]>)
 
 # Contributors
 - Justin Iso (original creator)
-- Donal Mee
+- Donal Mee

polling2.py

@@ -1,6 +1,10 @@
-"""Polling2 module containing all exceptions and helpers used for the polling function"""
+"""Polling2 module containing all exceptions and helpers used for the polling function
 
-__version__ = '0.4.2'
+Never write another polling function again.
+
+"""
+
+__version__ = '0.4.3'
 
 import logging
 import time
@@ -61,7 +65,7 @@ def wrap_check_success(return_val):
 
 def poll(target, step, args=(), kwargs=None, timeout=None, max_tries=None, check_success=is_truthy,
          step_function=step_constant, ignore_exceptions=(), poll_forever=False, collect_values=None,
-         log=logging.NOTSET):
+         log=logging.NOTSET, log_error=logging.NOTSET):
     """Poll by calling a target function until a certain condition is met. You must specify at least a target
     function to be called and the step -- base wait time between each function call.
 
@@ -112,6 +116,13 @@ def poll(target, step, args=(), kwargs=None, timeout=None, max_tries=None, check
     set to a log level greater than NOTSET, then the return values passed to check_success will be logged.
     This is done by using the decorator log_value.
 
+    :type log_error: int or str, one of logging._levelNames
+    :opt param log_level: If ignore_exception has been set, you might want to log the exceptions that are
+    ignored. If the log_error level is greater than NOTSET, then any caught exceptions will be logged at that
+    level. Note: the logger.exception() function is not used. That would print the stacktrace in the logs. Because
+    you are ignoring these exceptions, it seems unlikely that'd you'd want a full stack trace for each exception.
+    However, if you do what this, you can retrieve the exceptions using the collect_values parameter.
+
     :return: Polling will return first value from the target function that meets the condions of the check_success
     callback. By default, this will be the first value that is not None, 0, False, '', or an empty collection.
     """
@@ -143,6 +154,10 @@ def poll(target, step, args=(), kwargs=None, timeout=None, max_tries=None, check
             last_item = val
         except ignore_exceptions as e:
             last_item = e
+
+            if log_error: # NOTSET is 0, so it'll evaluate to False.
+                LOGGER.log(log_error, "poll() ignored exception %r", e)
+
         else:
             # Condition passes, this is the only "successful" exit from the polling function
             if check_success(val):

tests/test_polling2.py

@@ -3,7 +3,7 @@
 import time
 import unittest
 
-from mock import patch
+from mock import patch, Mock
 import pytest
 
 import polling2
@@ -95,6 +95,20 @@ def test_max_call_no_sleep(self):
             polling2.poll(lambda: False, step=sleep, max_tries=tries)
         assert time.time() - start_time < tries * sleep, 'Poll function slept before MaxCallException'
 
+    def test_ignore_specified_exceptions(self):
+        """
+        Test that ignore_exceptions tuple will ignore exceptions specified.
+        Should throw any errors not in the tuple.
+        """
+        # raises_errors is a function that returns 3 different things, each time it is called.
+        # First it raises a ValueError, then EOFError, then a TypeError.
+        raises_errors = Mock(return_value=True, side_effect=[ValueError, EOFError, RuntimeError])
+        with pytest.raises(RuntimeError):
+            # We are ignoring the exceptions other than a TypeError.
+            polling2.poll(target=raises_errors, step=0.1, max_tries=3,
+                          ignore_exceptions=(ValueError, EOFError))
+        assert raises_errors.call_count == 3
+
 
 @pytest.mark.skipif(is_py_34(), reason="pytest logcap fixture isn't available on 3.4")
 class TestPollLogging(object):
@@ -128,3 +142,34 @@ def test_default_is_not_log(self, caplog):
         with caplog.at_level(logging.DEBUG):
             polling2.poll(target=lambda: True, step=0.1, max_tries=1)
             assert len(caplog.records) == 0, "Should not be any log records"
+
+    def test_log_error_default_is_not_log(self, caplog):
+        """
+        Shouldn't log anything unless explicitly asked to do so.
+        """
+        raises_errors = Mock(side_effect=ValueError('msg is this'))
+        with caplog.at_level(logging.DEBUG), pytest.raises(polling2.MaxCallException):
+            polling2.poll(target=raises_errors, ignore_exceptions=(ValueError),
+                          step=0.1, max_tries=2)
+            assert len(caplog.records) == 0, "Wrong number of log records."
+            # Test that logging.NOTSET does not print log records either.
+            polling2.poll(target=raises_errors, ignore_exceptions=(ValueError),
+                          step=0.1, max_tries=2, log_error=logging.NOTSET)
+            assert len(caplog.records) == 0, "Wrong number of log records."
+
+    def test_log_error_set_at_debug_level(self, caplog):
+        """
+        Test that when the log_error parameter is set to debug level, the ignored
+        errors are sent to the logger.
+        """
+        raises_errors = Mock(side_effect=[ValueError('msg this'), RuntimeError('this msg')])
+        with caplog.at_level(logging.DEBUG), pytest.raises(polling2.MaxCallException):
+            polling2.poll(target=raises_errors, ignore_exceptions=(ValueError, RuntimeError),
+                          step=0.1, max_tries=2, log_error=logging.DEBUG)
+        assert len(caplog.records) == 2, "Wrong number of log records."
+        assert caplog.records[0].message == "poll() ignored exception ValueError('msg this',)"
+        assert caplog.records[1].message == "poll() ignored exception RuntimeError('this msg',)"
+
+
+
+