progressive module

class, max_value=100, width=u'25%', title_pos=u'left', title=u'Progress', num_rep=u'fraction', indent=0, filled_color=2, empty_color=7, back_color=None, filled_char=u' ', empty_char=u' ', start_char=u'', end_char=u'', fallback=True, fallback_empty_char=u'u25ef', fallback_filled_char=u'u25c9', force_color=None)[source]

Bases: object

Progress Bar with blessings

Several parts of this class are thanks to Erik Rose’s implementation of ProgressBar in nose-progressive, licensed under The MIT License. MIT nose-progressive/noseprogressive/

Terminal with 256 colors is recommended. See
this for Ubuntu installation as an example.
  • term (blessings.Terminal|NoneType) – blessings.Terminal instance for the terminal of display
  • max_value (int) – The capacity of the bar, i.e., value/max_value
  • width (str) – Must be of format {num: int}{unit: c|%}. Unit “c” can be used to specify number of maximum columns; unit “%”. to specify percentage of the total terminal width to use. e.g., “20c”, “25%”, etc.
  • title_pos (str) – Position of title relative to the progress bar; can be any one of [“left”, “right”, “above”, “below”]
  • title (str) – Title of the progress bar
  • num_rep (str) – Numeric representation of completion; can be one of [“fraction”, “percentage”]
  • indent (int) – Spaces to indent the bar from the left-hand side
  • filled_color (str|int) – color of the filled_char; can be a string of the color’s name or number representing the color; see the blessings documentation for details
  • empty_color (str|int) – color of the empty_char
  • back_color (str|NoneType) – Background color of the progress bar; must be a string of the color name, unused if numbers used for filled_color and empty_color. If set to None, will not be used.
  • filled_char (unicode) – Character representing completeness on the progress bar
  • empty_char (unicode) – The complement to filled_char
  • start_char (unicode) – Character at the start of the progress bar
  • end_char (unicode) – Character at the end of the progress bar
  • fallback (bool) – If this is set, if the terminal does not support provided colors, this will fall back to plain formatting that works on terminals with no color support, using the provided fallback_empty_char` and ``fallback_filled_char
  • force_color (bool|NoneType) – True forces color to be used even if it may not be supported by the terminal; False forces use of the fallback formatting; None does not force anything and allows automatic detection as usual.
draw(value, newline=True, flush=True)[source]

Draw the progress bar

  • value (int) – Progress value relative to self.max_value
  • newline (bool) – If this is set, a newline will be written after drawing

Callable for drawing empty portion of progress bar

Return type:callable

Character at the end of the progress bar


Callable for drawing filled portion of progress bar

Return type:callable

Find actual length of bar_str

e.g., Progress [ | ] 10/10


The capacity of the bar, i.e., value/max_value


Get maximum width of progress bar

Return type:int
Returns:Maximum column width of progress bar

Character at the start of the progress bar


Title of the progress bar

progressive.cursor module

class progressive.cursor.Cursor(term=None)[source]

Bases: object

Common methods for cursor manipulation

Parameters:term (NoneType|blessings.Terminal) – Terminal instance; if not given, will be created by the class

Flush buffer of terminal output stream


Effects a newline by moving the cursor down and clearing


Restores cursor to the previously saved location

Cursor position will only be restored IF it was previously saved
by this instance (and not by any external force)

Saves current cursor position, so that it can be restored later


Writes s to the terminal output stream

Writes can be disabled by setting the environment variable

progressive.examples module


Usage: python -c “from progressive.examples import *; tree()” as an example


Simple example using just the Bar class

This example is intended to show usage of the Bar class at the lowest level.


Example showing tree progress view

progressive.exceptions module

exception progressive.exceptions.ColorUnsupportedError[source]

Bases: progressive.exceptions.ProgressiveException

Color is not supported by terminal

exception progressive.exceptions.LengthOverflowError[source]

Bases: progressive.exceptions.ProgressiveException

Terminal is not long enough to display hierarchy

exception progressive.exceptions.ProgressiveException[source]

Bases: exceptions.Exception

Base class for exceptions raised by progressive

exception progressive.exceptions.WidthOverflowError[source]

Bases: progressive.exceptions.ProgressiveException

Terminal is not wide enough for the bar attempting to be written

progressive.pretty module

progressive.tree module

class progressive.tree.BarDescriptor[source]

Bases: dict

Bar descriptor

To be used in leaf of a tree describing a hierarchy for ProgressTree, e.g.,:

tree = {“Job”:

{“Task1”: BarDescriptor(...)}, {“Task2”:

{“Subtask1”: BarDescriptor(...)},



  • type (Bar|subclass of Bar) – The type of Bar to use to display that leaf
  • value (Value) – Amount to fill the progress bar vs. its max value
  • args (list) – A list of args to instantiate type with
  • kwargs (dict) – A dict of kwargs to instantiate type with
class progressive.tree.ProgressTree(term=None, indent=4)[source]

Bases: object

Progress display for trees

For drawing a hierarchical progress view from a tree

  • term (NoneType|blessings.Terminal) – Terminal instance; if not given, will be created by the class
  • indent (int) – The amount of indentation between each level in hierarchy
draw(tree, bar_desc=None, save_cursor=True, flush=True)[source]

Draw tree to the terminal

  • tree (dict) – tree should be a tree representing a hierarchy; each key should be a string describing that hierarchy level and value should also be dict except for leaves which should be BarDescriptors. See BarDescriptor for a tree example.
  • bar_desc (BarDescriptor|NoneType) – For describing non-leaf bars in that will be drawn from tree; certain attributes such as value and kwargs["max_value"] will of course be overridden if provided.
  • flush (bool) – If this is set, output written will be flushed
  • save_cursor (bool) – If this is set, cursor location will be saved before drawing; this will OVERWRITE a previous save, so be sure to set this accordingly (to your needs).
lines_required(tree, count=0)[source]

Calculate number of lines required to draw tree


Clear lines in terminal below current cursor position as required

This is important to do before drawing to ensure sufficient room at the bottom of your terminal.

Parameters:tree (dict) – tree as described in BarDescriptor
class progressive.tree.Value(val=0)[source]

Bases: object

Container class for use with BarDescriptor

Should be used for value argument when initializing
BarDescriptor, e.g., BarDescriptor(type=..., value=Value(10))

progressive.util module

progressive.util.ensure(expr, exc, *args, **kwargs)[source]
Raises exc:With *args and **kwargs if not expr

Returns the floor of x :returns: floor of x :rtype: int

progressive.util.merge_dicts(dicts, deepcopy=False)[source]

Merges dicts

In case of key conflicts, the value kept will be from the latter dictionary in the list of dictionaries

  • dicts – [dict, ...]
  • deepcopy – deepcopy items within dicts

Cast s as unicode string

This is a convenience function to make up for the fact
that Python3 does not have a unicode() cast (for obvious reasons)
Return type:unicode
Returns:Equivalent of unicode(s) (at least I hope so)