progressbar.bar module

class progressbar.bar.ProgressBarMixinBase(**kwargs)

Bases: abc.ABC

term_width = 80

The terminal width. This should be automatically detected but will fall back to 80 if auto detection is not possible.

widgets = None

The widgets to render, defaults to the result of default_widget()

max_error = None

When going beyond the max_value, raise an error if True or silently ignore otherwise

prefix = None

Prefix the progressbar with the given string

suffix = None

Suffix the progressbar with the given string

left_justify = None

Justify to the left if True or the right if False

widget_kwargs = None

The default keyword arguments for the default_widgets if no widgets are configured

initial_start_time = None

The time the progress bar was started

poll_interval = None

The interval to poll for updates in seconds if there are updates

min_poll_interval = None

The minimum interval to poll for updates in seconds even if there are no updates

value = None

Current progress (min_value <= value <= max_value)

min_value = None

The minimum/start value for the progress bar

max_value = None

Maximum (and final) value. Beyond this value an error will be raised unless the max_error parameter is False.

end_time = None

The time the progressbar reached max_value or when finish() was called.

start_time = None

The time start() was called or iteration started.

seconds_elapsed = None

Seconds between start_time and last call to update()

extra = None

Extra data for widgets with persistent state. This is used by sampling widgets for example. Since widgets can be shared between multiple progressbars we need to store the state with the progressbar.

get_last_update_time() → Optional[datetime.datetime]

set_last_update_time(value: Optional[datetime.datetime])

last_update_time

start(**kwargs)

update(value=None)

finish()

data() → Dict[str, Any]

class progressbar.bar.ProgressBarBase(**kwargs)

Bases: collections.abc.Iterable, typing.Generic, progressbar.bar.ProgressBarMixinBase

class progressbar.bar.DefaultFdMixin(fd: base.IO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>, is_terminal: bool | None = None, line_breaks: bool | None = None, enable_colors: bool | None = None, **kwargs)

Bases: progressbar.bar.ProgressBarMixinBase

fd = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>

is_ansi_terminal = False

Set the terminal to be ANSI compatible. If a terminal is ANSI compatible we will automatically enable colors and disable line_breaks.

line_breaks = True

Whether to print line breaks. This is useful for logging the progressbar. When disabled the current line is overwritten.

enable_colors = False

Enable or disable colors. Defaults to auto detection

update(*args, **kwargs)

finish(*args, **kwargs)

class progressbar.bar.ResizableMixin(term_width: int | None = None, **kwargs)

Bases: progressbar.bar.ProgressBarMixinBase

finish()

class progressbar.bar.StdRedirectMixin(redirect_stderr: bool = False, redirect_stdout: bool = False, **kwargs)

Bases: progressbar.bar.DefaultFdMixin

redirect_stderr = False

redirect_stdout = False

start(*args, **kwargs)

update(value: Optional[float] = None)

finish(end='\n')

class progressbar.bar.ProgressBar(min_value: T = 0, max_value: T | types.Type[base.UnknownLength] | None = None, widgets: types.Optional[types.List[widgets_module.WidgetBase]] = None, left_justify: bool = True, initial_value: T = 0, poll_interval: types.Optional[float] = None, widget_kwargs: types.Optional[types.Dict[str, types.Any]] = None, custom_len: types.Callable[[str], int] = <function len_color>, max_error=True, prefix=None, suffix=None, variables=None, min_poll_interval=None, **kwargs)

Bases: progressbar.bar.StdRedirectMixin, progressbar.bar.ResizableMixin, progressbar.bar.ProgressBarBase

The ProgressBar class which updates and prints the bar.

Parameters:

• min_value (int) – The minimum/start value for the progress bar
• max_value (int) – The maximum/end value for the progress bar. Defaults to _DEFAULT_MAXVAL
• widgets (list) – The widgets to render, defaults to the result of default_widget()
• left_justify (bool) – Justify to the left if True or the right if False
• initial_value (int) – The value to start with
• poll_interval (float) – The update interval in seconds. Note that if your widgets include timers or animations, the actual interval may be smaller (faster updates). Also note that updates never happens faster than min_poll_interval which can be used for reduced output in logs
• min_poll_interval (float) – The minimum update interval in seconds. The bar will _not_ be updated faster than this, despite changes in the progress, unless force=True. This is limited to be at least _MINIMUM_UPDATE_INTERVAL. If available, it is also bound by the environment variable PROGRESSBAR_MINIMUM_UPDATE_INTERVAL
• widget_kwargs (dict) – The default keyword arguments for widgets
• custom_len (function) – Method to override how the line width is calculated. When using non-latin characters the width calculation might be off by default
• max_error (bool) – When True the progressbar will raise an error if it goes beyond it’s set max_value. Otherwise the max_value is simply raised when needed prefix (str): Prefix the progressbar with the given string suffix (str): Prefix the progressbar with the given string
• variables (dict) – User-defined variables variables that can be used from a label using format=’{variables.my_var}’. These values can be updated using bar.update(my_var=’newValue’) This can also be used to set initial values for variables’ widgets

A common way of using it is like:

>>> progress = ProgressBar().start()
>>> for i in range(100):
...     progress.update(i + 1)
...     # do something
...
>>> progress.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.

dynamic_messages

init()

(re)initialize values to original state so the progressbar can be used (again)

percentage

Return current percentage, returns None if no max_value is given

>>> progress = ProgressBar()
>>> progress.max_value = 10
>>> progress.min_value = 0
>>> progress.value = 0
>>> progress.percentage
0.0
>>>
>>> progress.value = 1
>>> progress.percentage
10.0
>>> progress.value = 10
>>> progress.percentage
100.0
>>> progress.min_value = -10
>>> progress.percentage
100.0
>>> progress.value = 0
>>> progress.percentage
50.0
>>> progress.value = 5
>>> progress.percentage
75.0
>>> progress.value = -5
>>> progress.percentage
25.0
>>> progress.max_value = None
>>> progress.percentage

data() → Dict[str, Any]

Returns:

• max_value: The maximum value (can be None with iterators)
• start_time: Start time of the widget
• last_update_time: Last update time of the widget
• end_time: End time of the widget
• value: The current value
• previous_value: The previous value
• updates: The total update count
• total_seconds_elapsed: The seconds since the bar started
• seconds_elapsed: The seconds since the bar started modulo 60
• minutes_elapsed: The minutes since the bar started modulo 60
• hours_elapsed: The hours since the bar started modulo 24
• days_elapsed: The hours since the bar started
• time_elapsed: The raw elapsed datetime.timedelta object
• percentage: Percentage as a float or None if no max_value is available
• dynamic_messages: Deprecated, use variables instead.
• variables: Dictionary of user-defined variables for the Variable’s

Return type:dict

default_widgets()

next()

increment(value=1, *args, **kwargs)

update(value=None, force=False, **kwargs)

Updates the ProgressBar to a new value.

start(max_value=None, init=True)

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

It returns self so you can use it like this:

Parameters:

• max_value (int) – The maximum value of the progressbar
• reinit (bool) – Initialize the progressbar, this is useful if you wish to reuse the same progressbar but can be disabled if data needs to be passed along to the next run

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

finish(end='\n', dirty=False)

Puts the ProgressBar bar in the finished state.

Also flushes and disables output buffering if this was the last progressbar running.

Parameters:

• end (str) – The string to end the progressbar with, defaults to a newline
• dirty (bool) – When True the progressbar kept the current state and won’t be set to 100 percent

currval

Legacy method to make progressbar-2 compatible with the original progressbar package

class progressbar.bar.DataTransferBar(min_value: T = 0, max_value: T | types.Type[base.UnknownLength] | None = None, widgets: types.Optional[types.List[widgets_module.WidgetBase]] = None, left_justify: bool = True, initial_value: T = 0, poll_interval: types.Optional[float] = None, widget_kwargs: types.Optional[types.Dict[str, types.Any]] = None, custom_len: types.Callable[[str], int] = <function len_color>, max_error=True, prefix=None, suffix=None, variables=None, min_poll_interval=None, **kwargs)

Bases: progressbar.bar.ProgressBar

A progress bar with sensible defaults for downloads etc.

This assumes that the values its given are numbers of bytes.

default_widgets()

class progressbar.bar.NullBar(min_value: T = 0, max_value: T | types.Type[base.UnknownLength] | None = None, widgets: types.Optional[types.List[widgets_module.WidgetBase]] = None, left_justify: bool = True, initial_value: T = 0, poll_interval: types.Optional[float] = None, widget_kwargs: types.Optional[types.Dict[str, types.Any]] = None, custom_len: types.Callable[[str], int] = <function len_color>, max_error=True, prefix=None, suffix=None, variables=None, min_poll_interval=None, **kwargs)

Bases: progressbar.bar.ProgressBar

Progress bar that does absolutely nothing. Useful for single verbosity flags

start(*args, **kwargs)

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

It returns self so you can use it like this:

Parameters:

• max_value (int) – The maximum value of the progressbar
• reinit (bool) – Initialize the progressbar, this is useful if you wish to reuse the same progressbar but can be disabled if data needs to be passed along to the next run

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

update(*args, **kwargs)

Updates the ProgressBar to a new value.

finish(*args, **kwargs)

Puts the ProgressBar bar in the finished state.

Also flushes and disables output buffering if this was the last progressbar running.

Parameters:

• end (str) – The string to end the progressbar with, defaults to a newline
• dirty (bool) – When True the progressbar kept the current state and won’t be set to 100 percent