progressbar package

Subpackages

Submodules

Module contents

class progressbar.AbsoluteETA(format_not_started='Estimated finish time:  ----/--/-- --:--:--', format_finished='Finished at: %(elapsed)s', format='Estimated finish time: %(eta)s', **kwargs)[source]

Bases: ETA

Widget which attempts to estimate the absolute time of arrival.

class progressbar.AdaptiveETA(exponential_smoothing=True, exponential_smoothing_factor=0.1, **kwargs)[source]

Bases: ETA, SamplesMixin

WidgetBase 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.

exponential_smoothing: bool
exponential_smoothing_factor: float
class progressbar.AdaptiveTransferSpeed(**kwargs)[source]

Bases: FileTransferSpeed, SamplesMixin

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

class progressbar.AnimatedMarker(markers='|/-\\', default=None, fill='', marker_wrap=None, fill_wrap=None, **kwargs)[source]

Bases: TimeSensitiveWidgetBase

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

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

Bases: AutoWidthWidgetBase

A progress bar which stretches to fill the line.

bg: Color | ColorGradient | None = None
fg: Color | ColorGradient | None = <progressbar.terminal.base.ColorGradient object>
class progressbar.BouncingBar(marker='#', left='|', right='|', fill=' ', fill_left=True, marker_wrap=None, **kwargs)[source]

Bases: Bar, TimeSensitiveWidgetBase

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

INTERVAL = datetime.timedelta(microseconds=100000)
class progressbar.Counter(format='%(value)d', **kwargs)[source]

Bases: FormatWidgetMixin, WidgetBase

Displays the current count.

class progressbar.CurrentTime(format='Current Time: %(current_time)s', microseconds=False, **kwargs)[source]

Bases: FormatWidgetMixin, TimeSensitiveWidgetBase

Widget which displays the current (date)time with seconds resolution.

INTERVAL = datetime.timedelta(seconds=1)
current_datetime()[source]
current_time()[source]
class progressbar.DataSize(variable='value', format='%(scaled)5.1f %(prefix)s%(unit)s', unit='B', prefixes=('', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei', 'Zi', 'Yi'), **kwargs)[source]

Bases: FormatWidgetMixin, WidgetBase

Widget for showing an amount of data transferred/processed.

Automatically formats the value (assumed to be a count of bytes) with an appropriate sized unit, based on the IEC binary prefixes (powers of 1024).

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

Bases: ProgressBar

A progress bar with sensible defaults for downloads etc.

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

default_widgets()[source]
class progressbar.DoubleExponentialMovingAverage(alpha: float = 0.5)[source]

Bases: SmoothingAlgorithm

The Double Exponential Moving Average (DEMA) is essentially an EMA of an EMA, which reduces the lag that’s typically associated with a simple EMA. It’s more responsive to recent changes in data.

update(new_value: float, elapsed: timedelta) → float[source]

Updates the algorithm with a new value and returns the smoothed value.

class progressbar.DynamicMessage(name, format='{name}: {formatted_value}', width=6, precision=3, **kwargs)[source]

Bases: Variable

Kept for backwards compatibility, please use Variable instead.

class progressbar.ETA(format_not_started='ETA:  --:--:--', format_finished='Time: %(elapsed)8s', format='ETA:  %(eta)8s', format_zero='ETA:  00:00:00', format_na='ETA:      N/A', **kwargs)[source]

Bases: Timer

WidgetBase which attempts to estimate the time of arrival.

class progressbar.ExponentialMovingAverage(alpha: float = 0.5)[source]

Bases: SmoothingAlgorithm

The Exponential Moving Average (EMA) is an exponentially weighted moving average that reduces the lag that’s typically associated with a simple moving average. It’s more responsive to recent changes in data.

update(new_value: float, elapsed: timedelta) → float[source]

Updates the algorithm with a new value and returns the smoothed value.

class progressbar.FileTransferSpeed(format='%(scaled)5.1f %(prefix)s%(unit)-s/s', inverse_format='%(scaled)5.1f s/%(prefix)s%(unit)-s', unit='B', prefixes=('', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei', 'Zi', 'Yi'), **kwargs)[source]

Bases: FormatWidgetMixin, TimeSensitiveWidgetBase

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

class progressbar.FormatCustomText(format: str, mapping: Dict[str, Any] | None = None, **kwargs)[source]

Bases: FormatWidgetMixin, WidgetBase

copy = False
mapping: Dict[str, Any] = {}
update_mapping(**mapping: Dict[str, Any])[source]
class progressbar.FormatLabel(format: str, **kwargs)[source]

Bases: FormatWidgetMixin, WidgetBase

Displays a formatted label.

>>> label = FormatLabel('%(value)s', min_width=5, max_width=10)
>>> class Progress:
...     pass
>>> label = FormatLabel('{value} :: {value:^6}', new_style=True)
>>> str(label(Progress, dict(value='test')))
'test ::  test '
mapping: ClassVar[Dict[str, Tuple[str, Any]]] = {'elapsed': ('total_seconds_elapsed', <function format_time>), 'finished': ('end_time', None), 'last_update': ('last_update_time', None), 'max': ('max_value', None), 'seconds': ('seconds_elapsed', None), 'start': ('start_time', None), 'value': ('value', None)}
class progressbar.FormatLabelBar(format, **kwargs)[source]

Bases: FormatLabel, Bar

A bar which has a formatted label in the center.

class progressbar.GranularBar(markers=' ▏▎▍▌▋▊▉█', left='|', right='|', **kwargs)[source]

Bases: AutoWidthWidgetBase

A progressbar that can display progress at a sub-character granularity by using multiple marker characters.

Examples of markers:

  • Smooth: ` ▏▎▍▌▋▊▉█` (default)

  • Bar: ` ▁▂▃▄▅▆▇█`

  • Snake: ` ▖▌▛█`

  • Fade in: ` ░▒▓█`

  • Dots: ` ⡀⡄⡆⡇⣇⣧⣷⣿`

  • Growing circles: ` .oO`

The markers can be accessed through GranularMarkers. GranularMarkers.dots for example

class progressbar.JobStatusBar(name: str, left='|', right='|', fill=' ', fill_left=True, success_fg_color=((0, 128, 0), (120, 100, 25), 'Green', 2), success_bg_color=None, success_marker='█', failure_fg_color=((255, 0, 0), (0, 100, 50), 'Red', 9), failure_bg_color=None, failure_marker='X', **kwargs)[source]

Bases: Bar, VariableMixin

Widget which displays the job status as markers on the bar.

The status updates can be given either as a boolean or as a string. If it’s a string, it will be displayed as-is. If it’s a boolean, it will be displayed as a marker (default: ‘█’ for success, ‘X’ for failure) configurable through the success_marker and failure_marker parameters.

Parameters:

  • name – The name of the variable to use for the status updates.

  • left – The left border of the bar.

  • right – The right border of the bar.

  • fill – The fill character of the bar.

  • fill_left – Whether to fill the bar from the left or the right.

  • success_fg_color – The foreground color to use for successful jobs.

  • success_bg_color – The background color to use for successful jobs.

  • success_marker – The marker to use for successful jobs.

  • failure_fg_color – The foreground color to use for failed jobs.

  • failure_bg_color – The background color to use for failed jobs.

  • failure_marker – The marker to use for failed jobs.

failure_bg_color: Color | None = None
failure_fg_color: Color | None = ((255, 0, 0), (0, 100, 50), 'Red', 9)
failure_marker: str = 'X'
job_markers: list[str]
success_bg_color: Color | None = None
success_fg_color: Color | None = ((0, 128, 0), (120, 100, 25), 'Green', 2)
success_marker: str = '█'
class progressbar.LineOffsetStreamWrapper(lines: int = 0, stream: ~typing.TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)[source]

Bases: TextIOOutputWrapper

DOWN = '\x1b[B'
UP = '\x1b[F'
write(data: str) → int[source]
class progressbar.MultiBar(bars: ~typing.Iterable[tuple[str, ~progressbar.bar.ProgressBar]] | None = None, fd: ~typing.TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, prepend_label: bool = True, append_label: bool = False, label_format='{label:20.20} ', initial_format: str | None = '{label:20.20} Not yet started', finished_format: str | None = None, update_interval: float = 0.016666666666666666, show_initial: bool = True, show_finished: bool = True, remove_finished: ~datetime.timedelta | float = datetime.timedelta(seconds=3600), sort_key: str | ~progressbar.multi.SortKey = SortKey.CREATED, sort_reverse: bool = True, sort_keyfunc: ~typing.Callable[[~progressbar.bar.ProgressBar], ~typing.Any] | None = None, **progressbar_kwargs)[source]

Bases: Dict[str, ProgressBar]

append_label: bool

Automatically append the label to the progressbars

fd: TextIO
finished_format: str | None

If finished_format is None, the progressbar rendering is used.

flush()[source]
get_sorted_bars()[source]
initial_format: str | None
join(timeout=None)[source]
label_format: str

The format for the label to append/prepend to the progressbar

prepend_label: bool

Automatically prepend the label to the progressbars

print(*args, end='\n', offset=None, flush=True, clear=True, **kwargs)[source]

Print to the progressbar stream without overwriting the progressbars.

Parameters:

  • end – The string to append to the end of the output

  • offset – The number of lines to offset the output by. If None, the output will be printed above the progressbars

  • flush – Whether to flush the output to the stream

  • clear – If True, the line will be cleared before printing.

  • **kwargs – Additional keyword arguments to pass to print

progressbar_kwargs: dict[str, Any]

The kwargs passed to the progressbar constructor

remove_finished: float | None
render(flush: bool = True, force: bool = False)[source]

Render the multibar to the given stream.

run(join=True)[source]

Start the multibar render loop and run the progressbars until they have force _thread_finished.

sort_keyfunc: Callable[[ProgressBar], Any]

The progressbar sorting key function

start()[source]
stop(timeout: float | None = None)[source]
update_interval: float
class progressbar.MultiProgressBar(name, markers=' ▁▂▃▄▅▆▇█', **kwargs)[source]

Bases: MultiRangeBar

get_values(progress: ProgressBarMixinBase, data: Data)[source]
class progressbar.MultiRangeBar(name, markers, **kwargs)[source]

Bases: Bar, VariableMixin

A bar with multiple sub-ranges, each represented by a different symbol.

The various ranges are represented on a user-defined variable, formatted as

[['Symbol1', amount1], ['Symbol2', amount2], ...]
get_values(progress: ProgressBarMixinBase, data: Data)[source]
class progressbar.NullBar(min_value: float = 0, max_value: float | ~typing.Type[<class 'progressbar.base.UnknownLength'>] | None = None, widgets: ~typing.Sequence[~progressbar.widgets.WidgetBase | str] | None = None, left_justify: bool = True, initial_value: float = 0, poll_interval: float | None = None, widget_kwargs: ~typing.Dict[str, ~typing.Any] | None = None, custom_len: ~typing.Callable[[str], int] = <function len_color>, max_error=True, prefix=None, suffix=None, variables=None, min_poll_interval=None, **kwargs)[source]

Bases: ProgressBar

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

finish(*args: Any, **kwargs: Any)[source]

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

start(*args: Any, **kwargs: Any)[source]

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

  • init (bool) – (Re)Initialize the progressbar, this is useful if you wish to reuse the same progressbar but can be disabled if data needs to be persisted between runs

>>> pbar = ProgressBar().start()
>>> for i in range(100):
...     # do something
...     pbar.update(i + 1)
>>> pbar.finish()
update(*args: Any, **kwargs: Any)[source]

Updates the ProgressBar to a new value.

class progressbar.Percentage(format='%(percentage)3d%%', na='N/A%%', **kwargs)[source]

Bases: FormatWidgetMixin, ColoredMixin, WidgetBase

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

get_format(progress: ProgressBarMixinBase, data: Data, format=None)[source]
class progressbar.PercentageLabelBar(format='%(percentage)2d%%', na='N/A%%', **kwargs)[source]

Bases: Percentage, FormatLabelBar

A bar which displays the current percentage in the center.

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

Bases: StdRedirectMixin, ResizableMixin, 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

  • line_offset (int) – The number of lines to offset the progressbar from your current line. This is useful if you have other output or multiple progressbars

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.

property currval

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

data() → Dict[str, Any][source]
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()[source]
property dynamic_messages
finish(end: str = '\n', dirty: bool = False)[source]

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

increment(value: float = 1, *args: Any, **kwargs: Any)[source]
init()[source]

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

next()
paused: bool = False
property percentage: float | None

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
start(max_value: float | None = None, init: bool = True, *args: Any, **kwargs: Any) → ProgressBar[source]

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

  • init (bool) – (Re)Initialize the progressbar, this is useful if you wish to reuse the same progressbar but can be disabled if data needs to be persisted between runs

>>> pbar = ProgressBar().start()
>>> for i in range(100):
...     # do something
...     pbar.update(i + 1)
>>> pbar.finish()
update(value: float | ~typing.Type[<class 'progressbar.base.UnknownLength'>] | None = None, force: bool = False, **kwargs: ~typing.Any)[source]

Updates the ProgressBar to a new value.

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

Bases: Bar

A bar which has a marker that goes from right to left.

progressbar.RotatingMarker

alias of AnimatedMarker

class progressbar.SimpleProgress(format='%(value_s)s of %(max_value_s)s', **kwargs)[source]

Bases: FormatWidgetMixin, ColoredMixin, WidgetBase

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

DEFAULT_FORMAT = '%(value_s)s of %(max_value_s)s'
max_width_cache: dict[str | tuple[NumberT | types.Type[base.UnknownLength] | None, NumberT | types.Type[base.UnknownLength] | None], types.Optional[int]]
class progressbar.SmoothingAlgorithm(**kwargs)[source]

Bases: ABC

abstract update(new_value: float, elapsed: timedelta) → float[source]

Updates the algorithm with a new value and returns the smoothed value.

class progressbar.SmoothingETA(smoothing_algorithm: type[~progressbar.algorithms.SmoothingAlgorithm] = <class 'progressbar.algorithms.ExponentialMovingAverage'>, smoothing_parameters: dict[str, float] | None = None, **kwargs)[source]

Bases: ETA

WidgetBase which attempts to estimate the time of arrival using an exponential moving average (EMA) of the speed.

EMA applies more weight to recent data points and less to older ones, and doesn’t require storing all past values. This approach works well with varying data points and smooths out fluctuations effectively.

smoothing_algorithm: SmoothingAlgorithm
smoothing_parameters: dict[str, float]
class progressbar.SortKey(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Sort keys for the MultiBar.

This is a string enum, so you can use any progressbar attribute or property as a sort key.

Note that the multibar defaults to lazily rendering only the changed progressbars. This means that sorting by dynamic attributes such as value might result in more rendering which can have a small performance impact.

CREATED = 'index'
LABEL = 'label'
PERCENTAGE = 'percentage'
VALUE = 'value'
class progressbar.Timer(format='Elapsed Time: %(elapsed)s', **kwargs)[source]

Bases: FormatLabel, TimeSensitiveWidgetBase

WidgetBase which displays the elapsed seconds.

static format_time(timestamp: timedelta | date | datetime | str | int | float | None, precision: timedelta = datetime.timedelta(seconds=1)) → str

Formats timedelta/datetime/seconds

>>> format_time('1')
'0:00:01'
>>> format_time(1.234)
'0:00:01'
>>> format_time(1)
'0:00:01'
>>> format_time(datetime.datetime(2000, 1, 2, 3, 4, 5, 6))
'2000-01-02 03:04:05'
>>> format_time(datetime.date(2000, 1, 2))
'2000-01-02'
>>> format_time(datetime.timedelta(seconds=3661))
'1:01:01'
>>> format_time(None)
'--:--:--'
>>> format_time(format_time)  
Traceback (most recent call last):
    ...
TypeError: Unknown type ...
class progressbar.UnknownLength[source]

Bases: object

class progressbar.Variable(name, format='{name}: {formatted_value}', width=6, precision=3, **kwargs)[source]

Bases: FormatWidgetMixin, VariableMixin, WidgetBase

Displays a custom variable.

class progressbar.VariableMixin(name, **kwargs)[source]

Bases: object

Mixin to display a custom user variable.

progressbar.len_color(value: str | bytes) → int[source]

Return the length of value without ANSI escape codes.

>>> len_color(b'[1234]abc')
3
>>> len_color('[1234]abc')
3
>>> len_color('[1234]abc')
3
progressbar.progressbar(iterator, min_value: int = 0, max_value=None, widgets=None, prefix=None, suffix=None, **kwargs)[source]