Progress API¶

There is one function and one class of primray interest to libraries using the progress API: make_progress() and its return class, Progress.

Creating Progress Bars¶

progress_api.make_progress(logger=None, label=None, total=None, unit=None, outcomes=None, states=None, leave=False)¶

Primary API for creating progress reporters. This is the function client code will use the most often.

The outcomes and states variables configure multiple states for multi-state progress bars. See Multiple States for details on how states are handled and how these arguments configure them.

Parameters:

logger (str | Logger | None) – The logger to attach this progress to.
label (str | None) – A label for the progress display.
total (int | None) – The total for the progress (if known).
unit (str | None) – A label for the units. If ‘bytes’ is supplied, some backends will use binary suffixes (MiB, etc.).
outcomes (str | list[str] | None) – The names of different outcomes for a multi-state progress bar
states (str | list[str] | None) – The names of different sequential states for a multi-state progress bars.
leave (bool) – Whether to leave the progress bar visible after it has finished.

Return type:

Progress

progress_api.null_progress()¶

Create a null progress bar, regardless of the configured backend. This is useful to allow progress reporting to be optional without littering code with conditionals.

Return type:: Progress

Progress Bar Interface¶

class progress_api.Progress¶

Uniform interface to progress reporting APIs.

Progress bars can be used as context managers; finish() is called when the context is exited.

name¶

The name of the logger this progress bar is attached to.

Type:: str

abstract set_label(label)¶

Set a label to be used for this progress bar.

Parameters:: label (str | None)
Return type:: None

abstract set_total(total)¶

Update the progress bar’s total.

Parameters:: total (int)
Return type:: None

set_metric(label, value, fmt=None)¶

Set an ”metric” on the progress bar. This is a secondary value that will be displayed along with ETA; it is intended for things like a current measurement (e.g. the current training loss for training a machine learning model).

The format specifier is put into a format string that is passed to str.format(), and must include the braces. For example, to format a percentage with 2 decimal points:

progress.set_meter('buffer', buf_fill_pct, '{:.2f}%')

Only one meter can be set at a time. A new meter will replace any existing meter. This method remembers the label and format, even if value is None, so the metric value can be supplied in update.

Parameters:

label (str) – the label for the metric
value (int | str | float | None) – the metric value, or None to hide the metric.
fmt (str | None) – a format specifier (suitable for use in str.format())

Return type:

None

abstract update(n=1, state=None, src_state=None, metric=None)¶

Update the progress bar.

Parameters:

n (int) – the amount to increment the progress bar counter by.
state (str | None) – the name of the progress bar state to increment.
src_state (str | None) – the state to move the progress items from, if applicable.
metric (int | str | float | None)

Return type:

None

abstract finish()¶

Finish and close this progress bar, releasing resources as appropriate.

Return type:: None

Multiple States¶

The progress API supports multiple states and outcomes in progress reports (an outcome is just a state that represents one of the various ways a task can be finished, such as success or error). make_progress() has two parameters to provide the state configuration for a progress bar. They interact as follows:

If both states and outcomes are provided, then ouctomes is a list of final task states (succeeded, failed, etc.), and states is a list of non-final states an item may pass through on its way to a final state. States should usually be specified in reverse order, so items typically pass from the last state to the first (e.g. connecting, loading, parsing, etc.), and finally to an outcome, although this is not enforced (the progress API does not track individual items, only the current count in each state). When all items are completed, the total across the outcomes should equal the total number of items.
If only outcomes is specified, then they are a list of final task states, and no non-final states are reported.
If only states is specified, then the first state is considered the final state, and other states are intermediate in-progress states.
If neither states nor outcomes is specified, the progress bar is configured with a single final state 'finished'.

State names usually aren’t displayed, but they can be logged by backends, and configurable backends will use them to determine colors or other visuals. Backends that only support a single state should report the sum of all final states as their completed item count.

It is not recommended to include an initial state; the initial state can be modeled by the fraction of the total that has not yet been added to any state.

For an example, if you want to track final states loaded and failed, with intermediate states connecting and loading, you would call make_progress() as follows:

p = make_progress(
    total,
    outcomes=["loaded", "failed"],
    states=["loading", "connecting"]
)

For a single outcome with intermediate states, you can do:

p = make_progress(
    total,
    states=["finished", "in-progress", "queued"]
)