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.
widgets
Module¶
Default ProgressBar widgets
-
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
-