The API¶
This part of the documentation covers all the interfaces of polling2. polling2 depends on no external libraries and should run any version of python 2 or 3.
Poll Method¶
The main method is the poll method.
- polling2.poll(target, step, args=(), kwargs=None, timeout=None, max_tries=None, check_success=<function is_truthy>, step_function=<function step_constant>, ignore_exceptions=(), poll_forever=False, collect_values=None, log=0, log_error=0)[source]¶
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.
- Parameters:
step – Step defines the amount of time to wait (in seconds)
args – Arguments to be passed to the target function
kwargs (dict) – Keyword arguments to be passed to the target function
timeout – The target function will be called until the time elapsed is greater than the maximum timeout (in seconds). NOTE timeout == 0 or timeout == None is equivalent to setting poll_forever=True. NOTE that the actual execution time of the function can exceed the time specified in the timeout. For instance, if the target function takes 10 seconds to execute and the timeout is 21 seconds, the polling function will take a total of 30 seconds (two iterations of the target –20s which is less than the timeout–21s, and a final iteration).
max_tries – Maximum number of times the target function will be called before failing
check_success – A callback function that accepts the return value of the target function. It should return true if you want the polling function to stop and return this value. It should return false if you want it to continue executing. The default is a callback that tests for truthiness (anything not False, 0, or empty collection).
step_function –
A callback function that accepts each iteration’s “step.” By default, this is constant, but you can also pass a function that will increase or decrease the step. As an example, you can increase the wait time between calling the target function by 10 seconds every iteration until the step is 100 seconds–at which point it should remain constant at 100 seconds
>>> def my_step_function(step): >>> step += 10 >>> return max(step, 100)
ignore_exceptions (tuple) – You can specify a tuple of exceptions that should be caught and ignored on every iteration. If the target function raises one of these exceptions, it will be caught and the exception instance will be pushed to the queue of values collected during polling. Any other exceptions raised will be raised as normal.
poll_forever – If set to true, this function will retry until an exception is raised or the target’s return value satisfies the check_success function. If this is not set, then a timeout or a max_tries must be set.
collect_values (Queue) – By default, polling will create a new Queue to store all of the target’s return values. Optionally, you can specify your own queue to collect these values for access to it outside of function scope.
log (int or str, one of logging._levelNames) – (optional) By default, return values passed to check_success are not logged. However, if this param is 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.
log_level – (optional) 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.
- Returns:
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.
Note: a message is written to polling2 logger when poll() is called. This logs a message like so:
>>> Begin poll(target=<>, step=<>, timeout=<>, max_tries=<>, poll_forever=<>)
This message should allow a user to work-out how long the poll could take, and thereby detect a hang in real-time if the poll takes longer than it should.
Poll Decorator¶
There is also an equivalent decorator method. It’s interface is essentially the same as poll(). But benefits from allowing you to write the polling functionality with decorator syntax.
Helper Methods¶
There are some other supplemental methods that can help out.
- polling2.step_constant(step)[source]¶
Use this function when you want the step to remain fixed in every iteration (typically good for instances when you know approximately how long the function should poll for)
- Parameters:
step – a number
- Returns:
step
- polling2.step_linear_double(step)[source]¶
Use this function when you want the step to double each iteration (e.g. like the way ArrayList works in Java). Note that this can result in very long poll times after a few iterations
- Parameters:
step – a number, that is doubled
- Returns:
double of step
- polling2.is_truthy(val)[source]¶
Use this function to test if a return value is truthy
- Returns:
boolean
- polling2.is_value(val)[source]¶
Use this function to create a custom checker.
- Parameters:
val – Whatever val is, the checker checks that whatever is returned from that target is that value.
- Returns:
checker function testing if parameter is val, call checker to get a boolean
- polling2.log_value(check_success, level=10)[source]¶
A decorator for a check_success function that logs the return_value passed to check_success.
- Parameters:
level – (optional) the level at which to log the return value, defaults to debug. Must be one of the values in logging._levelNames (i.e. an int or a string).
- Returns:
decorator check_success function.
Exceptions¶
- exception polling2.PollingException(values, last=None)[source]¶
Base exception that stores all return values of attempted polls
