progressbar Package

progressbar Package

Text progress bar library for Python.

A text progress bar is typically used to display the progress of a long running operation, providing a visual cue that processing is underway.

The ProgressBar class manages the current progress, and the format of the line is given by a number of widgets. A widget is an object that may display differently depending on the state of the progress bar. There are three types of widgets:

  • a string, which always shows itself
  • a ProgressBarWidget, which may return a different value every time its update method is called
  • a ProgressBarWidgetHFill, which is like ProgressBarWidget, except it expands to fill the remaining width of the line.

The progressbar module is very easy to use, yet very powerful. It will also automatically enable features like auto-resizing when the system supports it.

class progressbar.ProgressBar(maxval=None, widgets=None, term_width=None, poll=0.1, left_justify=True, fd=<open file '<stderr>', mode 'w'>, redirect_stderr=False, redirect_stdout=False)[source]

Bases: object

The ProgressBar class which updates and prints the bar.

A common way of using it is like:

>>> pbar = ProgressBar().start()
>>> for i in range(100):
...     pbar.update(i+1)
...     # do something
...
>>> pbar.finish()

You can also use a ProgressBar as an iterator:

>>> progress = ProgressBar()
>>> some_iterable = range(100)
>>> for i in progress(some_iterable):
...     # do something
...     pass
...

Since the progress bar is incredibly customizable you can specify different widgets of any type in any order. You can even write your own widgets! However, since there are already a good number of widgets you should probably play around with them before moving on to create your own widgets.

The term_width parameter represents the current terminal width. If the parameter is set to an integer then the progress bar will use that, otherwise it will attempt to determine the terminal width falling back to 80 columns if the width cannot be determined.

When implementing a widget’s update method you are passed a reference to the current progress bar. As a result, you have access to the ProgressBar’s methods and attributes. Although there is nothing preventing you from changing the ProgressBar you should treat it as read only.

Useful methods and attributes include (Public API):
  • currval: current progress (0 <= currval <= maxval)

  • maxval: maximum (and final) value

  • finished: True if the bar has finished (reached 100%)

  • start_time: the time when start() method of ProgressBar was called

  • seconds_elapsed: seconds elapsed since start_time and last call to

    update

  • percentage(): progress in percent [0..100]

default_widgets()
finish()

Puts the ProgressBar bar in the finished state.

next()
percent

Returns the progress as a percentage.

percentage()

Returns the progress as a percentage.

start()

Starts measuring time, and prints the bar at 0%.

It returns self so you can use it like this:

>>> pbar = ProgressBar().start()
>>> for i in range(100):
...    # do something
...    pbar.update(i+1)
...
>>> pbar.finish()
update(value=None)

Updates the ProgressBar to a new value.

class progressbar.UnknownLength[source]

widgets Module

Default ProgressBar widgets

class progressbar.widgets.AbstractWidget[source]

Bases: object

class progressbar.widgets.AdaptiveETA(num_samples=10)[source]

Bases: progressbar.widgets.ETA

Widget which attempts to estimate the time of arrival.

Uses a sampled average of the speed based on the 10 last updates. Very convenient for resuming the progress halfway.

TIME_SENSITIVE = True
class progressbar.widgets.AdaptiveTransferSpeed(num_samples=10)[source]

Bases: progressbar.widgets.FileTransferSpeed

Widget for showing the transfer speed, based on the last X samples

class progressbar.widgets.AnimatedMarker(markers='|/-\')[source]

Bases: progressbar.widgets.Widget

An animated marker for the progress bar which defaults to appear as if it were rotating.

update(pbar)

Updates the widget to show the next marker or the first marker when finished

class progressbar.widgets.Bar(marker='#', left='|', right='|', fill=' ', fill_left=True)[source]

Bases: progressbar.widgets.WidgetHFill

A progress bar which stretches to fill the line.

update(pbar, width)

Updates the progress bar and its subcomponents

class progressbar.widgets.BouncingBar(marker='#', left='|', right='|', fill=' ', fill_left=True)[source]

Bases: progressbar.widgets.Bar

update(pbar, width)

Updates the progress bar and its subcomponents

class progressbar.widgets.Counter(format='%d')[source]

Bases: progressbar.widgets.Widget

Displays the current count

update(pbar)
class progressbar.widgets.ETA(format='Elapsed Time: %s')[source]

Bases: progressbar.widgets.Timer

Widget which attempts to estimate the time of arrival.

TIME_SENSITIVE = True
update(pbar)

Updates the widget to show the ETA or total time when finished.

class progressbar.widgets.FileTransferSpeed(unit='B')[source]

Bases: progressbar.widgets.Widget

Widget for showing the transfer speed (useful for file transfers).

format = '%6.2f %s%s/s'
prefixes = ' kMGTPEZY'
update(pbar)

Updates the widget with the current SI prefixed speed.

class progressbar.widgets.FormatLabel(format)[source]

Bases: progressbar.widgets.Timer

Displays a formatted label

mapping = {'seconds': ('seconds_elapsed', None), 'max': ('maxval', None), 'value': ('currval', None), 'last_update': ('last_update_time', None), 'start': ('start_time', None), 'finished': ('finished', None), 'elapsed': ('seconds_elapsed', <function format_time at 0xf6594b1c>)}
update(pbar)
class progressbar.widgets.Percentage[source]

Bases: progressbar.widgets.Widget

Displays the current percentage as a number with a percent sign.

update(pbar)
class progressbar.widgets.ReverseBar(marker='#', left='|', right='|', fill=' ', fill_left=False)[source]

Bases: progressbar.widgets.Bar

A bar which has a marker which bounces from side to side.

progressbar.widgets.RotatingMarker

alias of AnimatedMarker

class progressbar.widgets.SimpleProgress(sep=' of ')[source]

Bases: progressbar.widgets.Widget

Returns progress as a count of the total (e.g.: “5 of 47”)

update(pbar)
class progressbar.widgets.Timer(format='Elapsed Time: %s')[source]

Bases: progressbar.widgets.Widget

Widget which displays the elapsed seconds.

TIME_SENSITIVE = True
static format_time(seconds)

Formats time as the string “HH:MM:SS”.

update(pbar)

Updates the widget to show the elapsed time.

class progressbar.widgets.Widget[source]

Bases: progressbar.widgets.AbstractWidget

The base class for all widgets

The ProgressBar will call the widget’s update value when the widget should be updated. The widget’s size may change between calls, but the widget may display incorrectly if the size changes drastically and repeatedly.

The boolean TIME_SENSITIVE informs the ProgressBar that it should be updated more often because it is time sensitive.

TIME_SENSITIVE = False
update(pbar)

Updates the widget.

pbar - a reference to the calling ProgressBar

class progressbar.widgets.WidgetHFill[source]

Bases: progressbar.widgets.Widget

The base class for all variable width widgets.

This widget is much like the hfill command in TeX, it will expand to fill the line. You can use more than one in the same line, and they will all have the same width, and together will fill the line.

update(pbar, width)

Updates the widget providing the total width the widget must fill.

pbar - a reference to the calling ProgressBar width - The total width the widget must fill

progressbar.widgets.format_updatable(updatable, pbar)[source]