Skip to content

Progress

API for progress tracking ABCs and built-in backends.

Generic progress bar framework with pluggable backends.

NoProgress

Bases: Progress

A no-op progress wrapper that passes through the iterable unchanged.

__call__(iterable, *, total=None, msg='')

Yield items from the iterable unchanged.

__enter__()

Enter the context manager, returning self.

__exit__(exc_type, exc_val, exc_tb)

Exit the context manager, calling close().

child(*, leave=None)

Return self since no-op progress needs no nesting.

close()

Finalize progress display. Override in subclasses with cleanup.

context(*, msg='', start=0.0, end=1.0)

Return a shared no-op context that silently ignores updates.

Progress

Bases: ABC

A callable that wraps an iterable to display progress.

__call__(iterable, *, total=None, msg='') abstractmethod

Wrap an iterable to display a progress bar.

Parameters:

Name Type Description Default
iterable Iterable[T]

items to iterate over

 required
total int | None

total number of items. Inferred from len(iterable) when possible.

 None
msg str

description text to display

 ''

__enter__()

Enter the context manager, returning self.

__exit__(exc_type, exc_val, exc_tb)

Exit the context manager, calling close().

child(*, leave=None) abstractmethod

Return a child Progress for nested bars.

Parameters:

Name Type Description Default
leave bool | None

whether the child bar persists after completion. None inherits the parent setting.

 None

close()

Finalize progress display. Override in subclasses with cleanup.

context(*, msg='', start=0.0, end=1.0) abstractmethod

Create a push-based progress context.

Parameters:

Name Type Description Default
msg str

initial description

 ''
start float

start of the progress range (0.0-1.0)

 0.0
end float

end of the progress range (0.0-1.0)

 1.0

ProgressContext

Bases: ABC

A handle for push-based progress updates.

__enter__()

Enter the context manager, returning self.

__exit__(exc_type, exc_val, exc_tb)

Exit the context manager, calling close().

__init__(start=0.0, end=1.0)

Parameters:

Name Type Description Default
start float

start of the progress range (0.0-1.0)

 0.0
end float

end of the progress range (0.0-1.0)

 1.0

close()

Close the progress bar. Override in subclasses with cleanup.

update(*, progress, msg='') abstractmethod

Update the progress bar.

Parameters:

Name Type Description Default
progress float

fraction complete [0.0, 1.0], mapped to [start, end] range

 required
msg str

description text to display

 ''

RichProgress

Bases: Progress

Progress wrapper using the rich library (requires pip install "scinexus[rich]").

__enter__()

Enter the context manager, returning self.

__exit__(exc_type, exc_val, exc_tb)

Exit the context manager, calling close().

__init__(progress=None, refresh_per_second=10.0, leave=False, colour=None, bar_width=None, **rich_kwargs)

Parameters:

Name Type Description Default
progress Any

an existing rich.progress.Progress instance, or None to create one on first call

 None
refresh_per_second float

how often to refresh the display

 10.0
leave bool

whether completed bars persist in the display

 False
colour str | None

bar colour, applied when auto-creating the display

 None
bar_width int | None

width of the progress bar portion in characters

 None
**rich_kwargs Any

additional keyword arguments (e.g. disable=True) forwarded to rich.progress.Progress

 {}

child(*, leave=None)

Return a child RichProgress sharing the same display.

Parameters:

Name Type Description Default
leave bool | None

whether the child bar persists after completion. None inherits the parent setting.

 None

close()

Finalize the rich progress display so the cursor moves past it.

context(*, msg='', start=0.0, end=1.0)

Create a rich-backed push-based progress context.

TqdmProgress

Bases: Progress

Progress wrapper using tqdm.auto (handles TTY, Jupyter, etc.).

__enter__()

Enter the context manager, returning self.

__exit__(exc_type, exc_val, exc_tb)

Exit the context manager, calling close().

__init__(refresh_per_second=10.0, bar_format='{desc}: {bar} {n_fmt}/{total_fmt} [{elapsed}<{remaining}]', leave=None, colour=None, bar_width=None, **tqdm_kwargs)

Parameters:

Name Type Description Default
refresh_per_second float

how often to refresh the display

 10.0
bar_format str | None

custom bar format string passed to tqdm

 '{desc}: {bar} {n_fmt}/{total_fmt} [{elapsed}<{remaining}]'
leave bool | None

whether the bar persists after completion. None uses position-based logic (persist at position 0, clear otherwise).

 None
colour str | None

bar colour, forwarded to tqdm

 None
bar_width int | None

total width of the progress bar in characters

 None
**tqdm_kwargs Any

additional keyword arguments (e.g. dynamic_ncols=True) forwarded to tqdm

 {}

child(*, leave=None)

Return a child TqdmProgress at the next cursor position.

Parameters:

Name Type Description Default
leave bool | None

whether the child bar persists after completion. None inherits the parent setting.

 None

close()

Close all bars so the cursor moves past them.

context(*, msg='', start=0.0, end=1.0)

Create a tqdm-backed push-based progress context.

get_progress(show_progress=False, **kwargs)

Resolve a show_progress argument into a Progress instance.

Parameters:

Name Type Description Default
show_progress bool | Progress

If a Progress instance, returned as-is. If True, returns the module default (set via set_progress_backend, or TqdmProgress). If falsy, returns NoProgress.

 False
**kwargs Any

additional keyword arguments forwarded to the backend constructor. When a default has been set via set_progress_backend, a new instance of the same type is created with these kwargs. Ignored when show_progress is a Progress instance.

 {}

set_progress_backend(progress=None, **kwargs)

Set the default Progress used when show_progress=True.

Parameters:

Name Type Description Default
progress ProgressType | Progress | None

A Progress instance, a string literal ("tqdm" or "rich"), or None to reset to the default (TqdmProgress).

 None
**kwargs Any

additional keyword arguments forwarded to the backend constructor when progress is "tqdm" or "rich"

 {}