progressbar.shortcuts module

The one-call entry point: progressbar(iterable).

Most users never touch anything else in this package.

progressbar.shortcuts.progressbar(iterator: collections.abc.Iterable[T], min_value: bar.NumberT = 0, max_value: bar.ValueT = None, widgets: collections.abc.Sequence[widgets_module.WidgetBase | str] | None = None, prefix: str | None = None, suffix: str | None = None, fast: bool | None = None, desc: str | None = None, total: bar.ValueT = None, unit: str = 'it', unit_scale: bool = False, postfix: Any = None, **kwargs: Any) → collections.abc.Iterator[T][source]

Wrap an iterable so iterating it renders a progress bar.

The common case needs nothing but the iterable:

for item in progressbar(items):
    ...
Parameters:

  • iterator – The iterable to wrap. Its length is used as the total when it has one; otherwise pass max_value, or accept a bar with no percentage or ETA.

  • min_value – Value the bar starts from. Only worth changing when progress does not begin at zero.

  • max_value – Value counted as complete. Defaults to the iterable’s length, or UnknownLength when it has none.

  • widgets – Replaces the default bar layout entirely. Passing this forces the full widget machinery. See the widget reference for what can go in it.

  • prefix – Text before the bar. desc is the tqdm-style alias.

  • suffix – Text after the bar.

  • fast – Only False has an effect: it always uses the full widget bar. True is the same as leaving it unset – it cannot force the fast path when another argument below rules it out. Mainly useful for benchmarking.

  • desc – tqdm-compatible alias for prefix.

  • total – tqdm-compatible alias for max_value.

  • unit – Noun for one item, shown in the rate. Anything other than the default forces the full widget bar.

  • unit_scale – Scale counts by IEC binary prefixes, base 1024, so 1200 renders as 1.2 Kiit. Forces the full widget bar.

  • postfix – Values rendered after the bar. Through this entry point they are fixed for the run, since the bar itself is not returned, leaving no handle to refresh them through. Forces the full widget bar.

  • **kwargs – Passed through to the underlying bar. Supplying variables forces the full widget bar.

Returns:

An iterator yielding the same items, advancing the bar as it goes.