|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 <https://code.google.com/p/python-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 <https://raw.githubusercontent.com/tqdm/tqdm/master/CONTRIBUTE>`__
file for more information.


License
-------

`MIT LICENSE <https://raw.githubusercontent.com/tqdm/tqdm/master/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