Backends

The Progress API includes the following backends:

• null, reporting nothing.

• tqdm, a simple TQDM-based backend.

• enlighten, a backend based on Enlighten.

Configuring the Backend

By default, the progress API uses the null backend. Actual progress-reporting backends can be configured with the PROGRESS_BACKEND environment variable, or with the set_backend() function.

progress_api.set_backend(impl: ProgressBackend) → None

progress_api.set_backend(impl: ~typing.Callable[[~BCP], ~progress_api.backends.ProgressBackend], *args: ~typing.~BCP, **kwargs: ~typing.~BCP) → None

progress_api.set_backend(impl: str, *args: Any, **kwargs: Any) → None

Set the progress backend. The backend can be specified in one of several ways:

• A string naming a progress backend. For the backends included with Progress API, this name matches the implementing module name (e.g. "enlighten"). Other backends can be registered with an entry point (see implementing-backends).

• An object implementing the backends.ProgressBackend interface.

• A subclass of backends.ProgressBackend that to instantiate.

If the backend is a class (ether a class object, or a backend name), then it is instantiated witht he supplied args and kwargs.

Parameters:

• impl – The implementation.

• *args – Arguments to pass to the implementation constructor.

• **kwargs –

  Arguments to pass to the implementation constructor.

Provided Backends

Enlighten

Progress backend using Enlighten to display progress bars. It supports multiple bars (well) and multi-state bars, and interacts well with logging and other output to standard output and error streams.

class progress_api.backends.enlighten.EnlightenProgressBackend(manager=None, state_colors=None)

Progress bar backend that doesn’t emit any progress.

Parameters:

• manager (Manager)

• state_colors (dict[str, str])

create_bar(spec)

Create a new progress bar from the given specification.

Parameters:

spec (ProgressBarSpec)

Return type:

Progress

class progress_api.backends.enlighten.EnlightenProgress(spec, bar, bars)

Parameters:

• spec (ProgressBarSpec)

• bar (Counter)

• bars (dict[str, Counter])

set_label(label)

Set a label to be used for this progress bar.

Parameters:

label (str | None)

set_total(total)

Update the progress bar’s total.

Parameters:

total (int)

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())

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)

finish()

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

TQDM

Progress bar backend for tqdm. This backend is quite limited; it does not support multiple states, and it does not have good support for multiple progress bars or interaction with logging, unless used in a Jupyter notebook environment.

class progress_api.backends.tqdm.TQDMProgressBackend(tqdm=<class 'tqdm.asyncio.tqdm_asyncio'>)

TQDM progress bar backend implementation.

Parameters:

tqdm (type[tqdm])

create_bar(spec)

Create a new progress bar from the given specification.

Parameters:

spec (ProgressBarSpec)

Return type:

Progress

class progress_api.backends.tqdm.TQDMProgress(spec, tqdm)

Parameters:

• spec (ProgressBarSpec)

• tqdm (tqdm)

set_label(label)

Set a label to be used for this progress bar.

Parameters:

label (str | None)

set_total(total)

Update the progress bar’s total.

Parameters:

total (int)

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())

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)

finish()

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

Null

Null backend that doesn’t supply any progress.

class progress_api.backends.null.NullProgressBackend

Progress bar backend that doesn’t emit any progress.

create_bar(spec)

Create a new progress bar from the given specification.

Parameters:

spec (ProgressBarSpec)

Return type:

Progress

class progress_api.backends.null.NullProgress

set_label(label)

Set a label to be used for this progress bar.

Parameters:

label (str | None)

set_total(total)

Update the progress bar’s total.

Parameters:

total (int)

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)

finish()

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

Implementing Backends

Backends are can be implemented with the following:

1. Implement the progress_api.Progress interface for the backend.

2. Implement the progress.backends.ProgressBackend interface to create progress bars using the backend.

3. Register the progress backend with the progress_api.backend entry point:

   [project.entry-points."progress_api.backend"]
   enlighten = "progress_api.backends.enlighten:EnlightenProgressBackend"
   

class progress_api.backends.ProgressBackend

Interface to be implemented by progress API backends.

Note

Progress backends must be thread-safe.

abstract create_bar(spec)

Create a new progress bar from the given specification.

Parameters:

spec (ProgressBarSpec)

Return type:

Progress

Backend Data Structures

These types are used by the progress API to call the backend.

class progress_api.backends.ProgressBarSpec(logger, label=None, total=None, unit=None, states=<factory>, leave=False)

Class encapsulating a progress bar specification to request a new progress bar from the backend.

Parameters:

• logger (Logger)

• label (str | None)

• total (int | None)

• unit (str | None)

• states (list[ProgressState])

• leave (bool)

logger: Logger

The logger this progress bar is attached to.

label: str | None = None

The progress bar label (called a description in some backends).

total: int | None = None

The initial total number of tasks/bytes/objects in the progress bar.

unit: str | None = None

The progress bar’s units. Backends that support binary byte counts should recognize the bytes unit here.

states: list[ProgressState]

List of progress states. If no states were specified by the caller, this contains one final state 'finished'.

leave: bool = False

Whether the progress bar should remain visible after completion.

check_state(state, action='warn')

Check whether the specified state is valid.

Parameters:

• state (str)

• action (Literal['ignore', 'warn', 'fail'])

Return type:

bool

class progress_api.backends.ProgressState(name, final=True)

Representation of a progress bar state.

Parameters:

• name (str)

• final (bool)

name: str

The state name.

final: bool

Whether this is a final state (an outcome). Backends that do not support multiple states should report the sum of all final states.