support.progressindicator – Progress Indicator Widget

This module defines functions and classes which implement a flexible progress bar widget.

To date, the module provides only widgets for text user interfaces (i.e. for a terminal).

Public Classes

This module is built around two main parts: the first one is the manager; the second one is a collection of widgets which manages the way by which the progression is going to be displayed.

The manager has only on public class.

ProgressIndicatorWidget

To date, the module includes a number of widgets listed below in alphabetical order. A handler is a derived class from the BaseWidget class.

Public Functions

This module has has a number of functions listed below in alphabetical order.

Objects reference

This section details the objects defined in this module.

class support.progressindicator.ProgressIndicatorWidget(width=None)

Bases: object

Progress indicator.

This class is the manager of the progress indicator. This latter is a element of a textual user interface and it’s made of a set of elementary widget such as a progress bar or a transfer rate indicator (see widget_classes_available to have the current list of available widgets.

Parameters

width (int) – The width of the progress indicator expressed in characters. The resulting string of the concatenation of strings returned by each widget is left justified in a string of length width. The None object means that the width will set to number of columns of the terminal.

Raises

TypeError – Parameters type mismatch.

Public Methods

This class has a number of public methods listed below.

Using ProgressIndicatorWidget…

After created a class instance, you add one or more elementary widget to the progress indicator by calling the add_widget method. If this step is ignored, the progress indicator will be an empty string. After this step, you must call the start method to initialise the widget with the lowest and the highest value of the monitored quantity. At each change of the value, you call the update method to print the progress bar on the standard output (sys.stdout). When the task completed, you call the finish method.

Example of fetching a file
import urllib.request
from support import progressindicator

progress = progressindicator.ProgressIndicatorWidget(72)
widget = progressindicator.SeparatorWidget(
    symbol="python-3.5.1-docs-text.zip: "
)
progress.add_widget(widget)
widget = progressindicator.PercentWidget()
progress.add_widget(widget)
widget = progressindicator.ProgressBarWidget()
progress.add_widget(widget)

widget = progressindicator.SeparatorWidget(
    symbol="python-3.5.1-docs-text.zip: "
)
progress.add_widget(widget, True)
widget = progressindicator.PrefixedQuantityWidget(symbol="B")
progress.add_widget(widget, True)

url = "https://docs.python.org/release/3.5.1/" \
      "archives/python-3.5.1-docs-text.zip"
with urllib.request.urlopen(url) as stream:
    content_length = int(stream.info()["Content-Length"])
    length = 0
    progress.start(length, content_length)
    progress.update(length)
    while True:
        data = stream.read(1500)
        if not data:
            break
        length += len(data)
        progress.update(length)
    progress.finish(length)
add_widget(widget, is_completion=False)

Add an elementary widget to update the progress indicator widget.

Parameters
Raises
finish(value)

Compute the progress bar completion and return the computed string.

Parameters

value (int or float) – The last value of the monitored quantity.

Returns

A string representing the progress information.

Return type

str

start(minimum=0.0, maximum=inf)

Start the progress indicator widget.

Parameters

  • minimum (int or float) – The lowest value of the measured quantity.

  • maximum (int or float) – The highest value of the measured quantity. This value must be greater than the minimum parameter. The special value “inf” specify that the highest is unknown, so the relative widget will not be displayed.

Raises
update(value)

Update the progress indicator widget

Note

To prevent the update flicking, the refresh period is limited (see refreshment_threshold attribute).

Parameters

value (int or float) – The current value of the monitored quantity.

Raises
refreshment_threshold

The delay between two update of the display expressed in fraction of second. The default value is 8 times per seconds (0.125 s)

Type

float

width

The width of the progress indicator expressed in characters. The resulting string of the concatenation of strings returned by each widget is left justified in a string of length width.

Type

int

class support.progressindicator.WidgetsCollection(max_length)

Bases: object

Widgets collection

Parameters

max_length (int) – The authorised maximum length of the widgets string expressed in characters. This string is the concatenation of strings returned by each widget. The addition of a widget (see add_widget()), whose length makes the length of the widgets string exceeding the max_length, raises an ValueError exception.

Raises
add_widget(widget)

Add an elementary widget to the collection.

Parameters

widget (BaseWidget) – The widget to add. It must be an instance of the BaseWidget class.

Raises
widgets

The widgets list.

Type

list

class support.progressindicator.BaseWidget(symbol='')

Bases: object

Base class for all elementary widget.

Parameters

symbol (str) – The symbol of the unit.

Public Methods

This class has only one public method listed below.

update()
Methods to Override

This class is a abstract class, so the following method must be overridden.

update()
update(normal_value, dyn_range, value, duration, counter)

Update the elementary widget

Parameters

  • normal_value (float) – The normalised value of the progression. This value is between 0 and 1.

  • dyn_range (float) – The dynamics range of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

is_fixed_size

The True value indicates that the widget have a fixed size specifying by the size. The False value indicates that the widget have a variable size. In that case, the size take into account the number of columns of the terminal.

Type

bool

size

size of the widget expressed in characters.

Type

int

symbol

the unit symbol of the measured quantity.

Type

str

class support.progressindicator.PercentWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Widget to update the percentage of progress

The printed string have the following content: nnn% where nnn is the percentage of progress

Parameters

symbol (str) – The symbol of the unit. This string is not used in this context, because a percentage have no unit.

update(normal_value, dyn_range, value, duration, counter)

Display the elementary widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

size of the widget expressed in characters.

Type

int

class support.progressindicator.RateWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Widget to update the rate of progress

The printed string have the following content: rrrr XU/s where rrrr is the rate. X represent a multiple of the unit (G, M or k) and U is the unit symbol.

Parameters

symbol (str) – The symbol of the unit.

update(normal_value, dyn_range, value, duration, counter)

Display the elementary widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

the size of the widget expressed in characters.

Type

int

symbol

the unit symbol of the rate value. By default, the rate is expressed in unit per second.

Type

str

class support.progressindicator.ETAWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Widget to update the estimated time to achieve the operation.

The printed string have the following content: eta hh:mm:ss where hh:mm:ss is the estimated time to achieve the operation expressed in hour, minute and second.

Parameters

symbol (str) – The symbol of the unit. This string is not used in this context, because a time expression have no unit.

update(normal_value, dyn_range, value, duration, counter)

Display the elementary widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

the size of the widget expressed in characters.

Type

int

class support.progressindicator.DurationWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Widget to update the operation duration.

The printed string have the following content: hh:mm:ss where hh:mm:ss is the operation duration expressed in hour, minute and second.

Parameters

symbol (str) – The symbol of the unit. This string is not used in this context, because a time expression have no unit.

update(normal_value, dyn_range, value, duration, counter)

Display the elementary widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

the size of the widget expressed in characters.

Type

int

class support.progressindicator.ValueWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Widget to update the real value.

The printed string have the following content: lll,lll,lll,lll U where lll,lll,lll,lll is the value of the progress and U is the unit symbol. The formatter uses the current locale setting to insert the appropriate number separator characters (see string module).

Parameters

symbol (str) – The symbol of the unit.

update(normal_value, dyn_range, value, duration, counter)

Display the elementary widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

the size of the widget expressed in characters.

Type

int

symbol

the unit symbol of the measured quantity.

Type

str

class support.progressindicator.PrefixedValueWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Widget to update the real value using standard prefix for unit.

The printed string have the following content: nnn XU where nnn is a multiple of the value. X represent a multiple of the unit (G, M or k) and U is the unit symbol.

Parameters

symbol (str) – The symbol of the unit.

update(normal_value, dyn_range, value, duration, counter)

Display the elementary widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

the size of the widget expressed in characters.

Type

int

symbol

the unit symbol of the measured quantity.

Type

str

class support.progressindicator.PrefixedQuantityWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Widget to update the monitored quantity using standard prefix for unit.

The printed string have the following content: nnn XU where nnn is a multiple of the value. X represent a multiple of the unit (G, M or k) and U is the unit symbol.

Parameters

symbol (str) – The symbol of the unit.

update(normal_value, dyn_range, value, duration, counter)

Display the elementary widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

the size of the widget expressed in characters.

Type

int

symbol

the unit symbol of the measured quantity.

Type

str

class support.progressindicator.ProgressBarWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Progress bar widget.

This class implement a progress bar widget.

The printed string have the following content: [==============              ] where = is a step of the progression.

Parameters

symbol (str) – The symbol of the unit. This string is not used in this context, because a progress bar have no unit.

update(normal_value, dyn_range, value, duration, counter)

Update the Progress bar widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

is_fixed_size

The False value indicates that the widget have a fixed size specifying by the size. The True value indicates that the widget have a variable size. In that case, the size take into account the number of columns of the terminal.

Type

bool

size

the size of the widget expressed in characters.

Type

int

symbol

the unit symbol of the measured quantity.

Type

str

class support.progressindicator.IndeterminateProgressBarWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Indeterminate progress bar widget.

This class implement an indeterminate progress bar widget.

The printed string have the following content: [ ****       ] where **** is a maker moving from right to left.

Parameters

symbol (str) – The symbol of the unit. This string is not used in this context, because a progress bar have no unit.

update(normal_value, dyn_range, value, duration, counter)

Update the Progress bar widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

is_fixed_size

The False value indicates that the widget have a fixed size specifying by the size. The True value indicates that the widget have a variable size. In that case, the size take into account the number of columns of the terminal.

Type

bool

size

the unit symbol of the measured quantity.

Type

str

class support.progressindicator.SpinningWheelWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Spinning wheel widget.

This class implement a throbber widget.

Parameters

symbol (str) – The symbol of the unit. This string is not used in this context, because a spinning wheel have no unit.

update(normal_value, dyn_range, value, duration, counter)

Update the Progress bar widget

Parameters

  • normal_value (float) – The normalized value of the monitored quantity. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (float) – The number of seconds since the starting point

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

the size of the widget expressed in characters.

Type

int

class support.progressindicator.SeparatorWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Widget to display a separator.

Parameters

symbol (str) – The separator.

update(normal_value, dyn_range, value, duration, counter)

Display the elementary widget

Parameters

  • normal_value (float) – The normalized value of the progress. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (int) – The number of seconds since the start

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

the size of the widget expressed in characters.

Type

int

symbol

the separator.

Type

str

class support.progressindicator.ScrollingTextWidget(symbol='')

Bases: support.progressindicator.BaseWidget

Widget to display a scrolling text.

Parameters

symbol (str) – The text.

update(normal_value, dyn_range, value, duration, counter)

Display the elementary widget

Parameters

  • normal_value (float) – The normalized value of the progress. This value is between 0 and 1.

  • dyn_range (float) – The normalized maximum value of the monitored quantity.

  • value (float) – The real value of the progress

  • duration (int) – The number of seconds since the start

  • counter (int) – The number of call of the method. This counter may be useful to animate a throbber.

Returns

a human readable string.

Return type

str

size

The size of the widget expressed in characters.

Type

int

symbol

The text.

Type

str

Functions reference

This section details the specific functions used in this module.

support.progressindicator.isu_format_prefix(value, unit)

Return a string using standard prefix for unit.

The returned string represent the value in a compliant International System of Units format, which means with a prefix for unit.

Parameters

  • value (int or float) – The value to format.

  • unit (str) – The unit of the value.

Returns

a string representing the value (“5.75 MB” for example).

Return type

str

Raises

TypeError – Parameters type mismatch.

support.progressindicator.new_download_throbber(title='')

Returns a throbber indicator to monitor a download process.

This widget uses the following widget with a width equal to the number of columns of the terminal: ScrollingTextWidget, SpinningWheelWidget, PrefixedValueWidget, RateWidget, DurationWidget.

Parameters

title (str) – The title of the download. This string is displayed as a scrolling text if its length exceeds the size attribute. The None value

Returns

a progress indicator designed to monitor a download process.

Return type

ProgressIndicatorWidget

Raises

TypeError – Parameters type mismatch.

support.progressindicator.new_download_progress(title='')

Returns a progress indicator to monitor a download process.

This widget uses the following widget with a width equal to the number of columns of the terminal: ScrollingTextWidget, SpinningWheelWidget, PrefixedValueWidget, RateWidget, DurationWidget.

Parameters

title (str) – The title of the download. This string is displayed as a scrolling text if its length exceeds the size attribute

Returns

a progress indicator designed to monitor a download process.

Return type

ProgressIndicatorWidget

Raises

TypeError – Parameters type mismatch.

support.progressindicator.new_download_null(title='')

Returns a progress indicator to monitor a download process.

This widget uses no widget. This is useful for very small downloads (a few kilobytes).

Parameters

title (str) – The title of the download. This string is not used, it is present only for the consistency with the other factory function.

Returns

a progress indicator designed to monitor a download process.

Return type

ProgressIndicatorWidget

Raises

TypeError – Parameters type mismatch.

Data reference

This section details global data, including both variables and values used as ‘defined constants’.

support.progressindicator.widget_classes_available = [<class 'support.progressindicator.PercentWidget'>, <class 'support.progressindicator.RateWidget'>, <class 'support.progressindicator.ETAWidget'>, <class 'support.progressindicator.DurationWidget'>, <class 'support.progressindicator.ValueWidget'>, <class 'support.progressindicator.PrefixedValueWidget'>, <class 'support.progressindicator.PrefixedQuantityWidget'>, <class 'support.progressindicator.ProgressBarWidget'>, <class 'support.progressindicator.IndeterminateProgressBarWidget'>, <class 'support.progressindicator.SpinningWheelWidget'>, <class 'support.progressindicator.SeparatorWidget'>, <class 'support.progressindicator.ScrollingTextWidget'>]

A set containing the class of the widget supported by this module on all platforms.

Type

list