FormatCustomText¶

FormatCustomText renders its own text, independent of the bar.

Reach for it to show auxiliary information that is not part of the bar’s progress or variables – it keeps its own mapping, updated directly with update_mapping() rather than through bar.update().

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

Bases: FormatWidgetMixin, WidgetBase

A widget that formats its own mapping instead of data().

Not driven by the bar’s progress at all: update_mapping lets calling code push arbitrary key/value pairs to render, so this acts as a free-form status line alongside the bar. copy = False because its whole point is shared, externally-updated state, unlike ordinary widgets (see WidgetBase’s copy note).

Create a FormatCustomText.

Parameters:

format – The template string. Keys come from self.mapping, not the bar’s data().
mapping – Initial mapping. Defaults to a copy of the class- level mapping (empty unless a subclass overrides it).
**kwargs – Forwarded to the next class in the cooperative __init__ chain.

update_mapping(**mapping: Any)[source]: Merge mapping into self.mapping for the next render.

Example¶

"""``FormatCustomText`` renders its own text, independent of the bar.

Reach for it to show auxiliary information that is not part of the
bar's progress or ``variables`` -- it keeps its own mapping, updated
directly with ``update_mapping()`` rather than through ``bar.update()``.
"""

import time

import progressbar

STEPS = 24


def main() -> None:
    status = progressbar.FormatCustomText(
        'Spam: %(spam).1f kg, eggs: %(eggs)d',
        {'spam': 0.25, 'eggs': 0},
    )
    widgets = [status, ' :: ', progressbar.Percentage()]
    with progressbar.ProgressBar(max_value=STEPS, widgets=widgets) as bar:
        for step in range(STEPS):
            status.update_mapping(eggs=step)
            bar.update(step + 1)
            time.sleep(0.005)


if __name__ == '__main__':
    main()

FormatCustomText¶

Example¶

See also¶