tqdm 3.1.3

Latest pypi stable release

pip install tqdm

Latest development release on github

Pull and install in the current directory:

pip install -e git+https://github.com/tqdm/tqdm.git@master#egg=tqdm

Parameters

• iterableiterable, optional

  Iterable to decorate with a progressbar. Leave blank [default: None] to manually manage the updates.

• descstr, optional

  Prefix for the progressbar [default: None].

• totalint, optional

  The number of expected iterations. If not given, len(iterable) is used if possible. As a last resort, only basic progress statistics are displayed (no ETA, no progressbar). If gui is True and this parameter needs subsequent updating, specify an initial arbitrary large positive integer, e.g. int(9e9).

• leavebool, optional

  If [default: False], removes all traces of the progressbar upon termination of iteration.

• fileio.TextIOWrapper or io.StringIO, optional

  Specifies where to output the progress messages [default: sys.stderr]. Uses file.write(str) and file.flush() methods.

• ncolsint, optional

  The width of the entire output message. If specified, dynamically resizes the progressbar to stay within this bound. If [default: None], attempts to use environment width. The fallback is a meter width of 10 and no limit for the counter and statistics. If 0, will not print any meter (only stats).

• minintervalfloat, optional

  Minimum progress update interval, in seconds [default: 0.1].

• maxintervalfloat, optional

  Maximum progress update interval, in seconds [default: 10.0].

• minitersint, optional

  Minimum progress update interval, in iterations [default: None]. If specified, will set mininterval to 0.

• asciibool, optional

  If [default: None] or false, use unicode (smooth blocks) to fill the meter. The fallback is to use ASCII characters 1-9 #.

• disablebool

  Whether to disable the entire progressbar wrapper [default: False].

• unitstr, optional

  String that will be used to define the unit of each iteration [default: ‘it’].

• unit_scalebool, optional

  If set, the number of iterations will be reduced/scaled automatically and a metric prefix following the International System of Units standard will be added (kilo, mega, etc.) [default: False].

• dynamic_ncolsbool, optional

  If set, constantly alters ncols to the environment (allowing for window resizes) [default: False].

• smoothingfloat

  Exponential moving average smoothing factor for speed estimates (ignored in GUI mode). Ranges from 0 (average speed) to 1 (current/instantaneous speed) [default: 0.3].

Returns

• out : decorated iterator.

  def update(self, 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
          Increment to add to the internal counter of iterations
          [default: 1].
      """

  def close(self):
      """
      Cleanup and (if leave=False) close the progressbar.
      """

def trange(*args, **kwargs):
    """
    A shortcut for tqdm(xrange(*args), **kwargs).
    On Python3+ range is used instead of xrange.
    """

class tqdm_gui(tqdm):
    """
    Experimental GUI version of tqdm!
    """

def tgrange(*args, **kwargs):
    """
    Experimental GUI version of trange!
    """

Examples and Advanced Usage

See the examples folder.

tqdm can easily support callbacks/hooks and manual updates. Here’s an example with urllib:

urllib.urlretrieve documentation

[…]

If present, the hook function will be called once

on establishment of the network connection and once after each block read

thereafter. The hook will be passed three arguments; a count of blocks

transferred so far, a block size in bytes, and the total size of the file.

[…]

import tqdm
import urllib

def my_hook(**kwargs):
    t = tqdm.tqdm(**kwargs)
    last_b = [0]

    def inner(b=1, bsize=1, tsize=None, close=False):
        if close:
            t.close()
            return
        t.total = tsize
        t.update((b - last_b[0]) * bsize) # manually update the progressbar
        last_b[0] = b
    return inner

eg_link = 'http://www.doc.ic.ac.uk/~cod11/matryoshka.zip'
eg_hook = my_hook(unit='B', unit_scale=True, leave=True, miniters=1,
                  desc=eg_link.split('/')[-1]) # all optional kwargs
urllib.urlretrieve(eg_link,
                   filename='/dev/null', reporthook=eg_hook, data=None)
eg_hook(close=True)

It is recommend to use miniters=1 whenever there is potentially large differences in iteration speed (e.g. downloading a file over a patchy connection).