progress

This module offers different methods for showing the current status of an iterative algorithm, or to control its execution, for example to abort it as soon as certain abort criterions are met.

Classes

class progress.Bar(nstep=1, text='progress', width=None, verbose=True, etc=True)[source]

Display a progress bar when executing a loop with a fixed number of iterations.

Usage:

Instantiate this class before loop. Call the method step() at the end of each loop (do not forget to do the same before any occurence of continue). If the loop is left early (i.e., if break is called), or if you want to make sure the line break is done after the loop, call the method end(). To reset the counter, call the method reset().

On initialization, the number of iterations nstep must be specified. Additional keyword arguments include:

text
User-defined text message (instead of “Progress”).
width
Width of the current shell window. Default: 80.
verbose
If set to False, the progress bar is not displayed.
etc
If set to True, show “Estimated Time to Complete”. The remaining time the loop will need to finish is calculated by linear extrapolation of the time that already passed since the loop has been entered.

This class is meant to be used in loops where the number of iteration steps is already known before entering the loop (i.e., for-loops). This excludes all iterative algorithms that leave the loop on some convergence criterions after a variable number of steps (e.g., while-loops). Of course, the number of loops that will probably be used could be estimated, but this is not the way this class is intended to be used. See the class OpenBar for that.

end()[source]

Leave the progress bar, insert a line break on the screen.

jump(howmany=1)[source]

Skip one or several steps. Using this instead of step() is only important for the correct calculation of the estimated time to complete (ETC).

reset()[source]

Reset the counter, start over with the progress bar.

step(howmany=1)[source]

Move one or several steps forward.

write()[source]

Update the progress bar on the screen.

class progress.Monitor(**kwargs)[source]

Monitor the values of certain variables as they change within a loop (e.g., for iterative algorithms). Depends on the class StatusLine.

Update the line by using carriage return each time the method step() is called. Do this until the method end() is called (then, a line break is issued).

end()[source]

Finish monitoring values, issue a line break (if not already done). Update the status line one last time.

remove(*names)[source]

Stop monitoring the specified variables.

reset()[source]

Reset the status line. Empty the list of values and begin a new status line.

set_delay(delay)[source]

Set the delay of the StatusLine instance.

update(**values)[source]

Update the values of one or more variables, or add new variables to the status line.

class progress.Abort(key='q', timeout=0)[source]

Check keyboard buffer for a certain key to be pressed.

Initialize before your loop (e.g., of an iterative algorithm). Check within the loop body (e.g., break the loop on positive check). Finalize (end) after the loop. Do not forget to finalize, so that your terminal is put back into normal mode! Or use it as context manager (use the with statement), then finalization is done automatically.

Example:

>>> import time
>>> with Abort() as a:
>>>     for i in range(10):
>>>         time.sleep(1)  # do something
>>>         if a.check():
>>>             break  # leave loop early, because "q" has been pressed
check()[source]

Check if the key has been pressed by now. All other contents of the keyboard buffer are ignored.

end()[source]

Finalize. Put the terminal back into normal mode. Return string buffer.

report()[source]

If the handler was triggered, display a message.

reset()[source]

Reset the abort handler.

class progress.Until(until=None)[source]

Check if a certain date/time has been reached. Can be used to conveniently confine the execution time of an iterative algorithm.

You can specify either a maximum duration (execution time) or a specific date.

check()[source]

Check if the specified time has already been reached.

class progress.Converge(tol=None, smooth=1)[source]

Check data for convergence criterion within an interative algorithm. Specify a certain tolerance (accuracy) that should be reached. Increase the “smooth value” to average over the last few deltas.

check(data)[source]

Check convergence criterion. Return True if the requested accuracy has been reached, otherwise False. If data is None, return False.

delta()[source]

Return the current mean delta (based on the last call of check()). Return -1 if the delta list is still empty.

report()[source]

If the handler was triggered, display a message.

class progress.StatusLine(line='', delay=0.0, cols=None)[source]

Show a status line that is updated by the user every once in a while using “carriage return”.

end()[source]

End status line, issue a line break (only if the status line has already been used).

reset()[source]

Reset the status line (make a line break if neccessary and begin a new status line).

update(line)[source]

Update the line by the given string, replacing the old line. The line only gets printed if the line has changed, and if the given delay time has been passed. If now is True, ignore the delay.

class progress.Terminate[source]

Trap the TERM signal (15). For example, you can stop an interative algorithm in a controlled way, leaving the loop after the next iteration and still saving the results. This is done by sending the TERM signal to the process (also possible remotely), i.e. in a Unix shell you can do kill 12345, or you can use the program top.

Note: Works only on Unix-based systems (Linux etc.).

check()[source]

Return True if a TERM signal has been received, otherwise False.

end()[source]

Remove the trap. Set the action for the TERM signal back to system standard.

report()[source]

If this handler was triggered, display a message.

reset()[source]

Reset the terminate handler, setting the flag back to False and waiting for a new TERM signal.

terminate(signal, frame)[source]

If the TERM signal has been received, this method is executed, setting the flag to True.

Functions

progress.get_columns()[source]

Try to get the number of columns of the current terminal window. If failing, return standard width (80 columns).

progress._nicetime(seconds)[source]

Return nice string representation of the given number of seconds in a human-readable format (approximated). Example: 3634 s –> 1 h.

Indices and tables

Table Of Contents

This Page