progression.decorators module

Implements decorators/wrappers for simple use-cases of jobmanager.

class progression.decorators.ProgressBar(func, **kwargs)

Bases: object

A wrapper/decorator with a text-based progress bar.

Methods: - __init__ - __call__

The idea is to add a status bar for a regular function just by wrapping the function via python’s decorator syntax.

In order to do so, the function needs to provide some extra information, namely the current state ‘count’ and the final state ‘max_count’. Simply expand your function by these two additional keyword arguments (or other pairs specified in jobmanager.validCountKwargs) and set their values during the calculation (see example 1 below). In that manner the decorated function as well as the not decorated function can simple be called as one would not care about any status information.

Alternatively one could explicitly set count and max_count in the function call, which circumvents the need to change the value of max_count AFTER instantiation of the progressBar.

>>> from jobmanager.decorators import ProgressBar
>>> from jobmanager.decorators.progress import UnsignedIntValue
>>> import time
>>> 
>>> @ProgressBar
>>> def my_func_1(arg, 
>>>               kwarg     = "1", 
>>>               count     = UnsignedIntValue(val=0), 
>>>               max_count = UnsignedIntValue(val=1)):
>>>     # max_count should as default always be set to a value > 0 
>>>     maxval = 100
>>>     max_count.value = maxval
>>> 
>>>     for i in range(maxval):
>>>         count.value += 1
>>>         time.sleep(0.02)
>>> 
>>>     return arg+kwarg
>>> 
>>> my_func_1("one argument", kwarg=" second argument")
# The progress of my_func is monitored on stdout.
one argument second argument

>>> from jobmanager.decorators import ProgressBar
>>> from jobmanager.decorators.progress import UnsignedIntValue
>>> import time
>>> 
>>> @ProgressBar
>>> def my_func(c, m):
>>>     for i in range(m.value):
>>>         c.value = i
>>>         time.sleep(0.02)
>>>             
>>> c = progress.UnsignedIntValue(val=0)
>>> m = progress.UnsignedIntValue(val=100)
>>> my_func(c, m)

You can also use this class as a wrapper and tune parameters of the progress bar.

>>> wrapper = ProgressBar(my_func, interval=.1)
>>> result = wrapper("wrapped function", kwarg=" test")

class progression.decorators.ProgressBarExtended(func, **kwargs)

Bases: progression.decorators.ProgressBar

extends the ProgressBar such that one can turn of the ProgressBar by giving an extra argument, namely ‘progress_bar_off’ and set its value to ‘True’.

Further there will be an additional argument passed to the function called ‘progress_bar’ which allows to stop the progress bar from within the function. note that there will be an function signature error if the function does not accept the extra argument ‘progress_bar’. So a general **kwargs at the end of the functions arguments will help. That is also the reason why the extended version comes in an extra class because it might otherwise break compatibility.

>>> import jobmanager as jm

>>> c = jm.progress.UnsignedIntValue(val=0)
>>> m = jm.progress.UnsignedIntValue(val=20)

>>> @jm.decorators.ProgressBarExtended    # choose 'ProgressBarExtended'
>>> def my_func_kwargs(c, m, **kwargs):   # simply add '**kwargs' here
>>>     for i in range(m.value):
>>>         c.value = i+1
>>>         time.sleep(0.1)

>>> # same as when using ProgressBar
>>> my_func_kwargs(c, m)

>>> # a simple kwarg will switch the progressBar off
>>> my_func_kwargs(c, m, progress_bar_off=True)

class progression.decorators.ProgressBarOverrideCount(func, **kwargs)

Bases: progression.decorators.ProgressBar