napari.utils.progress#

class napari.utils.progress(*_, **__)[source]#

Bases: tqdm

This class inherits from tqdm and provides an interface for progress bars in the napari viewer. Progress bars can be created directly by wrapping an iterable or by providing a total number of expected updates.

While this interface is primarily designed to be displayed in the viewer, it can also be used without a viewer open, in which case it behaves identically to tqdm and produces the progress bar in the terminal.

See tqdm.tqdm API for valid args and kwargs: https://tqdm.github.io/docs/tqdm/

Examples

>>> def long_running(steps=10, delay=0.1):
...     for i in progress(range(steps)):
...         sleep(delay)

it can also be used as a context manager:

>>> def long_running(steps=10, repeats=4, delay=0.1):
...     with progress(range(steps)) as pbr:
...         for i in pbr:
...             sleep(delay)

or equivalently, using the progrange shorthand

with progrange(steps) as pbr:
    for i in pbr:
        sleep(delay)

For manual updates:

>>> def manual_updates(total):
...     pbr = progress(total=total)
...     sleep(10)
...     pbr.set_description("Step 1 Complete")
...     pbr.update(1)
...     # must call pbr.close() when using outside for loop
...     # or context manager
...     pbr.close()

Methods

`clear`([nolock])	Clear current bar display.
`close`()	Close progress object and emit event.
`display`([msg, pos])	Update the display and emit eta event.
`external_write_mode`([file, nolock])	Disable tqdm within context and refresh tqdm when exits.
`format_interval`(t)	Formats a number of seconds as a clock time, [H:]MM:SS
`format_meter`(n, total, elapsed[, ncols, ...])	Return a string-based progress bar given some parameters
`format_num`(n)	Intelligent scientific notation (.3g).
`format_sizeof`(num[, suffix, divisor])	Formats a number (greater than unity) with SI Order of Magnitude prefixes.
`get_lock`()	Get the global lock.
`increment_with_overflow`()	Update if not exceeding total, else set indeterminate range.
`moveto`(n)
`pandas`(**tqdm_kwargs)	Registers the current tqdm class with
`refresh`([nolock, lock_args])	Force refresh the display of this bar.
`reset`([total])	Resets to 0 iterations for repeated use.
`set_description`(desc)	Update progress description and emit description event.
`set_description_str`([desc, refresh])	Set/modify description without ': ' appended.
`set_lock`(lock)	Set the global lock.
`set_postfix`([ordered_dict, refresh])	Set/modify postfix (additional stats) with automatic formatting based on datatype.
`set_postfix_str`([s, refresh])	Postfix without dictionary expansion, similar to prefix handling.
`status_printer`(file)	Manage the printing and in-place updating of a line of characters.
`unpause`()	Restart tqdm timer from last print time.
`update`([n])	Update progress value by n and emit value event
`wrapattr`(stream, method[, total, bytes])	stream : file-like object. method : str, "read" or "write". The result of read() and the first argument of write() should have a len().
`write`(s[, file, end, nolock])	Print a message via tqdm (without overlap with bars).

Attributes

`format_dict`	Public API for read-only member access.
`monitor`
`monitor_interval`
`total`

Details

clear(nolock=False)#: Clear current bar display.

close()[source]#: Close progress object and emit event.

display(msg: str | None = None, pos: int | None = None) → None[source]#: Update the display and emit eta event.

classmethod external_write_mode(file=None, nolock=False)#: Disable tqdm within context and refresh tqdm when exits. Useful when writing to standard output stream

property format_dict#: Public API for read-only member access.

static format_interval(t)#

Formats a number of seconds as a clock time, [H:]MM:SS

Parameters:: t (int) – Number of seconds.
Returns:: out – [H:]MM:SS
Return type:: str

static format_meter(n, total, elapsed, ncols=None, prefix='', ascii=False, unit='it', unit_scale=False, rate=None, bar_format=None, postfix=None, unit_divisor=1000, initial=0, colour=None, **extra_kwargs)#

Return a string-based progress bar given some parameters

Parameters:

n (int or float) – Number of finished iterations.
total (int or float) – The expected total number of iterations. If meaningless (None), only basic progress statistics are displayed (no ETA).
elapsed (float) – Number of seconds passed since start.
ncols (int, optional) – The width of the entire output message. If specified, dynamically resizes {bar} to stay within this bound [default: None]. If 0, will not print any bar (only stats). The fallback is {bar:10}.
prefix (str, optional) – Prefix message (included in total width) [default: ‘’]. Use as {desc} in bar_format string.
ascii (bool, optional or str, optional) – If not set, use unicode (smooth blocks) to fill the meter [default: False]. The fallback is to use ASCII characters “ 123456789#”.
unit (str, optional) – The iteration unit [default: ‘it’].
unit_scale (bool or int or float, optional) – If 1 or True, the number of iterations will be printed with an appropriate SI metric prefix (k = 10^3, M = 10^6, etc.) [default: False]. If any other non-zero number, will scale total and n.
rate (float, optional) – Manual override for iteration rate. If [default: None], uses n/elapsed.
bar_format (str, optional) –
Specify a custom bar string formatting. May impact performance. [default: ‘{l_bar}{bar}{r_bar}’], where l_bar=’{desc}: {percentage:3.0f}%|’ and r_bar=’| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, ‘

’{rate_fmt}{postfix}]’

Possible vars: l_bar, bar, r_bar, n, n_fmt, total, total_fmt,
percentage, elapsed, elapsed_s, ncols, nrows, desc, unit, rate, rate_fmt, rate_noinv, rate_noinv_fmt, rate_inv, rate_inv_fmt, postfix, unit_divisor, remaining, remaining_s, eta.

Note that a trailing “: “ is automatically removed after {desc} if the latter is empty.
postfix (*, optional) – Similar to prefix, but placed at the end (e.g. for additional stats). Note: postfix is usually a string (not a dict) for this method, and will if possible be set to postfix = ‘, ‘ + postfix. However other types are supported (#382).
unit_divisor (float, optional) – [default: 1000], ignored unless unit_scale is True.
initial (int or float, optional) – The initial counter value [default: 0].
colour (str, optional) – Bar colour (e.g. ‘green’, ‘#00ff00’).

Returns:

out

Return type:

Formatted meter and stats, ready to display.

static format_num(n)#

Intelligent scientific notation (.3g).

Parameters:: n (int or float or Numeric) – A Number.
Returns:: out – Formatted number.
Return type:: str

static format_sizeof(num, suffix='', divisor=1000)#

Formats a number (greater than unity) with SI Order of Magnitude prefixes.

Parameters:

num (float) – Number ( >= 1) to format.
suffix (str, optional) – Post-postfix [default: ‘’].
divisor (float, optional) – Divisor between prefixes [default: 1000].

Returns:

out – Number with Order of Magnitude SI unit postfix.

Return type:

str

classmethod get_lock()#: Get the global lock. Construct it if it does not exist.

increment_with_overflow()[source]#: Update if not exceeding total, else set indeterminate range.

classmethod pandas(**tqdm_kwargs)#

Registers the current tqdm class with: pandas.core. ( frame.DataFrame | series.Series | groupby.(generic.)DataFrameGroupBy | groupby.(generic.)SeriesGroupBy ).progress_apply

A new instance will be created every time progress_apply is called, and each instance will automatically close() upon completion.

Parameters:: tqdm_kwargs (arguments for the tqdm instance) –

Examples

>>> import pandas as pd
>>> import numpy as np
>>> from tqdm import tqdm
>>> from tqdm.gui import tqdm as tqdm_gui
>>>
>>> df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))
>>> tqdm.pandas(ncols=50)  # can use tqdm_gui, optional kwargs, etc
>>> # Now you can use `progress_apply` instead of `apply`
>>> df.groupby(0).progress_apply(lambda x: x**2)

References

<https://stackoverflow.com/questions/18603270/ progress-indicator-during-pandas-operations-python>

refresh(nolock=False, lock_args=None)#

Force refresh the display of this bar.

Parameters:

nolock (bool, optional) – If True, does not lock. If [default: False]: calls acquire() on internal lock.
lock_args (tuple, optional) – Passed to internal lock’s acquire(). If specified, will only display() if acquire() returns True.

reset(total=None)#

Resets to 0 iterations for repeated use.

Consider combining with leave=True.

Parameters:: total (int or float, optional. Total to use for the new bar.) –

set_description(desc)[source]#: Update progress description and emit description event.

set_description_str(desc=None, refresh=True)#: Set/modify description without ‘: ‘ appended.

classmethod set_lock(lock)#: Set the global lock.

set_postfix(ordered_dict=None, refresh=True, **kwargs)#

Set/modify postfix (additional stats) with automatic formatting based on datatype.

Parameters:

ordered_dict (dict or OrderedDict, optional) –
refresh (bool, optional) – Forces refresh [default: True].
kwargs (dict, optional) –

set_postfix_str(s='', refresh=True)#: Postfix without dictionary expansion, similar to prefix handling.

static status_printer(file)#: Manage the printing and in-place updating of a line of characters. Note that if the string is longer than a line, then in-place updating may not work (it will print a new line at each refresh).

unpause()#: Restart tqdm timer from last print time.

update(n=1)[source]#: Update progress value by n and emit value event

classmethod wrapattr(stream, method, total=None, bytes=True, **tqdm_kwargs)#

stream : file-like object. method : str, “read” or “write”. The result of read() and

the first argument of write() should have a len().

>>> with tqdm.wrapattr(file_obj, "read", total=file_obj.size) as fobj:
...     while True:
...         chunk = fobj.read(chunk_size)
...         if not chunk:
...             break

classmethod write(s, file=None, end='\n', nolock=False)#: Print a message via tqdm (without overlap with bars).