progressbar.widgets module

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

Bases: ETA

Widget which attempts to estimate the absolute time of arrival.

class progressbar.widgets.AdaptiveETA(exponential_smoothing=True, exponential_smoothing_factor=0.1, **kwargs)

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.widgets.AdaptiveTransferSpeed(**kwargs: Any)

Bases: FileTransferSpeed, SamplesMixin

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

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

Bases: TimeSensitiveWidgetBase

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

class progressbar.widgets.AutoWidthWidgetBase(*args, fixed_colors=None, gradient_colors=None, **kwargs)

Bases: WidgetBase

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.

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

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.widgets.BouncingBar(marker='#', left='|', right='|', fill=' ', fill_left=True, marker_wrap=None, **kwargs)

Bases: Bar, TimeSensitiveWidgetBase

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

INTERVAL = datetime.timedelta(microseconds=100000)

class progressbar.widgets.ColoredMixin

Bases: object

class progressbar.widgets.Counter(format='%(value)d', **kwargs: Any)

Bases: FormatWidgetMixin, WidgetBase

Displays the current count.

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

Bases: FormatWidgetMixin, TimeSensitiveWidgetBase

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

INTERVAL = datetime.timedelta(seconds=1)

current_datetime()

current_time()

class progressbar.widgets.DataSize(variable='value', format='%(scaled)5.1f %(prefix)s%(unit)s', unit='B', prefixes=('', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei', 'Zi', 'Yi'), **kwargs)

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.widgets.DynamicMessage(name, format='{name}: {formatted_value}', width=6, precision=3, **kwargs)

Bases: Variable

Kept for backwards compatibility, please use Variable instead.

class progressbar.widgets.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)

Bases: Timer

WidgetBase which attempts to estimate the time of arrival.

class progressbar.widgets.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)

Bases: FormatWidgetMixin, TimeSensitiveWidgetBase

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

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

Bases: FormatWidgetMixin, WidgetBase

copy = False

mapping: Dict[str, Any] = {}

update_mapping(**mapping: Dict[str, Any])

class progressbar.widgets.FormatLabel(format: str, **kwargs: Any)

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.widgets.FormatLabelBar(format, **kwargs: Any)

Bases: FormatLabel, Bar

A bar which has a formatted label in the center.

class progressbar.widgets.FormatWidgetMixin(format: str, new_style: bool = False, **kwargs: Any)

Bases: ABC

Mixin to format widgets using a formatstring.

Variables available:

• max_value: The maximum value (can be None with iterators)

• value: The current value

• 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: Shortcut for HH:MM:SS time since the bar started including days

• percentage: Percentage as a float

get_format(progress: ProgressBarMixinBase, data: Data, format: types.Optional[str] = None) → str

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

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.widgets.GranularMarkers

Bases: object

bar = ' ▁▂▃▄▅▆▇█'

dots = ' ⡀⡄⡆⡇⣇⣧⣷⣿'

fade_in = ' ░▒▓█'

growing_circles = ' .oO'

smooth = ' ▏▎▍▌▋▊▉█'

snake = ' ▖▌▛█'

class progressbar.widgets.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)

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.widgets.MultiProgressBar(name, markers=' ▁▂▃▄▅▆▇█', **kwargs)

Bases: MultiRangeBar

get_values(progress: ProgressBarMixinBase, data: Data)

class progressbar.widgets.MultiRangeBar(name, markers, **kwargs: Any)

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)

class progressbar.widgets.Percentage(format='%(percentage)3d%%', na='N/A%%', **kwargs: Any)

Bases: FormatWidgetMixin, ColoredMixin, WidgetBase

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

get_format(progress: ProgressBarMixinBase, data: Data, format=None)

class progressbar.widgets.PercentageLabelBar(format='%(percentage)2d%%', na='N/A%%', **kwargs: Any)

Bases: Percentage, FormatLabelBar

A bar which displays the current percentage in the center.

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

Bases: Bar

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

progressbar.widgets.RotatingMarker

alias of AnimatedMarker

class progressbar.widgets.SamplesMixin(samples=datetime.timedelta(seconds=2), key_prefix=None, **kwargs)

Bases: TimeSensitiveWidgetBase

Mixing for widgets that average multiple measurements.

Note that samples can be either an integer or a timedelta to indicate a certain amount of time

>>> class progress:
...     last_update_time = datetime.datetime.now()
...     value = 1
...     extra = dict()

>>> samples = SamplesMixin(samples=2)
>>> samples(progress, None, True)
(None, None)
>>> progress.last_update_time += datetime.timedelta(seconds=1)
>>> samples(progress, None, True) == (datetime.timedelta(seconds=1), 0)
True

>>> progress.last_update_time += datetime.timedelta(seconds=1)
>>> samples(progress, None, True) == (datetime.timedelta(seconds=1), 0)
True

>>> samples = SamplesMixin(samples=datetime.timedelta(seconds=1))
>>> _, value = samples(progress, None)
>>> value
SliceableDeque([1, 1])

>>> samples(progress, None, True) == (datetime.timedelta(seconds=1), 0)
True

get_sample_times(progress: ProgressBarMixinBase, data: Data)

get_sample_values(progress: ProgressBarMixinBase, data: Data)

class progressbar.widgets.SimpleProgress(format='%(value_s)s of %(max_value_s)s', **kwargs: Any)

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

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.widgets.TFixedColors

Bases: TypedDict

bg_none: Color | None

fg_none: Color | None

class progressbar.widgets.TGradientColors

Bases: TypedDict

bg: Color | ColorGradient | None

fg: Color | ColorGradient | None

class progressbar.widgets.TimeSensitiveWidgetBase(*args, fixed_colors=None, gradient_colors=None, **kwargs)

Bases: WidgetBase

The base class for all time sensitive widgets.

Some widgets like timers would become out of date unless updated at least every INTERVAL

INTERVAL = datetime.timedelta(microseconds=100000)

class progressbar.widgets.Timer(format='Elapsed Time: %(elapsed)s', **kwargs: Any)

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.widgets.Variable(name, format='{name}: {formatted_value}', width=6, precision=3, **kwargs)

Bases: FormatWidgetMixin, VariableMixin, WidgetBase

Displays a custom variable.

class progressbar.widgets.VariableMixin(name, **kwargs: Any)

Bases: object

Mixin to display a custom user variable.

class progressbar.widgets.WidgetBase(*args, fixed_colors=None, gradient_colors=None, **kwargs)

Bases: WidthWidgetMixin

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 INTERVAL timedelta informs the ProgressBar that it should be updated more often because it is time sensitive.

The widgets are only visible if the screen is within a specified size range so the progressbar fits on both large and small screens.

WARNING: Widgets can be shared between multiple progressbars so any state information specific to a progressbar should be stored within the progressbar instead of the widget.

Variables available:

• min_width: Only display the widget if at least min_width is left

• max_width: Only display the widget if at most max_width is left

• weight: Widgets with a higher weight will be calculated before widgets with a lower one

• copy: Copy this widget when initializing the progress bar so the progressbar can be reused. Some widgets such as the FormatCustomText require the shared state so this needs to be optional

copy = True

property uses_colors

class progressbar.widgets.WidthWidgetMixin(min_width=None, max_width=None, **kwargs: Any)

Bases: ABC

Mixing to make sure widgets are only visible if the screen is within a specified size range so the progressbar fits on both large and small screens.

Variables available:

• min_width: Only display the widget if at least min_width is left

• max_width: Only display the widget if at most max_width is left

>>> class Progress:
...     term_width = 0

>>> WidthWidgetMixin(5, 10).check_size(Progress)
False
>>> Progress.term_width = 5
>>> WidthWidgetMixin(5, 10).check_size(Progress)
True
>>> Progress.term_width = 10
>>> WidthWidgetMixin(5, 10).check_size(Progress)
True
>>> Progress.term_width = 11
>>> WidthWidgetMixin(5, 10).check_size(Progress)
False

check_size(progress: ProgressBarMixinBase)

progressbar.widgets.create_marker(marker, wrap=None)

progressbar.widgets.create_wrapper(wrapper)

Convert a wrapper tuple or format string to a format string.

>>> create_wrapper('')

>>> print(create_wrapper('a{}b'))
a{}b

>>> print(create_wrapper(('a', 'b')))
a{}b

progressbar.widgets.string_or_lambda(input_)

progressbar.widgets.wrapper(function, wrapper_)

Wrap the output of a function in a template string or a tuple with begin/end strings.