|Logo| tqdm ==== |Build Status| |Coverage Status| |PyPi Status| |PyPi Downloads| tqdm (read taqadum, تقدّم) means "progress" in arabic. Instantly make your loops show a progress meter - just wrap any iterable with "tqdm(iterable)", and you're done! .. code:: python from tqdm import tqdm for i in tqdm(range(9)): ... Here's what the output looks like: 76%\|████████████████████\             \| 7641/10000 [00:34<00:10, 222.22 it/s] You can also use ``trange(N)`` as a shortcut for ``tqdm(xrange(N))`` |Screenshot| Overhead is low -- about 60ns per iteration (80ns with ``gui=True``). By comparison, the well established `ProgressBar `__ has an 800ns/iter overhead. It's a matter of taste, but we also like to think our version is much more visually appealing. tqdm works on any platform (Linux/Windows/Mac), in any console or in a GUI, and is also friendly with IPython/Jupyter notebooks. Installation ------------ Latest pypi stable release ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code:: sh pip install tqdm Latest development release on github ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Pull and install in the current directory: .. code:: sh pip install -e git+https://github.com/tqdm/tqdm.git@master#egg=tqdm Documentation ------------- .. code:: python class tqdm(object): """ Decorate an iterable object, returning an iterator which acts exactly like the orignal iterable, but prints a dynamically updating progressbar every time a value is requested. """ def __init__(self, iterable=None, desc=None, total=None, leave=False, file=sys.stderr, ncols=None, mininterval=0.1, miniters=None, ascii=None, disable=False, unit='it', unit_scale=False, gui=False, dynamic_ncols=False): """ Parameters ---------- iterable : iterable, optional Iterable to decorate with a progressbar. Leave blank [default: None] to manually manage the updates. desc : str, optional Prefix for the progressbar [default: None]. total : int, 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). leave : bool, optional If [default: False], removes all traces of the progressbar upon termination of iteration. file : `io.TextIOWrapper` or `io.StringIO`, optional Specifies where to output the progress messages [default: sys.stderr]. Uses `file.write(str)` and `file.flush()` methods. ncols : int, 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). mininterval : float, optional Minimum progress update interval, in seconds [default: 0.1]. miniters : int, optional Minimum progress update interval, in iterations [default: None]. If specified, will set `mininterval` to 0. ascii : bool, optional If [default: None] or false, use unicode (smooth blocks) to fill the meter. The fallback is to use ASCII characters `1-9 #`. disable : bool Whether to disable the entire progressbar wrapper [default: False]. unit : str, optional String that will be used to define the unit of each iteration [default: 'it']. unit_scale : bool, 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]. gui : bool, optional If set, will attempt to use matplotlib animations for a graphical output [default: false]. dynamic_ncols : bool, optional If set, constantly alters `ncols` to the environment (allowing for window resizes) [default: False]. 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. """ 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. | [...] .. code:: python 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). Contributions ------------- To run the testing suite please make sure tox (http://tox.testrun.org/) is installed, then type ``tox`` from the command line. Alternatively if you don't want to use ``tox``, a Makefile is provided with the following command: .. code:: sh $ make flake8 $ make test $ make coverage See the `CONTRIBUTE `__ file for more information. License ------- `MIT LICENSE `__. Authors ------- - Casper da Costa-Luis (casperdcl) - Stephen Larroque (lrq3000) - Hadrien Mary (hadim) - Noam Yorav-Raphael (noamraph)* - Ivan Ivanov (obiwanus) - Mikhail Korobov (kmike) `*` Original author .. |Logo| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/logo.png .. |Build Status| image:: https://travis-ci.org/tqdm/tqdm.svg?branch=master :target: https://travis-ci.org/tqdm/tqdm .. |Coverage Status| image:: https://coveralls.io/repos/tqdm/tqdm/badge.svg :target: https://coveralls.io/r/tqdm/tqdm .. |PyPi Status| image:: https://img.shields.io/pypi/v/tqdm.svg :target: https://pypi.python.org/pypi/tqdm .. |PyPi Downloads| image:: https://img.shields.io/pypi/dm/tqdm.svg :target: https://pypi.python.org/pypi/tqdm .. |Screenshot| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/tqdm.gif