class napari.utils.progress(iterable=None, desc=None, total=None, nest_under=None, *args, **kwargs)[source]

Bases: tqdm.std.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.

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

Also, any keyword arguments to the ProgressBar QWidget are also accepted and will be passed to the ProgressBar.

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

Closes and deletes the progress bar widget

close_pbar()

display([msg, pos])

Update the display.

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 bar description

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

Manually update the progress bar, useful for streams such as reading files.

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

Details

clear(nolock=False)

Clear current bar display.

close()[source]

Closes and deletes the progress bar widget

display(msg=None, pos=None)[source]

Update the display.

Return type

None

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 create 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 bar description

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)

Manually update the progress bar, useful for streams such as reading files. E.g.: >>> t = tqdm(total=filesize) # Initialise >>> for current_buffer in stream: … … … t.update(len(current_buffer)) >>> t.close() The last line is highly recommended, but possibly not necessary if t.update() will be called in such a way that filesize will be exactly reached and printed.

Parameters

n (int or float, optional) – Increment to add to the internal counter of iterations [default: 1]. If using float, consider specifying {n:.3f} or similar in bar_format, or specifying unit_scale.

Returns

out – True if a display() was triggered.

Return type

bool or None

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