tqdm

Name	tqdm JSON
Version	4.67.0 JSON
	download
home_page	None
Summary	Fast, Extensible Progress Meter
upload_time	2024-11-06 16:35:37
maintainer	None
docs_url	None
author	None
requires_python	>=3.7
license	MPL-2.0 AND MIT
keywords	progressbar progressmeter progress bar meter rate eta console terminal time
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            |Logo|

tqdm
====

|Py-Versions| |Versions| |Conda-Forge-Status| |Docker| |Snapcraft|

|Build-Status| |Coverage-Status| |Branch-Coverage-Status| |Codacy-Grade| |Libraries-Rank| |PyPI-Downloads|

|LICENCE| |OpenHub-Status| |binder-demo| |awesome-python|

``tqdm`` derives from the Arabic word *taqaddum* (تقدّم) which can mean "progress,"
and is an abbreviation for "I love you so much" in Spanish (*te quiero demasiado*).

Instantly make your loops show a smart progress meter - just wrap any
iterable with ``tqdm(iterable)``, and you're done!

.. code:: python

    from tqdm import tqdm
    for i in tqdm(range(10000)):
        ...

``76%|████████████████████████        | 7568/10000 [00:33<00:10, 229.00it/s]``

``trange(N)`` can be also used as a convenient shortcut for
``tqdm(range(N))``.

|Screenshot|
    |Video| |Slides| |Merch|

It can also be executed as a module with pipes:

.. code:: sh

    $ seq 9999999 | tqdm --bytes | wc -l
    75.2MB [00:00, 217MB/s]
    9999999

    $ tar -zcf - docs/ | tqdm --bytes --total `du -sb docs/ | cut -f1` \
        > backup.tgz
     32%|██████████▍                      | 8.89G/27.9G [00:42<01:31, 223MB/s]

Overhead is low -- about 60ns per iteration (80ns with ``tqdm.gui``), and is
unit tested against performance regression.
By comparison, the well-established
`ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has
an 800ns/iter overhead.

In addition to its low overhead, ``tqdm`` uses smart algorithms to predict
the remaining time and to skip unnecessary iteration displays, which allows
for a negligible overhead in most cases.

``tqdm`` works on any platform
(Linux, Windows, Mac, FreeBSD, NetBSD, Solaris/SunOS),
in any console or in a GUI, and is also friendly with IPython/Jupyter notebooks.

``tqdm`` does not require any dependencies (not even ``curses``!), just
Python and an environment supporting ``carriage return \r`` and
``line feed \n`` control characters.

------------------------------------------

.. contents:: Table of contents
   :backlinks: top
   :local:


Installation
------------

Latest PyPI stable release
~~~~~~~~~~~~~~~~~~~~~~~~~~

|Versions| |PyPI-Downloads| |Libraries-Dependents|

.. code:: sh

    pip install tqdm

Latest development release on GitHub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

|GitHub-Status| |GitHub-Stars| |GitHub-Commits| |GitHub-Forks| |GitHub-Updated|

Pull and install pre-release ``devel`` branch:

.. code:: sh

    pip install "git+https://github.com/tqdm/tqdm.git@devel#egg=tqdm"

Latest Conda release
~~~~~~~~~~~~~~~~~~~~

|Conda-Forge-Status|

.. code:: sh

    conda install -c conda-forge tqdm

Latest Snapcraft release
~~~~~~~~~~~~~~~~~~~~~~~~

|Snapcraft|

There are 3 channels to choose from:

.. code:: sh

    snap install tqdm  # implies --stable, i.e. latest tagged release
    snap install tqdm  --candidate  # master branch
    snap install tqdm  --edge  # devel branch

Note that ``snap`` binaries are purely for CLI use (not ``import``-able), and
automatically set up ``bash`` tab-completion.

Latest Docker release
~~~~~~~~~~~~~~~~~~~~~

|Docker|

.. code:: sh

    docker pull tqdm/tqdm
    docker run -i --rm tqdm/tqdm --help

Other
~~~~~

There are other (unofficial) places where ``tqdm`` may be downloaded, particularly for CLI use:

|Repology|

.. |Repology| image:: https://repology.org/badge/tiny-repos/python:tqdm.svg
   :target: https://repology.org/project/python:tqdm/versions

Changelog
---------

The list of all changes is available either on GitHub's Releases:
|GitHub-Status|, on the
`wiki <https://github.com/tqdm/tqdm/wiki/Releases>`__, or on the
`website <https://tqdm.github.io/releases>`__.


Usage
-----

``tqdm`` is very versatile and can be used in a number of ways.
The three main ones are given below.

Iterable-based
~~~~~~~~~~~~~~

Wrap ``tqdm()`` around any iterable:

.. code:: python

    from tqdm import tqdm
    from time import sleep

    text = ""
    for char in tqdm(["a", "b", "c", "d"]):
        sleep(0.25)
        text = text + char

``trange(i)`` is a special optimised instance of ``tqdm(range(i))``:

.. code:: python

    from tqdm import trange

    for i in trange(100):
        sleep(0.01)

Instantiation outside of the loop allows for manual control over ``tqdm()``:

.. code:: python

    pbar = tqdm(["a", "b", "c", "d"])
    for char in pbar:
        sleep(0.25)
        pbar.set_description("Processing %s" % char)

Manual
~~~~~~

Manual control of ``tqdm()`` updates using a ``with`` statement:

.. code:: python

    with tqdm(total=100) as pbar:
        for i in range(10):
            sleep(0.1)
            pbar.update(10)

If the optional variable ``total`` (or an iterable with ``len()``) is
provided, predictive stats are displayed.

``with`` is also optional (you can just assign ``tqdm()`` to a variable,
but in this case don't forget to ``del`` or ``close()`` at the end:

.. code:: python

    pbar = tqdm(total=100)
    for i in range(10):
        sleep(0.1)
        pbar.update(10)
    pbar.close()

Module
~~~~~~

Perhaps the most wonderful use of ``tqdm`` is in a script or on the command
line. Simply inserting ``tqdm`` (or ``python -m tqdm``) between pipes will pass
through all ``stdin`` to ``stdout`` while printing progress to ``stderr``.

The example below demonstrate counting the number of lines in all Python files
in the current directory, with timing information included.

.. code:: sh

    $ time find . -name '*.py' -type f -exec cat \{} \; | wc -l
    857365

    real    0m3.458s
    user    0m0.274s
    sys     0m3.325s

    $ time find . -name '*.py' -type f -exec cat \{} \; | tqdm | wc -l
    857366it [00:03, 246471.31it/s]
    857365

    real    0m3.585s
    user    0m0.862s
    sys     0m3.358s

Note that the usual arguments for ``tqdm`` can also be specified.

.. code:: sh

    $ find . -name '*.py' -type f -exec cat \{} \; |
        tqdm --unit loc --unit_scale --total 857366 >> /dev/null
    100%|█████████████████████████████████| 857K/857K [00:04<00:00, 246Kloc/s]

Backing up a large directory?

.. code:: sh

    $ tar -zcf - docs/ | tqdm --bytes --total `du -sb docs/ | cut -f1` \
      > backup.tgz
     44%|██████████████▊                   | 153M/352M [00:14<00:18, 11.0MB/s]

This can be beautified further:

.. code:: sh

    $ BYTES=$(du -sb docs/ | cut -f1)
    $ tar -cf - docs/ \
      | tqdm --bytes --total "$BYTES" --desc Processing | gzip \
      | tqdm --bytes --total "$BYTES" --desc Compressed --position 1 \
      > ~/backup.tgz
    Processing: 100%|██████████████████████| 352M/352M [00:14<00:00, 30.2MB/s]
    Compressed:  42%|█████████▎            | 148M/352M [00:14<00:19, 10.9MB/s]

Or done on a file level using 7-zip:

.. code:: sh

    $ 7z a -bd -r backup.7z docs/ | grep Compressing \
      | tqdm --total $(find docs/ -type f | wc -l) --unit files \
      | grep -v Compressing
    100%|██████████████████████████▉| 15327/15327 [01:00<00:00, 712.96files/s]

Pre-existing CLI programs already outputting basic progress information will
benefit from ``tqdm``'s ``--update`` and ``--update_to`` flags:

.. code:: sh

    $ seq 3 0.1 5 | tqdm --total 5 --update_to --null
    100%|████████████████████████████████████| 5.0/5 [00:00<00:00, 9673.21it/s]
    $ seq 10 | tqdm --update --null  # 1 + 2 + ... + 10 = 55 iterations
    55it [00:00, 90006.52it/s]

FAQ and Known Issues
--------------------

|GitHub-Issues|

The most common issues relate to excessive output on multiple lines, instead
of a neat one-line progress bar.

- Consoles in general: require support for carriage return (``CR``, ``\r``).

  * Some cloud logging consoles which don't support ``\r`` properly
    (`cloudwatch <https://github.com/tqdm/tqdm/issues/966>`__,
    `K8s <https://github.com/tqdm/tqdm/issues/1319>`__) may benefit from
    ``export TQDM_POSITION=-1``.

- Nested progress bars:

  * Consoles in general: require support for moving cursors up to the
    previous line. For example,
    `IDLE <https://github.com/tqdm/tqdm/issues/191#issuecomment-230168030>`__,
    `ConEmu <https://github.com/tqdm/tqdm/issues/254>`__ and
    `PyCharm <https://github.com/tqdm/tqdm/issues/203>`__ (also
    `here <https://github.com/tqdm/tqdm/issues/208>`__,
    `here <https://github.com/tqdm/tqdm/issues/307>`__, and
    `here <https://github.com/tqdm/tqdm/issues/454#issuecomment-335416815>`__)
    lack full support.
  * Windows: additionally may require the Python module ``colorama``
    to ensure nested bars stay within their respective lines.

- Unicode:

  * Environments which report that they support unicode will have solid smooth
    progressbars. The fallback is an ``ascii``-only bar.
  * Windows consoles often only partially support unicode and thus
    `often require explicit ascii=True <https://github.com/tqdm/tqdm/issues/454#issuecomment-335416815>`__
    (also `here <https://github.com/tqdm/tqdm/issues/499>`__). This is due to
    either normal-width unicode characters being incorrectly displayed as
    "wide", or some unicode characters not rendering.

- Wrapping generators:

  * Generator wrapper functions tend to hide the length of iterables.
    ``tqdm`` does not.
  * Replace ``tqdm(enumerate(...))`` with ``enumerate(tqdm(...))`` or
    ``tqdm(enumerate(x), total=len(x), ...)``.
    The same applies to ``numpy.ndenumerate``.
  * Replace ``tqdm(zip(a, b))`` with ``zip(tqdm(a), b)`` or even
    ``zip(tqdm(a), tqdm(b))``.
  * The same applies to ``itertools``.
  * Some useful convenience functions can be found under ``tqdm.contrib``.

- `No intermediate output in docker-compose <https://github.com/tqdm/tqdm/issues/771>`__:
  use ``docker-compose run`` instead of ``docker-compose up`` and ``tty: true``.

- Overriding defaults via environment variables:
  e.g. in CI/cloud jobs, ``export TQDM_MININTERVAL=5`` to avoid log spam.
  This override logic is handled by the ``tqdm.utils.envwrap`` decorator
  (useful independent of ``tqdm``).

If you come across any other difficulties, browse and file |GitHub-Issues|.

Documentation
-------------

|Py-Versions| |README-Hits| (Since 19 May 2016)

.. code:: python

    class tqdm():
      """
      Decorate an iterable object, returning an iterator which acts exactly
      like the original iterable, but prints a dynamically updating
      progressbar every time a value is requested.
      """

      @envwrap("TQDM_")  # override defaults via env vars
      def __init__(self, iterable=None, desc=None, total=None, leave=True,
                   file=None, ncols=None, mininterval=0.1,
                   maxinterval=10.0, miniters=None, ascii=None, disable=False,
                   unit='it', unit_scale=False, dynamic_ncols=False,
                   smoothing=0.3, bar_format=None, initial=0, position=None,
                   postfix=None, unit_divisor=1000, write_bytes=False,
                   lock_args=None, nrows=None, colour=None, delay=0):

Parameters
~~~~~~~~~~

* iterable  : iterable, optional  
    Iterable to decorate with a progressbar.
    Leave blank to manually manage the updates.
* desc  : str, optional  
    Prefix for the progressbar.
* total  : int or float, optional  
    The number of expected iterations. If unspecified,
    len(iterable) is used if possible. If float("inf") or 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 number,
    e.g. 9e9.
* leave  : bool, optional  
    If [default: True], keeps all traces of the progressbar
    upon termination of iteration.
    If ``None``, will leave only if ``position`` is ``0``.
* 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.  For encoding, see ``write_bytes``.
* ncols  : int, optional  
    The width of the entire output message. If specified,
    dynamically resizes the progressbar to stay within this bound.
    If unspecified, 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 display update interval [default: 0.1] seconds.
* maxinterval  : float, optional  
    Maximum progress display update interval [default: 10] seconds.
    Automatically adjusts ``miniters`` to correspond to ``mininterval``
    after long display update lag. Only works if ``dynamic_miniters``
    or monitor thread is enabled.
* miniters  : int or float, optional  
    Minimum progress display update interval, in iterations.
    If 0 and ``dynamic_miniters``, will automatically adjust to equal
    ``mininterval`` (more CPU efficient, good for tight loops).
    If > 0, will skip display of specified number of iterations.
    Tweak this and ``mininterval`` to get very efficient loops.
    If your progress is erratic with both fast and slow iterations
    (network, skipping items, etc) you should set miniters=1.
* ascii  : bool or str, optional  
    If unspecified or False, use unicode (smooth blocks) to fill
    the meter. The fallback is to use ASCII characters " 123456789#".
* disable  : bool, optional  
    Whether to disable the entire progressbar wrapper
    [default: False]. If set to None, disable on non-TTY.
* unit  : str, optional  
    String that will be used to define the unit of each iteration
    [default: it].
* unit_scale  : bool or int or float, optional  
    If 1 or True, 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]. If any other non-zero
    number, will scale ``total`` and ``n``.
* dynamic_ncols  : bool, optional  
    If set, constantly alters ``ncols`` and ``nrows`` to the
    environment (allowing for window resizes) [default: False].
* smoothing  : float, optional  
    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].
* 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.
* initial  : int or float, optional  
    The initial counter value. Useful when restarting a progress
    bar [default: 0]. If using float, consider specifying ``{n:.3f}``
    or similar in ``bar_format``, or specifying ``unit_scale``.
* position  : int, optional  
    Specify the line offset to print this bar (starting from 0)
    Automatic if unspecified.
    Useful to manage multiple bars at once (eg, from threads).
* postfix  : dict or ``*``, optional  
    Specify additional stats to display at the end of the bar.
    Calls ``set_postfix(**postfix)`` if possible (dict).
* unit_divisor  : float, optional  
    [default: 1000], ignored unless ``unit_scale`` is True.
* write_bytes  : bool, optional  
    Whether to write bytes. If (default: False) will write unicode.
* lock_args  : tuple, optional  
    Passed to ``refresh`` for intermediate output
    (initialisation, iterating, and updating).
* nrows  : int, optional  
    The screen height. If specified, hides nested bars outside this
    bound. If unspecified, attempts to use environment height.
    The fallback is 20.
* colour  : str, optional  
    Bar colour (e.g. 'green', '#00ff00').
* delay  : float, optional  
    Don't display until [default: 0] seconds have elapsed.

Extra CLI Options
~~~~~~~~~~~~~~~~~

* delim  : chr, optional  
    Delimiting character [default: '\n']. Use '\0' for null.
    N.B.: on Windows systems, Python converts '\n' to '\r\n'.
* buf_size  : int, optional  
    String buffer size in bytes [default: 256]
    used when ``delim`` is specified.
* bytes  : bool, optional  
    If true, will count bytes, ignore ``delim``, and default
    ``unit_scale`` to True, ``unit_divisor`` to 1024, and ``unit`` to 'B'.
* tee  : bool, optional  
    If true, passes ``stdin`` to both ``stderr`` and ``stdout``.
* update  : bool, optional  
    If true, will treat input as newly elapsed iterations,
    i.e. numbers to pass to ``update()``. Note that this is slow
    (~2e5 it/s) since every input must be decoded as a number.
* update_to  : bool, optional  
    If true, will treat input as total elapsed iterations,
    i.e. numbers to assign to ``self.n``. Note that this is slow
    (~2e5 it/s) since every input must be decoded as a number.
* null  : bool, optional  
    If true, will discard input (no stdout).
* manpath  : str, optional  
    Directory in which to install tqdm man pages.
* comppath  : str, optional  
    Directory in which to place tqdm completion.
* log  : str, optional  
    CRITICAL|FATAL|ERROR|WARN(ING)|[default: 'INFO']|DEBUG|NOTSET.

Returns
~~~~~~~

* out  : decorated iterator.  

.. code:: python

    class tqdm():
      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 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  : bool or None
              True if a ``display()`` was triggered.
          """

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

      def clear(self, nomove=False):
          """Clear current bar display."""

      def refresh(self):
          """
          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``.
          """

      def unpause(self):
          """Restart tqdm timer from last print time."""

      def reset(self, 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.
          """

      def set_description(self, desc=None, refresh=True):
          """
          Set/modify description of the progress bar.

          Parameters
          ----------
          desc  : str, optional
          refresh  : bool, optional
              Forces refresh [default: True].
          """

      def set_postfix(self, ordered_dict=None, refresh=True, **tqdm_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
          """

      @classmethod
      def write(cls, s, file=sys.stdout, end="\n"):
          """Print a message via tqdm (without overlap with bars)."""

      @property
      def format_dict(self):
          """Public API for read-only member access."""

      def display(self, msg=None, pos=None):
          """
          Use ``self.sp`` to display ``msg`` in the specified ``pos``.

          Consider overloading this function when inheriting to use e.g.:
          ``self.some_frontend(**self.format_dict)`` instead of ``self.sp``.

          Parameters
          ----------
          msg  : str, optional. What to display (default: ``repr(self)``).
          pos  : int, optional. Position to ``moveto``
            (default: ``abs(self.pos)``).
          """

      @classmethod
      @contextmanager
      def wrapattr(cls, 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
      def pandas(cls, *targs, **tqdm_kwargs):
          """Registers the current `tqdm` class with `pandas`."""

    def trange(*args, **tqdm_kwargs):
        """Shortcut for `tqdm(range(*args), **tqdm_kwargs)`."""

Convenience Functions
~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    def tqdm.contrib.tenumerate(iterable, start=0, total=None,
                                tqdm_class=tqdm.auto.tqdm, **tqdm_kwargs):
        """Equivalent of `numpy.ndenumerate` or builtin `enumerate`."""

    def tqdm.contrib.tzip(iter1, *iter2plus, **tqdm_kwargs):
        """Equivalent of builtin `zip`."""

    def tqdm.contrib.tmap(function, *sequences, **tqdm_kwargs):
        """Equivalent of builtin `map`."""

Submodules
~~~~~~~~~~

.. code:: python

    class tqdm.notebook.tqdm(tqdm.tqdm):
        """IPython/Jupyter Notebook widget."""

    class tqdm.auto.tqdm(tqdm.tqdm):
        """Automatically chooses beween `tqdm.notebook` and `tqdm.tqdm`."""

    class tqdm.asyncio.tqdm(tqdm.tqdm):
      """Asynchronous version."""
      @classmethod
      def as_completed(cls, fs, *, loop=None, timeout=None, total=None,
                       **tqdm_kwargs):
          """Wrapper for `asyncio.as_completed`."""

    class tqdm.gui.tqdm(tqdm.tqdm):
        """Matplotlib GUI version."""

    class tqdm.tk.tqdm(tqdm.tqdm):
        """Tkinter GUI version."""

    class tqdm.rich.tqdm(tqdm.tqdm):
        """`rich.progress` version."""

    class tqdm.keras.TqdmCallback(keras.callbacks.Callback):
        """Keras callback for epoch and batch progress."""

    class tqdm.dask.TqdmCallback(dask.callbacks.Callback):
        """Dask callback for task progress."""


``contrib``
+++++++++++

The ``tqdm.contrib`` package also contains experimental modules:

- ``tqdm.contrib.itertools``: Thin wrappers around ``itertools``
- ``tqdm.contrib.concurrent``: Thin wrappers around ``concurrent.futures``
- ``tqdm.contrib.slack``: Posts to `Slack <https://slack.com>`__ bots
- ``tqdm.contrib.discord``: Posts to `Discord <https://discord.com>`__ bots
- ``tqdm.contrib.telegram``: Posts to `Telegram <https://telegram.org>`__ bots
- ``tqdm.contrib.bells``: Automagically enables all optional features

  * ``auto``, ``pandas``, ``slack``, ``discord``, ``telegram``

Examples and Advanced Usage
---------------------------

- See the `examples <https://github.com/tqdm/tqdm/tree/master/examples>`__
  folder;
- import the module and run ``help()``;
- consult the `wiki <https://github.com/tqdm/tqdm/wiki>`__;

  * this has an
    `excellent article <https://github.com/tqdm/tqdm/wiki/How-to-make-a-great-Progress-Bar>`__
    on how to make a **great** progressbar;

- check out the `slides from PyData London <https://tqdm.github.io/PyData2019/slides.html>`__, or
- run the |binder-demo|.

Description and additional stats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Custom information can be displayed and updated dynamically on ``tqdm`` bars
with the ``desc`` and ``postfix`` arguments:

.. code:: python

    from tqdm import tqdm, trange
    from random import random, randint
    from time import sleep

    with trange(10) as t:
        for i in t:
            # Description will be displayed on the left
            t.set_description('GEN %i' % i)
            # Postfix will be displayed on the right,
            # formatted automatically based on argument's datatype
            t.set_postfix(loss=random(), gen=randint(1,999), str='h',
                          lst=[1, 2])
            sleep(0.1)

    with tqdm(total=10, bar_format="{postfix[0]} {postfix[1][value]:>8.2g}",
              postfix=["Batch", {"value": 0}]) as t:
        for i in range(10):
            sleep(0.1)
            t.postfix[1]["value"] = i / 2
            t.update()

Points to remember when using ``{postfix[...]}`` in the ``bar_format`` string:

- ``postfix`` also needs to be passed as an initial argument in a compatible
  format, and
- ``postfix`` will be auto-converted to a string if it is a ``dict``-like
  object. To prevent this behaviour, insert an extra item into the dictionary
  where the key is not a string.

Additional ``bar_format`` parameters may also be defined by overriding
``format_dict``, and the bar itself may be modified using ``ascii``:

.. code:: python

    from tqdm import tqdm
    class TqdmExtraFormat(tqdm):
        """Provides a `total_time` format parameter"""
        @property
        def format_dict(self):
            d = super().format_dict
            total_time = d["elapsed"] * (d["total"] or 0) / max(d["n"], 1)
            d.update(total_time=self.format_interval(total_time) + " in total")
            return d

    for i in TqdmExtraFormat(
          range(9), ascii=" .oO0",
          bar_format="{total_time}: {percentage:.0f}%|{bar}{r_bar}"):
        if i == 4:
            break

.. code::

    00:00 in total: 44%|0000.     | 4/9 [00:00<00:00, 962.93it/s]

Note that ``{bar}`` also supports a format specifier ``[width][type]``.

- ``width``

  * unspecified (default): automatic to fill ``ncols``
  * ``int >= 0``: fixed width overriding ``ncols`` logic
  * ``int < 0``: subtract from the automatic default

- ``type``

  * ``a``: ascii (``ascii=True`` override)
  * ``u``: unicode (``ascii=False`` override)
  * ``b``: blank (``ascii="  "`` override)

This means a fixed bar with right-justified text may be created by using:
``bar_format="{l_bar}{bar:10}|{bar:-10b}right-justified"``

Nested progress bars
~~~~~~~~~~~~~~~~~~~~

``tqdm`` supports nested progress bars. Here's an example:

.. code:: python

    from tqdm.auto import trange
    from time import sleep

    for i in trange(4, desc='1st loop'):
        for j in trange(5, desc='2nd loop'):
            for k in trange(50, desc='3rd loop', leave=False):
                sleep(0.01)

For manual control over positioning (e.g. for multi-processing use),
you may specify ``position=n`` where ``n=0`` for the outermost bar,
``n=1`` for the next, and so on.
However, it's best to check if ``tqdm`` can work without manual ``position``
first.

.. code:: python

    from time import sleep
    from tqdm import trange, tqdm
    from multiprocessing import Pool, RLock, freeze_support

    L = list(range(9))

    def progresser(n):
        interval = 0.001 / (n + 2)
        total = 5000
        text = f"#{n}, est. {interval * total:<04.2}s"
        for _ in trange(total, desc=text, position=n):
            sleep(interval)

    if __name__ == '__main__':
        freeze_support()  # for Windows support
        tqdm.set_lock(RLock())  # for managing output contention
        p = Pool(initializer=tqdm.set_lock, initargs=(tqdm.get_lock(),))
        p.map(progresser, L)

Note that in Python 3, ``tqdm.write`` is thread-safe:

.. code:: python

    from time import sleep
    from tqdm import tqdm, trange
    from concurrent.futures import ThreadPoolExecutor

    L = list(range(9))

    def progresser(n):
        interval = 0.001 / (n + 2)
        total = 5000
        text = f"#{n}, est. {interval * total:<04.2}s"
        for _ in trange(total, desc=text):
            sleep(interval)
        if n == 6:
            tqdm.write("n == 6 completed.")
            tqdm.write("`tqdm.write()` is thread-safe in py3!")

    if __name__ == '__main__':
        with ThreadPoolExecutor() as p:
            p.map(progresser, L)

Hooks and callbacks
~~~~~~~~~~~~~~~~~~~

``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 urllib, os
    from tqdm import tqdm
    urllib = getattr(urllib, 'request', urllib)

    class TqdmUpTo(tqdm):
        """Provides `update_to(n)` which uses `tqdm.update(delta_n)`."""
        def update_to(self, b=1, bsize=1, tsize=None):
            """
            b  : int, optional
                Number of blocks transferred so far [default: 1].
            bsize  : int, optional
                Size of each block (in tqdm units) [default: 1].
            tsize  : int, optional
                Total size (in tqdm units). If [default: None] remains unchanged.
            """
            if tsize is not None:
                self.total = tsize
            return self.update(b * bsize - self.n)  # also sets self.n = b * bsize

    eg_link = "https://caspersci.uk.to/matryoshka.zip"
    with TqdmUpTo(unit='B', unit_scale=True, unit_divisor=1024, miniters=1,
                  desc=eg_link.split('/')[-1]) as t:  # all optional kwargs
        urllib.urlretrieve(eg_link, filename=os.devnull,
                           reporthook=t.update_to, data=None)
        t.total = t.n

Inspired by `twine#242 <https://github.com/pypa/twine/pull/242>`__.
Functional alternative in
`examples/tqdm_wget.py <https://github.com/tqdm/tqdm/blob/master/examples/tqdm_wget.py>`__.

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

**Wrapping read/write methods**

To measure throughput through a file-like object's ``read`` or ``write``
methods, use ``CallbackIOWrapper``:

.. code:: python

    from tqdm.auto import tqdm
    from tqdm.utils import CallbackIOWrapper

    with tqdm(total=file_obj.size,
              unit='B', unit_scale=True, unit_divisor=1024) as t:
        fobj = CallbackIOWrapper(t.update, file_obj, "read")
        while True:
            chunk = fobj.read(chunk_size)
            if not chunk:
                break
        t.reset()
        # ... continue to use `t` for something else

Alternatively, use the even simpler ``wrapattr`` convenience function,
which would condense both the ``urllib`` and ``CallbackIOWrapper`` examples
down to:

.. code:: python

    import urllib, os
    from tqdm import tqdm

    eg_link = "https://caspersci.uk.to/matryoshka.zip"
    response = getattr(urllib, 'request', urllib).urlopen(eg_link)
    with tqdm.wrapattr(open(os.devnull, "wb"), "write",
                       miniters=1, desc=eg_link.split('/')[-1],
                       total=getattr(response, 'length', None)) as fout:
        for chunk in response:
            fout.write(chunk)

The ``requests`` equivalent is nearly identical:

.. code:: python

    import requests, os
    from tqdm import tqdm

    eg_link = "https://caspersci.uk.to/matryoshka.zip"
    response = requests.get(eg_link, stream=True)
    with tqdm.wrapattr(open(os.devnull, "wb"), "write",
                       miniters=1, desc=eg_link.split('/')[-1],
                       total=int(response.headers.get('content-length', 0))) as fout:
        for chunk in response.iter_content(chunk_size=4096):
            fout.write(chunk)

**Custom callback**

``tqdm`` is known for intelligently skipping unnecessary displays. To make a
custom callback take advantage of this, simply use the return value of
``update()``. This is set to ``True`` if a ``display()`` was triggered.

.. code:: python

    from tqdm.auto import tqdm as std_tqdm

    def external_callback(*args, **kwargs):
        ...

    class TqdmExt(std_tqdm):
        def update(self, n=1):
            displayed = super().update(n)
            if displayed:
                external_callback(**self.format_dict)
            return displayed

``asyncio``
~~~~~~~~~~~

Note that ``break`` isn't currently caught by asynchronous iterators.
This means that ``tqdm`` cannot clean up after itself in this case:

.. code:: python

    from tqdm.asyncio import tqdm

    async for i in tqdm(range(9)):
        if i == 2:
            break

Instead, either call ``pbar.close()`` manually or use the context manager syntax:

.. code:: python

    from tqdm.asyncio import tqdm

    with tqdm(range(9)) as pbar:
        async for i in pbar:
            if i == 2:
                break

Pandas Integration
~~~~~~~~~~~~~~~~~~

Due to popular demand we've added support for ``pandas`` -- here's an example
for ``DataFrame.progress_apply`` and ``DataFrameGroupBy.progress_apply``:

.. code:: python

    import pandas as pd
    import numpy as np
    from tqdm import tqdm

    df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))

    # Register `pandas.progress_apply` and `pandas.Series.map_apply` with `tqdm`
    # (can use `tqdm.gui.tqdm`, `tqdm.notebook.tqdm`, optional kwargs, etc.)
    tqdm.pandas(desc="my bar!")

    # Now you can use `progress_apply` instead of `apply`
    # and `progress_map` instead of `map`
    df.progress_apply(lambda x: x**2)
    # can also groupby:
    # df.groupby(0).progress_apply(lambda x: x**2)

In case you're interested in how this works (and how to modify it for your
own callbacks), see the
`examples <https://github.com/tqdm/tqdm/tree/master/examples>`__
folder or import the module and run ``help()``.

Keras Integration
~~~~~~~~~~~~~~~~~

A ``keras`` callback is also available:

.. code:: python

    from tqdm.keras import TqdmCallback

    ...

    model.fit(..., verbose=0, callbacks=[TqdmCallback()])

Dask Integration
~~~~~~~~~~~~~~~~

A ``dask`` callback is also available:

.. code:: python

    from tqdm.dask import TqdmCallback

    with TqdmCallback(desc="compute"):
        ...
        arr.compute()

    # or use callback globally
    cb = TqdmCallback(desc="global")
    cb.register()
    arr.compute()

IPython/Jupyter Integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

IPython/Jupyter is supported via the ``tqdm.notebook`` submodule:

.. code:: python

    from tqdm.notebook import trange, tqdm
    from time import sleep

    for i in trange(3, desc='1st loop'):
        for j in tqdm(range(100), desc='2nd loop'):
            sleep(0.01)

In addition to ``tqdm`` features, the submodule provides a native Jupyter
widget (compatible with IPython v1-v4 and Jupyter), fully working nested bars
and colour hints (blue: normal, green: completed, red: error/interrupt,
light blue: no ETA); as demonstrated below.

|Screenshot-Jupyter1|
|Screenshot-Jupyter2|
|Screenshot-Jupyter3|

The ``notebook`` version supports percentage or pixels for overall width
(e.g.: ``ncols='100%'`` or ``ncols='480px'``).

It is also possible to let ``tqdm`` automatically choose between
console or notebook versions by using the ``autonotebook`` submodule:

.. code:: python

    from tqdm.autonotebook import tqdm
    tqdm.pandas()

Note that this will issue a ``TqdmExperimentalWarning`` if run in a notebook
since it is not meant to be possible to distinguish between ``jupyter notebook``
and ``jupyter console``. Use ``auto`` instead of ``autonotebook`` to suppress
this warning.

Note that notebooks will display the bar in the cell where it was created.
This may be a different cell from the one where it is used.
If this is not desired, either

- delay the creation of the bar to the cell where it must be displayed, or
- create the bar with ``display=False``, and in a later cell call
  ``display(bar.container)``:

.. code:: python

    from tqdm.notebook import tqdm
    pbar = tqdm(..., display=False)

.. code:: python

    # different cell
    display(pbar.container)

The ``keras`` callback has a ``display()`` method which can be used likewise:

.. code:: python

    from tqdm.keras import TqdmCallback
    cbk = TqdmCallback(display=False)

.. code:: python

    # different cell
    cbk.display()
    model.fit(..., verbose=0, callbacks=[cbk])

Another possibility is to have a single bar (near the top of the notebook)
which is constantly re-used (using ``reset()`` rather than ``close()``).
For this reason, the notebook version (unlike the CLI version) does not
automatically call ``close()`` upon ``Exception``.

.. code:: python

    from tqdm.notebook import tqdm
    pbar = tqdm()

.. code:: python

    # different cell
    iterable = range(100)
    pbar.reset(total=len(iterable))  # initialise with new `total`
    for i in iterable:
        pbar.update()
    pbar.refresh()  # force print final status but don't `close()`

Custom Integration
~~~~~~~~~~~~~~~~~~

To change the default arguments (such as making ``dynamic_ncols=True``),
simply use built-in Python magic:

.. code:: python

    from functools import partial
    from tqdm import tqdm as std_tqdm
    tqdm = partial(std_tqdm, dynamic_ncols=True)

For further customisation,
``tqdm`` may be inherited from to create custom callbacks (as with the
``TqdmUpTo`` example `above <#hooks-and-callbacks>`__) or for custom frontends
(e.g. GUIs such as notebook or plotting packages). In the latter case:

1. ``def __init__()`` to call ``super().__init__(..., gui=True)`` to disable
   terminal ``status_printer`` creation.
2. Redefine: ``close()``, ``clear()``, ``display()``.

Consider overloading ``display()`` to use e.g.
``self.frontend(**self.format_dict)`` instead of ``self.sp(repr(self))``.

Some submodule examples of inheritance:

- `tqdm/notebook.py <https://github.com/tqdm/tqdm/blob/master/tqdm/notebook.py>`__
- `tqdm/gui.py <https://github.com/tqdm/tqdm/blob/master/tqdm/gui.py>`__
- `tqdm/tk.py <https://github.com/tqdm/tqdm/blob/master/tqdm/tk.py>`__
- `tqdm/contrib/slack.py <https://github.com/tqdm/tqdm/blob/master/tqdm/contrib/slack.py>`__
- `tqdm/contrib/discord.py <https://github.com/tqdm/tqdm/blob/master/tqdm/contrib/discord.py>`__
- `tqdm/contrib/telegram.py <https://github.com/tqdm/tqdm/blob/master/tqdm/contrib/telegram.py>`__

Dynamic Monitor/Meter
~~~~~~~~~~~~~~~~~~~~~

You can use a ``tqdm`` as a meter which is not monotonically increasing.
This could be because ``n`` decreases (e.g. a CPU usage monitor) or ``total``
changes.

One example would be recursively searching for files. The ``total`` is the
number of objects found so far, while ``n`` is the number of those objects which
are files (rather than folders):

.. code:: python

    from tqdm import tqdm
    import os.path

    def find_files_recursively(path, show_progress=True):
        files = []
        # total=1 assumes `path` is a file
        t = tqdm(total=1, unit="file", disable=not show_progress)
        if not os.path.exists(path):
            raise IOError("Cannot find:" + path)

        def append_found_file(f):
            files.append(f)
            t.update()

        def list_found_dir(path):
            """returns os.listdir(path) assuming os.path.isdir(path)"""
            listing = os.listdir(path)
            # subtract 1 since a "file" we found was actually this directory
            t.total += len(listing) - 1
            # fancy way to give info without forcing a refresh
            t.set_postfix(dir=path[-10:], refresh=False)
            t.update(0)  # may trigger a refresh
            return listing

        def recursively_search(path):
            if os.path.isdir(path):
                for f in list_found_dir(path):
                    recursively_search(os.path.join(path, f))
            else:
                append_found_file(path)

        recursively_search(path)
        t.set_postfix(dir=path)
        t.close()
        return files

Using ``update(0)`` is a handy way to let ``tqdm`` decide when to trigger a
display refresh to avoid console spamming.

Writing messages
~~~~~~~~~~~~~~~~

This is a work in progress (see
`#737 <https://github.com/tqdm/tqdm/issues/737>`__).

Since ``tqdm`` uses a simple printing mechanism to display progress bars,
you should not write any message in the terminal using ``print()`` while
a progressbar is open.

To write messages in the terminal without any collision with ``tqdm`` bar
display, a ``.write()`` method is provided:

.. code:: python

    from tqdm.auto import tqdm, trange
    from time import sleep

    bar = trange(10)
    for i in bar:
        # Print using tqdm class method .write()
        sleep(0.1)
        if not (i % 3):
            tqdm.write("Done task %i" % i)
        # Can also use bar.write()

By default, this will print to standard output ``sys.stdout``. but you can
specify any file-like object using the ``file`` argument. For example, this
can be used to redirect the messages writing to a log file or class.

Redirecting writing
~~~~~~~~~~~~~~~~~~~

If using a library that can print messages to the console, editing the library
by  replacing ``print()`` with ``tqdm.write()`` may not be desirable.
In that case, redirecting ``sys.stdout`` to ``tqdm.write()`` is an option.

To redirect ``sys.stdout``, create a file-like class that will write
any input string to ``tqdm.write()``, and supply the arguments
``file=sys.stdout, dynamic_ncols=True``.

A reusable canonical example is given below:

.. code:: python

    from time import sleep
    import contextlib
    import sys
    from tqdm import tqdm
    from tqdm.contrib import DummyTqdmFile


    @contextlib.contextmanager
    def std_out_err_redirect_tqdm():
        orig_out_err = sys.stdout, sys.stderr
        try:
            sys.stdout, sys.stderr = map(DummyTqdmFile, orig_out_err)
            yield orig_out_err[0]
        # Relay exceptions
        except Exception as exc:
            raise exc
        # Always restore sys.stdout/err if necessary
        finally:
            sys.stdout, sys.stderr = orig_out_err

    def some_fun(i):
        print("Fee, fi, fo,".split()[i])

    # Redirect stdout to tqdm.write() (don't forget the `as save_stdout`)
    with std_out_err_redirect_tqdm() as orig_stdout:
        # tqdm needs the original stdout
        # and dynamic_ncols=True to autodetect console width
        for i in tqdm(range(3), file=orig_stdout, dynamic_ncols=True):
            sleep(.5)
            some_fun(i)

    # After the `with`, printing is restored
    print("Done!")

Redirecting ``logging``
~~~~~~~~~~~~~~~~~~~~~~~

Similar to ``sys.stdout``/``sys.stderr`` as detailed above, console ``logging``
may also be redirected to ``tqdm.write()``.

Warning: if also redirecting ``sys.stdout``/``sys.stderr``, make sure to
redirect ``logging`` first if needed.

Helper methods are available in ``tqdm.contrib.logging``. For example:

.. code:: python

    import logging
    from tqdm import trange
    from tqdm.contrib.logging import logging_redirect_tqdm

    LOG = logging.getLogger(__name__)

    if __name__ == '__main__':
        logging.basicConfig(level=logging.INFO)
        with logging_redirect_tqdm():
            for i in trange(9):
                if i == 4:
                    LOG.info("console logging redirected to `tqdm.write()`")
        # logging restored

Monitoring thread, intervals and miniters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``tqdm`` implements a few tricks to increase efficiency and reduce overhead.

- Avoid unnecessary frequent bar refreshing: ``mininterval`` defines how long
  to wait between each refresh. ``tqdm`` always gets updated in the background,
  but it will display only every ``mininterval``.
- Reduce number of calls to check system clock/time.
- ``mininterval`` is more intuitive to configure than ``miniters``.
  A clever adjustment system ``dynamic_miniters`` will automatically adjust
  ``miniters`` to the amount of iterations that fit into time ``mininterval``.
  Essentially, ``tqdm`` will check if it's time to print without actually
  checking time. This behaviour can be still be bypassed by manually setting
  ``miniters``.

However, consider a case with a combination of fast and slow iterations.
After a few fast iterations, ``dynamic_miniters`` will set ``miniters`` to a
large number. When iteration rate subsequently slows, ``miniters`` will
remain large and thus reduce display update frequency. To address this:

- ``maxinterval`` defines the maximum time between display refreshes.
  A concurrent monitoring thread checks for overdue updates and forces one
  where necessary.

The monitoring thread should not have a noticeable overhead, and guarantees
updates at least every 10 seconds by default.
This value can be directly changed by setting the ``monitor_interval`` of
any ``tqdm`` instance (i.e. ``t = tqdm.tqdm(...); t.monitor_interval = 2``).
The monitor thread may be disabled application-wide by setting
``tqdm.tqdm.monitor_interval = 0`` before instantiation of any ``tqdm`` bar.


Merch
-----

You can buy `tqdm branded merch <https://tqdm.github.io/merch>`__ now!

Contributions
-------------

|GitHub-Commits| |GitHub-Issues| |GitHub-PRs| |OpenHub-Status| |GitHub-Contributions| |CII Best Practices|

All source code is hosted on `GitHub <https://github.com/tqdm/tqdm>`__.
Contributions are welcome.

See the
`CONTRIBUTING <https://github.com/tqdm/tqdm/blob/master/CONTRIBUTING.md>`__
file for more information.

Developers who have made significant contributions, ranked by *SLoC*
(surviving lines of code,
`git fame <https://github.com/casperdcl/git-fame>`__ ``-wMC --excl '\.(png|gif|jpg)$'``),
are:

==================== ======================================================== ==== ================================
Name                 ID                                                       SLoC Notes
==================== ======================================================== ==== ================================
Casper da Costa-Luis `casperdcl <https://github.com/casperdcl>`__             ~80% primary maintainer |Gift-Casper|
Stephen Larroque     `lrq3000 <https://github.com/lrq3000>`__                 ~9%  team member
Martin Zugnoni       `martinzugnoni <https://github.com/martinzugnoni>`__     ~3%
Daniel Ecer          `de-code <https://github.com/de-code>`__                 ~2%
Richard Sheridan     `richardsheridan <https://github.com/richardsheridan>`__ ~1%
Guangshuo Chen       `chengs <https://github.com/chengs>`__                   ~1%
Helio Machado        `0x2b3bfa0 <https://github.com/0x2b3bfa0>`__             ~1%
Kyle Altendorf       `altendky <https://github.com/altendky>`__               <1%
Noam Yorav-Raphael   `noamraph <https://github.com/noamraph>`__               <1%  original author
Matthew Stevens      `mjstevens777 <https://github.com/mjstevens777>`__       <1%
Hadrien Mary         `hadim <https://github.com/hadim>`__                     <1%  team member
Mikhail Korobov      `kmike <https://github.com/kmike>`__                     <1%  team member
==================== ======================================================== ==== ================================

Ports to Other Languages
~~~~~~~~~~~~~~~~~~~~~~~~

A list is available on
`this wiki page <https://github.com/tqdm/tqdm/wiki/tqdm-ports>`__.


LICENCE
-------

Open Source (OSI approved): |LICENCE|

Citation information: |DOI|

|README-Hits| (Since 19 May 2016)

.. |Logo| image:: https://tqdm.github.io/img/logo.gif
.. |Screenshot| image:: https://tqdm.github.io/img/tqdm.gif
.. |Video| image:: https://tqdm.github.io/img/video.jpg
   :target: https://tqdm.github.io/video
.. |Slides| image:: https://tqdm.github.io/img/slides.jpg
   :target: https://tqdm.github.io/PyData2019/slides.html
.. |Merch| image:: https://tqdm.github.io/img/merch.jpg
   :target: https://tqdm.github.io/merch
.. |Build-Status| image:: https://img.shields.io/github/actions/workflow/status/tqdm/tqdm/test.yml?branch=master&label=tqdm&logo=GitHub
   :target: https://github.com/tqdm/tqdm/actions/workflows/test.yml
.. |Coverage-Status| image:: https://img.shields.io/coveralls/github/tqdm/tqdm/master?logo=coveralls
   :target: https://coveralls.io/github/tqdm/tqdm
.. |Branch-Coverage-Status| image:: https://codecov.io/gh/tqdm/tqdm/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/tqdm/tqdm
.. |Codacy-Grade| image:: https://app.codacy.com/project/badge/Grade/3f965571598f44549c7818f29cdcf177
   :target: https://www.codacy.com/gh/tqdm/tqdm/dashboard
.. |CII Best Practices| image:: https://bestpractices.coreinfrastructure.org/projects/3264/badge
   :target: https://bestpractices.coreinfrastructure.org/projects/3264
.. |GitHub-Status| image:: https://img.shields.io/github/tag/tqdm/tqdm.svg?maxAge=86400&logo=github&logoColor=white
   :target: https://github.com/tqdm/tqdm/releases
.. |GitHub-Forks| image:: https://img.shields.io/github/forks/tqdm/tqdm.svg?logo=github&logoColor=white
   :target: https://github.com/tqdm/tqdm/network
.. |GitHub-Stars| image:: https://img.shields.io/github/stars/tqdm/tqdm.svg?logo=github&logoColor=white
   :target: https://github.com/tqdm/tqdm/stargazers
.. |GitHub-Commits| image:: https://img.shields.io/github/commit-activity/y/tqdm/tqdm.svg?logo=git&logoColor=white
   :target: https://github.com/tqdm/tqdm/graphs/commit-activity
.. |GitHub-Issues| image:: https://img.shields.io/github/issues-closed/tqdm/tqdm.svg?logo=github&logoColor=white
   :target: https://github.com/tqdm/tqdm/issues?q=
.. |GitHub-PRs| image:: https://img.shields.io/github/issues-pr-closed/tqdm/tqdm.svg?logo=github&logoColor=white
   :target: https://github.com/tqdm/tqdm/pulls
.. |GitHub-Contributions| image:: https://img.shields.io/github/contributors/tqdm/tqdm.svg?logo=github&logoColor=white
   :target: https://github.com/tqdm/tqdm/graphs/contributors
.. |GitHub-Updated| image:: https://img.shields.io/github/last-commit/tqdm/tqdm/master.svg?logo=github&logoColor=white&label=pushed
   :target: https://github.com/tqdm/tqdm/pulse
.. |Gift-Casper| image:: https://img.shields.io/badge/dynamic/json.svg?color=ff69b4&label=gifts%20received&prefix=%C2%A3&query=%24..sum&url=https%3A%2F%2Fcaspersci.uk.to%2Fgifts.json
   :target: https://cdcl.ml/sponsor
.. |Versions| image:: https://img.shields.io/pypi/v/tqdm.svg
   :target: https://tqdm.github.io/releases
.. |PyPI-Downloads| image:: https://img.shields.io/pypi/dm/tqdm.svg?label=pypi%20downloads&logo=PyPI&logoColor=white
   :target: https://pepy.tech/project/tqdm
.. |Py-Versions| image:: https://img.shields.io/pypi/pyversions/tqdm.svg?logo=python&logoColor=white
   :target: https://pypi.org/project/tqdm
.. |Conda-Forge-Status| image:: https://img.shields.io/conda/v/conda-forge/tqdm.svg?label=conda-forge&logo=conda-forge
   :target: https://anaconda.org/conda-forge/tqdm
.. |Snapcraft| image:: https://img.shields.io/badge/snap-install-82BEA0.svg?logo=snapcraft
   :target: https://snapcraft.io/tqdm
.. |Docker| image:: https://img.shields.io/badge/docker-pull-blue.svg?logo=docker&logoColor=white
   :target: https://hub.docker.com/r/tqdm/tqdm
.. |Libraries-Rank| image:: https://img.shields.io/librariesio/sourcerank/pypi/tqdm.svg?logo=koding&logoColor=white
   :target: https://libraries.io/pypi/tqdm
.. |Libraries-Dependents| image:: https://img.shields.io/librariesio/dependent-repos/pypi/tqdm.svg?logo=koding&logoColor=white
    :target: https://github.com/tqdm/tqdm/network/dependents
.. |OpenHub-Status| image:: https://www.openhub.net/p/tqdm/widgets/project_thin_badge?format=gif
   :target: https://www.openhub.net/p/tqdm?ref=Thin+badge
.. |awesome-python| image:: https://awesome.re/mentioned-badge.svg
   :target: https://github.com/vinta/awesome-python
.. |LICENCE| image:: https://img.shields.io/pypi/l/tqdm.svg
   :target: https://raw.githubusercontent.com/tqdm/tqdm/master/LICENCE
.. |DOI| image:: https://img.shields.io/badge/DOI-10.5281/zenodo.595120-blue.svg
   :target: https://doi.org/10.5281/zenodo.595120
.. |binder-demo| image:: https://mybinder.org/badge_logo.svg
   :target: https://mybinder.org/v2/gh/tqdm/tqdm/master?filepath=DEMO.ipynb
.. |Screenshot-Jupyter1| image:: https://tqdm.github.io/img/jupyter-1.gif
.. |Screenshot-Jupyter2| image:: https://tqdm.github.io/img/jupyter-2.gif
.. |Screenshot-Jupyter3| image:: https://tqdm.github.io/img/jupyter-3.gif
.. |README-Hits| image:: https://cgi.cdcl.ml/hits?q=tqdm&style=social&r=https://github.com/tqdm/tqdm&l=https://tqdm.github.io/img/favicon.png&f=https://tqdm.github.io/img/logo.gif
   :target: https://cgi.cdcl.ml/hits?q=tqdm&a=plot&r=https://github.com/tqdm/tqdm&l=https://tqdm.github.io/img/favicon.png&f=https://tqdm.github.io/img/logo.gif&style=social

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "tqdm",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "tqdm developers <devs@tqdm.ml>",
    "keywords": "progressbar, progressmeter, progress, bar, meter, rate, eta, console, terminal, time",
    "author": null,
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/e8/4f/0153c21dc5779a49a0598c445b1978126b1344bab9ee71e53e44877e14e0/tqdm-4.67.0.tar.gz",
    "platform": null,
    "description": "|Logo|\n\ntqdm\n====\n\n|Py-Versions| |Versions| |Conda-Forge-Status| |Docker| |Snapcraft|\n\n|Build-Status| |Coverage-Status| |Branch-Coverage-Status| |Codacy-Grade| |Libraries-Rank| |PyPI-Downloads|\n\n|LICENCE| |OpenHub-Status| |binder-demo| |awesome-python|\n\n``tqdm`` derives from the Arabic word *taqaddum* (\u062a\u0642\u062f\u0651\u0645) which can mean \"progress,\"\nand is an abbreviation for \"I love you so much\" in Spanish (*te quiero demasiado*).\n\nInstantly make your loops show a smart progress meter - just wrap any\niterable with ``tqdm(iterable)``, and you're done!\n\n.. code:: python\n\n    from tqdm import tqdm\n    for i in tqdm(range(10000)):\n        ...\n\n``76%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 | 7568/10000 [00:33<00:10, 229.00it/s]``\n\n``trange(N)`` can be also used as a convenient shortcut for\n``tqdm(range(N))``.\n\n|Screenshot|\n    |Video| |Slides| |Merch|\n\nIt can also be executed as a module with pipes:\n\n.. code:: sh\n\n    $ seq 9999999 | tqdm --bytes | wc -l\n    75.2MB [00:00, 217MB/s]\n    9999999\n\n    $ tar -zcf - docs/ | tqdm --bytes --total `du -sb docs/ | cut -f1` \\\n        > backup.tgz\n     32%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u258d                      | 8.89G/27.9G [00:42<01:31, 223MB/s]\n\nOverhead is low -- about 60ns per iteration (80ns with ``tqdm.gui``), and is\nunit tested against performance regression.\nBy comparison, the well-established\n`ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has\nan 800ns/iter overhead.\n\nIn addition to its low overhead, ``tqdm`` uses smart algorithms to predict\nthe remaining time and to skip unnecessary iteration displays, which allows\nfor a negligible overhead in most cases.\n\n``tqdm`` works on any platform\n(Linux, Windows, Mac, FreeBSD, NetBSD, Solaris/SunOS),\nin any console or in a GUI, and is also friendly with IPython/Jupyter notebooks.\n\n``tqdm`` does not require any dependencies (not even ``curses``!), just\nPython and an environment supporting ``carriage return \\r`` and\n``line feed \\n`` control characters.\n\n------------------------------------------\n\n.. contents:: Table of contents\n   :backlinks: top\n   :local:\n\n\nInstallation\n------------\n\nLatest PyPI stable release\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n|Versions| |PyPI-Downloads| |Libraries-Dependents|\n\n.. code:: sh\n\n    pip install tqdm\n\nLatest development release on GitHub\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n|GitHub-Status| |GitHub-Stars| |GitHub-Commits| |GitHub-Forks| |GitHub-Updated|\n\nPull and install pre-release ``devel`` branch:\n\n.. code:: sh\n\n    pip install \"git+https://github.com/tqdm/tqdm.git@devel#egg=tqdm\"\n\nLatest Conda release\n~~~~~~~~~~~~~~~~~~~~\n\n|Conda-Forge-Status|\n\n.. code:: sh\n\n    conda install -c conda-forge tqdm\n\nLatest Snapcraft release\n~~~~~~~~~~~~~~~~~~~~~~~~\n\n|Snapcraft|\n\nThere are 3 channels to choose from:\n\n.. code:: sh\n\n    snap install tqdm  # implies --stable, i.e. latest tagged release\n    snap install tqdm  --candidate  # master branch\n    snap install tqdm  --edge  # devel branch\n\nNote that ``snap`` binaries are purely for CLI use (not ``import``-able), and\nautomatically set up ``bash`` tab-completion.\n\nLatest Docker release\n~~~~~~~~~~~~~~~~~~~~~\n\n|Docker|\n\n.. code:: sh\n\n    docker pull tqdm/tqdm\n    docker run -i --rm tqdm/tqdm --help\n\nOther\n~~~~~\n\nThere are other (unofficial) places where ``tqdm`` may be downloaded, particularly for CLI use:\n\n|Repology|\n\n.. |Repology| image:: https://repology.org/badge/tiny-repos/python:tqdm.svg\n   :target: https://repology.org/project/python:tqdm/versions\n\nChangelog\n---------\n\nThe list of all changes is available either on GitHub's Releases:\n|GitHub-Status|, on the\n`wiki <https://github.com/tqdm/tqdm/wiki/Releases>`__, or on the\n`website <https://tqdm.github.io/releases>`__.\n\n\nUsage\n-----\n\n``tqdm`` is very versatile and can be used in a number of ways.\nThe three main ones are given below.\n\nIterable-based\n~~~~~~~~~~~~~~\n\nWrap ``tqdm()`` around any iterable:\n\n.. code:: python\n\n    from tqdm import tqdm\n    from time import sleep\n\n    text = \"\"\n    for char in tqdm([\"a\", \"b\", \"c\", \"d\"]):\n        sleep(0.25)\n        text = text + char\n\n``trange(i)`` is a special optimised instance of ``tqdm(range(i))``:\n\n.. code:: python\n\n    from tqdm import trange\n\n    for i in trange(100):\n        sleep(0.01)\n\nInstantiation outside of the loop allows for manual control over ``tqdm()``:\n\n.. code:: python\n\n    pbar = tqdm([\"a\", \"b\", \"c\", \"d\"])\n    for char in pbar:\n        sleep(0.25)\n        pbar.set_description(\"Processing %s\" % char)\n\nManual\n~~~~~~\n\nManual control of ``tqdm()`` updates using a ``with`` statement:\n\n.. code:: python\n\n    with tqdm(total=100) as pbar:\n        for i in range(10):\n            sleep(0.1)\n            pbar.update(10)\n\nIf the optional variable ``total`` (or an iterable with ``len()``) is\nprovided, predictive stats are displayed.\n\n``with`` is also optional (you can just assign ``tqdm()`` to a variable,\nbut in this case don't forget to ``del`` or ``close()`` at the end:\n\n.. code:: python\n\n    pbar = tqdm(total=100)\n    for i in range(10):\n        sleep(0.1)\n        pbar.update(10)\n    pbar.close()\n\nModule\n~~~~~~\n\nPerhaps the most wonderful use of ``tqdm`` is in a script or on the command\nline. Simply inserting ``tqdm`` (or ``python -m tqdm``) between pipes will pass\nthrough all ``stdin`` to ``stdout`` while printing progress to ``stderr``.\n\nThe example below demonstrate counting the number of lines in all Python files\nin the current directory, with timing information included.\n\n.. code:: sh\n\n    $ time find . -name '*.py' -type f -exec cat \\{} \\; | wc -l\n    857365\n\n    real    0m3.458s\n    user    0m0.274s\n    sys     0m3.325s\n\n    $ time find . -name '*.py' -type f -exec cat \\{} \\; | tqdm | wc -l\n    857366it [00:03, 246471.31it/s]\n    857365\n\n    real    0m3.585s\n    user    0m0.862s\n    sys     0m3.358s\n\nNote that the usual arguments for ``tqdm`` can also be specified.\n\n.. code:: sh\n\n    $ find . -name '*.py' -type f -exec cat \\{} \\; |\n        tqdm --unit loc --unit_scale --total 857366 >> /dev/null\n    100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 857K/857K [00:04<00:00, 246Kloc/s]\n\nBacking up a large directory?\n\n.. code:: sh\n\n    $ tar -zcf - docs/ | tqdm --bytes --total `du -sb docs/ | cut -f1` \\\n      > backup.tgz\n     44%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u258a                   | 153M/352M [00:14<00:18, 11.0MB/s]\n\nThis can be beautified further:\n\n.. code:: sh\n\n    $ BYTES=$(du -sb docs/ | cut -f1)\n    $ tar -cf - docs/ \\\n      | tqdm --bytes --total \"$BYTES\" --desc Processing | gzip \\\n      | tqdm --bytes --total \"$BYTES\" --desc Compressed --position 1 \\\n      > ~/backup.tgz\n    Processing: 100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 352M/352M [00:14<00:00, 30.2MB/s]\n    Compressed:  42%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u258e            | 148M/352M [00:14<00:19, 10.9MB/s]\n\nOr done on a file level using 7-zip:\n\n.. code:: sh\n\n    $ 7z a -bd -r backup.7z docs/ | grep Compressing \\\n      | tqdm --total $(find docs/ -type f | wc -l) --unit files \\\n      | grep -v Compressing\n    100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2589| 15327/15327 [01:00<00:00, 712.96files/s]\n\nPre-existing CLI programs already outputting basic progress information will\nbenefit from ``tqdm``'s ``--update`` and ``--update_to`` flags:\n\n.. code:: sh\n\n    $ seq 3 0.1 5 | tqdm --total 5 --update_to --null\n    100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 5.0/5 [00:00<00:00, 9673.21it/s]\n    $ seq 10 | tqdm --update --null  # 1 + 2 + ... + 10 = 55 iterations\n    55it [00:00, 90006.52it/s]\n\nFAQ and Known Issues\n--------------------\n\n|GitHub-Issues|\n\nThe most common issues relate to excessive output on multiple lines, instead\nof a neat one-line progress bar.\n\n- Consoles in general: require support for carriage return (``CR``, ``\\r``).\n\n  * Some cloud logging consoles which don't support ``\\r`` properly\n    (`cloudwatch <https://github.com/tqdm/tqdm/issues/966>`__,\n    `K8s <https://github.com/tqdm/tqdm/issues/1319>`__) may benefit from\n    ``export TQDM_POSITION=-1``.\n\n- Nested progress bars:\n\n  * Consoles in general: require support for moving cursors up to the\n    previous line. For example,\n    `IDLE <https://github.com/tqdm/tqdm/issues/191#issuecomment-230168030>`__,\n    `ConEmu <https://github.com/tqdm/tqdm/issues/254>`__ and\n    `PyCharm <https://github.com/tqdm/tqdm/issues/203>`__ (also\n    `here <https://github.com/tqdm/tqdm/issues/208>`__,\n    `here <https://github.com/tqdm/tqdm/issues/307>`__, and\n    `here <https://github.com/tqdm/tqdm/issues/454#issuecomment-335416815>`__)\n    lack full support.\n  * Windows: additionally may require the Python module ``colorama``\n    to ensure nested bars stay within their respective lines.\n\n- Unicode:\n\n  * Environments which report that they support unicode will have solid smooth\n    progressbars. The fallback is an ``ascii``-only bar.\n  * Windows consoles often only partially support unicode and thus\n    `often require explicit ascii=True <https://github.com/tqdm/tqdm/issues/454#issuecomment-335416815>`__\n    (also `here <https://github.com/tqdm/tqdm/issues/499>`__). This is due to\n    either normal-width unicode characters being incorrectly displayed as\n    \"wide\", or some unicode characters not rendering.\n\n- Wrapping generators:\n\n  * Generator wrapper functions tend to hide the length of iterables.\n    ``tqdm`` does not.\n  * Replace ``tqdm(enumerate(...))`` with ``enumerate(tqdm(...))`` or\n    ``tqdm(enumerate(x), total=len(x), ...)``.\n    The same applies to ``numpy.ndenumerate``.\n  * Replace ``tqdm(zip(a, b))`` with ``zip(tqdm(a), b)`` or even\n    ``zip(tqdm(a), tqdm(b))``.\n  * The same applies to ``itertools``.\n  * Some useful convenience functions can be found under ``tqdm.contrib``.\n\n- `No intermediate output in docker-compose <https://github.com/tqdm/tqdm/issues/771>`__:\n  use ``docker-compose run`` instead of ``docker-compose up`` and ``tty: true``.\n\n- Overriding defaults via environment variables:\n  e.g. in CI/cloud jobs, ``export TQDM_MININTERVAL=5`` to avoid log spam.\n  This override logic is handled by the ``tqdm.utils.envwrap`` decorator\n  (useful independent of ``tqdm``).\n\nIf you come across any other difficulties, browse and file |GitHub-Issues|.\n\nDocumentation\n-------------\n\n|Py-Versions| |README-Hits| (Since 19 May 2016)\n\n.. code:: python\n\n    class tqdm():\n      \"\"\"\n      Decorate an iterable object, returning an iterator which acts exactly\n      like the original iterable, but prints a dynamically updating\n      progressbar every time a value is requested.\n      \"\"\"\n\n      @envwrap(\"TQDM_\")  # override defaults via env vars\n      def __init__(self, iterable=None, desc=None, total=None, leave=True,\n                   file=None, ncols=None, mininterval=0.1,\n                   maxinterval=10.0, miniters=None, ascii=None, disable=False,\n                   unit='it', unit_scale=False, dynamic_ncols=False,\n                   smoothing=0.3, bar_format=None, initial=0, position=None,\n                   postfix=None, unit_divisor=1000, write_bytes=False,\n                   lock_args=None, nrows=None, colour=None, delay=0):\n\nParameters\n~~~~~~~~~~\n\n* iterable  : iterable, optional  \n    Iterable to decorate with a progressbar.\n    Leave blank to manually manage the updates.\n* desc  : str, optional  \n    Prefix for the progressbar.\n* total  : int or float, optional  \n    The number of expected iterations. If unspecified,\n    len(iterable) is used if possible. If float(\"inf\") or as a last\n    resort, only basic progress statistics are displayed\n    (no ETA, no progressbar).\n    If ``gui`` is True and this parameter needs subsequent updating,\n    specify an initial arbitrary large positive number,\n    e.g. 9e9.\n* leave  : bool, optional  \n    If [default: True], keeps all traces of the progressbar\n    upon termination of iteration.\n    If ``None``, will leave only if ``position`` is ``0``.\n* file  : ``io.TextIOWrapper`` or ``io.StringIO``, optional  \n    Specifies where to output the progress messages\n    (default: sys.stderr). Uses ``file.write(str)`` and ``file.flush()``\n    methods.  For encoding, see ``write_bytes``.\n* ncols  : int, optional  \n    The width of the entire output message. If specified,\n    dynamically resizes the progressbar to stay within this bound.\n    If unspecified, attempts to use environment width. The\n    fallback is a meter width of 10 and no limit for the counter and\n    statistics. If 0, will not print any meter (only stats).\n* mininterval  : float, optional  \n    Minimum progress display update interval [default: 0.1] seconds.\n* maxinterval  : float, optional  \n    Maximum progress display update interval [default: 10] seconds.\n    Automatically adjusts ``miniters`` to correspond to ``mininterval``\n    after long display update lag. Only works if ``dynamic_miniters``\n    or monitor thread is enabled.\n* miniters  : int or float, optional  \n    Minimum progress display update interval, in iterations.\n    If 0 and ``dynamic_miniters``, will automatically adjust to equal\n    ``mininterval`` (more CPU efficient, good for tight loops).\n    If > 0, will skip display of specified number of iterations.\n    Tweak this and ``mininterval`` to get very efficient loops.\n    If your progress is erratic with both fast and slow iterations\n    (network, skipping items, etc) you should set miniters=1.\n* ascii  : bool or str, optional  \n    If unspecified or False, use unicode (smooth blocks) to fill\n    the meter. The fallback is to use ASCII characters \" 123456789#\".\n* disable  : bool, optional  \n    Whether to disable the entire progressbar wrapper\n    [default: False]. If set to None, disable on non-TTY.\n* unit  : str, optional  \n    String that will be used to define the unit of each iteration\n    [default: it].\n* unit_scale  : bool or int or float, optional  \n    If 1 or True, the number of iterations will be reduced/scaled\n    automatically and a metric prefix following the\n    International System of Units standard will be added\n    (kilo, mega, etc.) [default: False]. If any other non-zero\n    number, will scale ``total`` and ``n``.\n* dynamic_ncols  : bool, optional  \n    If set, constantly alters ``ncols`` and ``nrows`` to the\n    environment (allowing for window resizes) [default: False].\n* smoothing  : float, optional  \n    Exponential moving average smoothing factor for speed estimates\n    (ignored in GUI mode). Ranges from 0 (average speed) to 1\n    (current/instantaneous speed) [default: 0.3].\n* bar_format  : str, optional  \n    Specify a custom bar string formatting. May impact performance.\n    [default: '{l_bar}{bar}{r_bar}'], where\n    l_bar='{desc}: {percentage:3.0f}%|' and\n    r_bar='| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, '\n    '{rate_fmt}{postfix}]'\n    Possible vars: l_bar, bar, r_bar, n, n_fmt, total, total_fmt,\n    percentage, elapsed, elapsed_s, ncols, nrows, desc, unit,\n    rate, rate_fmt, rate_noinv, rate_noinv_fmt,\n    rate_inv, rate_inv_fmt, postfix, unit_divisor,\n    remaining, remaining_s, eta.\n    Note that a trailing \": \" is automatically removed after {desc}\n    if the latter is empty.\n* initial  : int or float, optional  \n    The initial counter value. Useful when restarting a progress\n    bar [default: 0]. If using float, consider specifying ``{n:.3f}``\n    or similar in ``bar_format``, or specifying ``unit_scale``.\n* position  : int, optional  \n    Specify the line offset to print this bar (starting from 0)\n    Automatic if unspecified.\n    Useful to manage multiple bars at once (eg, from threads).\n* postfix  : dict or ``*``, optional  \n    Specify additional stats to display at the end of the bar.\n    Calls ``set_postfix(**postfix)`` if possible (dict).\n* unit_divisor  : float, optional  \n    [default: 1000], ignored unless ``unit_scale`` is True.\n* write_bytes  : bool, optional  \n    Whether to write bytes. If (default: False) will write unicode.\n* lock_args  : tuple, optional  \n    Passed to ``refresh`` for intermediate output\n    (initialisation, iterating, and updating).\n* nrows  : int, optional  \n    The screen height. If specified, hides nested bars outside this\n    bound. If unspecified, attempts to use environment height.\n    The fallback is 20.\n* colour  : str, optional  \n    Bar colour (e.g. 'green', '#00ff00').\n* delay  : float, optional  \n    Don't display until [default: 0] seconds have elapsed.\n\nExtra CLI Options\n~~~~~~~~~~~~~~~~~\n\n* delim  : chr, optional  \n    Delimiting character [default: '\\n']. Use '\\0' for null.\n    N.B.: on Windows systems, Python converts '\\n' to '\\r\\n'.\n* buf_size  : int, optional  \n    String buffer size in bytes [default: 256]\n    used when ``delim`` is specified.\n* bytes  : bool, optional  \n    If true, will count bytes, ignore ``delim``, and default\n    ``unit_scale`` to True, ``unit_divisor`` to 1024, and ``unit`` to 'B'.\n* tee  : bool, optional  \n    If true, passes ``stdin`` to both ``stderr`` and ``stdout``.\n* update  : bool, optional  \n    If true, will treat input as newly elapsed iterations,\n    i.e. numbers to pass to ``update()``. Note that this is slow\n    (~2e5 it/s) since every input must be decoded as a number.\n* update_to  : bool, optional  \n    If true, will treat input as total elapsed iterations,\n    i.e. numbers to assign to ``self.n``. Note that this is slow\n    (~2e5 it/s) since every input must be decoded as a number.\n* null  : bool, optional  \n    If true, will discard input (no stdout).\n* manpath  : str, optional  \n    Directory in which to install tqdm man pages.\n* comppath  : str, optional  \n    Directory in which to place tqdm completion.\n* log  : str, optional  \n    CRITICAL|FATAL|ERROR|WARN(ING)|[default: 'INFO']|DEBUG|NOTSET.\n\nReturns\n~~~~~~~\n\n* out  : decorated iterator.  \n\n.. code:: python\n\n    class tqdm():\n      def update(self, n=1):\n          \"\"\"\n          Manually update the progress bar, useful for streams\n          such as reading files.\n          E.g.:\n          >>> t = tqdm(total=filesize) # Initialise\n          >>> for current_buffer in stream:\n          ...    ...\n          ...    t.update(len(current_buffer))\n          >>> t.close()\n          The last line is highly recommended, but possibly not necessary if\n          ``t.update()`` will be called in such a way that ``filesize`` will be\n          exactly reached and printed.\n\n          Parameters\n          ----------\n          n  : int or float, optional\n              Increment to add to the internal counter of iterations\n              [default: 1]. If using float, consider specifying ``{n:.3f}``\n              or similar in ``bar_format``, or specifying ``unit_scale``.\n\n          Returns\n          -------\n          out  : bool or None\n              True if a ``display()`` was triggered.\n          \"\"\"\n\n      def close(self):\n          \"\"\"Cleanup and (if leave=False) close the progressbar.\"\"\"\n\n      def clear(self, nomove=False):\n          \"\"\"Clear current bar display.\"\"\"\n\n      def refresh(self):\n          \"\"\"\n          Force refresh the display of this bar.\n\n          Parameters\n          ----------\n          nolock  : bool, optional\n              If ``True``, does not lock.\n              If [default: ``False``]: calls ``acquire()`` on internal lock.\n          lock_args  : tuple, optional\n              Passed to internal lock's ``acquire()``.\n              If specified, will only ``display()`` if ``acquire()`` returns ``True``.\n          \"\"\"\n\n      def unpause(self):\n          \"\"\"Restart tqdm timer from last print time.\"\"\"\n\n      def reset(self, total=None):\n          \"\"\"\n          Resets to 0 iterations for repeated use.\n\n          Consider combining with ``leave=True``.\n\n          Parameters\n          ----------\n          total  : int or float, optional. Total to use for the new bar.\n          \"\"\"\n\n      def set_description(self, desc=None, refresh=True):\n          \"\"\"\n          Set/modify description of the progress bar.\n\n          Parameters\n          ----------\n          desc  : str, optional\n          refresh  : bool, optional\n              Forces refresh [default: True].\n          \"\"\"\n\n      def set_postfix(self, ordered_dict=None, refresh=True, **tqdm_kwargs):\n          \"\"\"\n          Set/modify postfix (additional stats)\n          with automatic formatting based on datatype.\n\n          Parameters\n          ----------\n          ordered_dict  : dict or OrderedDict, optional\n          refresh  : bool, optional\n              Forces refresh [default: True].\n          kwargs  : dict, optional\n          \"\"\"\n\n      @classmethod\n      def write(cls, s, file=sys.stdout, end=\"\\n\"):\n          \"\"\"Print a message via tqdm (without overlap with bars).\"\"\"\n\n      @property\n      def format_dict(self):\n          \"\"\"Public API for read-only member access.\"\"\"\n\n      def display(self, msg=None, pos=None):\n          \"\"\"\n          Use ``self.sp`` to display ``msg`` in the specified ``pos``.\n\n          Consider overloading this function when inheriting to use e.g.:\n          ``self.some_frontend(**self.format_dict)`` instead of ``self.sp``.\n\n          Parameters\n          ----------\n          msg  : str, optional. What to display (default: ``repr(self)``).\n          pos  : int, optional. Position to ``moveto``\n            (default: ``abs(self.pos)``).\n          \"\"\"\n\n      @classmethod\n      @contextmanager\n      def wrapattr(cls, stream, method, total=None, bytes=True, **tqdm_kwargs):\n          \"\"\"\n          stream  : file-like object.\n          method  : str, \"read\" or \"write\". The result of ``read()`` and\n              the first argument of ``write()`` should have a ``len()``.\n\n          >>> with tqdm.wrapattr(file_obj, \"read\", total=file_obj.size) as fobj:\n          ...     while True:\n          ...         chunk = fobj.read(chunk_size)\n          ...         if not chunk:\n          ...             break\n          \"\"\"\n\n      @classmethod\n      def pandas(cls, *targs, **tqdm_kwargs):\n          \"\"\"Registers the current `tqdm` class with `pandas`.\"\"\"\n\n    def trange(*args, **tqdm_kwargs):\n        \"\"\"Shortcut for `tqdm(range(*args), **tqdm_kwargs)`.\"\"\"\n\nConvenience Functions\n~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n    def tqdm.contrib.tenumerate(iterable, start=0, total=None,\n                                tqdm_class=tqdm.auto.tqdm, **tqdm_kwargs):\n        \"\"\"Equivalent of `numpy.ndenumerate` or builtin `enumerate`.\"\"\"\n\n    def tqdm.contrib.tzip(iter1, *iter2plus, **tqdm_kwargs):\n        \"\"\"Equivalent of builtin `zip`.\"\"\"\n\n    def tqdm.contrib.tmap(function, *sequences, **tqdm_kwargs):\n        \"\"\"Equivalent of builtin `map`.\"\"\"\n\nSubmodules\n~~~~~~~~~~\n\n.. code:: python\n\n    class tqdm.notebook.tqdm(tqdm.tqdm):\n        \"\"\"IPython/Jupyter Notebook widget.\"\"\"\n\n    class tqdm.auto.tqdm(tqdm.tqdm):\n        \"\"\"Automatically chooses beween `tqdm.notebook` and `tqdm.tqdm`.\"\"\"\n\n    class tqdm.asyncio.tqdm(tqdm.tqdm):\n      \"\"\"Asynchronous version.\"\"\"\n      @classmethod\n      def as_completed(cls, fs, *, loop=None, timeout=None, total=None,\n                       **tqdm_kwargs):\n          \"\"\"Wrapper for `asyncio.as_completed`.\"\"\"\n\n    class tqdm.gui.tqdm(tqdm.tqdm):\n        \"\"\"Matplotlib GUI version.\"\"\"\n\n    class tqdm.tk.tqdm(tqdm.tqdm):\n        \"\"\"Tkinter GUI version.\"\"\"\n\n    class tqdm.rich.tqdm(tqdm.tqdm):\n        \"\"\"`rich.progress` version.\"\"\"\n\n    class tqdm.keras.TqdmCallback(keras.callbacks.Callback):\n        \"\"\"Keras callback for epoch and batch progress.\"\"\"\n\n    class tqdm.dask.TqdmCallback(dask.callbacks.Callback):\n        \"\"\"Dask callback for task progress.\"\"\"\n\n\n``contrib``\n+++++++++++\n\nThe ``tqdm.contrib`` package also contains experimental modules:\n\n- ``tqdm.contrib.itertools``: Thin wrappers around ``itertools``\n- ``tqdm.contrib.concurrent``: Thin wrappers around ``concurrent.futures``\n- ``tqdm.contrib.slack``: Posts to `Slack <https://slack.com>`__ bots\n- ``tqdm.contrib.discord``: Posts to `Discord <https://discord.com>`__ bots\n- ``tqdm.contrib.telegram``: Posts to `Telegram <https://telegram.org>`__ bots\n- ``tqdm.contrib.bells``: Automagically enables all optional features\n\n  * ``auto``, ``pandas``, ``slack``, ``discord``, ``telegram``\n\nExamples and Advanced Usage\n---------------------------\n\n- See the `examples <https://github.com/tqdm/tqdm/tree/master/examples>`__\n  folder;\n- import the module and run ``help()``;\n- consult the `wiki <https://github.com/tqdm/tqdm/wiki>`__;\n\n  * this has an\n    `excellent article <https://github.com/tqdm/tqdm/wiki/How-to-make-a-great-Progress-Bar>`__\n    on how to make a **great** progressbar;\n\n- check out the `slides from PyData London <https://tqdm.github.io/PyData2019/slides.html>`__, or\n- run the |binder-demo|.\n\nDescription and additional stats\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nCustom information can be displayed and updated dynamically on ``tqdm`` bars\nwith the ``desc`` and ``postfix`` arguments:\n\n.. code:: python\n\n    from tqdm import tqdm, trange\n    from random import random, randint\n    from time import sleep\n\n    with trange(10) as t:\n        for i in t:\n            # Description will be displayed on the left\n            t.set_description('GEN %i' % i)\n            # Postfix will be displayed on the right,\n            # formatted automatically based on argument's datatype\n            t.set_postfix(loss=random(), gen=randint(1,999), str='h',\n                          lst=[1, 2])\n            sleep(0.1)\n\n    with tqdm(total=10, bar_format=\"{postfix[0]} {postfix[1][value]:>8.2g}\",\n              postfix=[\"Batch\", {\"value\": 0}]) as t:\n        for i in range(10):\n            sleep(0.1)\n            t.postfix[1][\"value\"] = i / 2\n            t.update()\n\nPoints to remember when using ``{postfix[...]}`` in the ``bar_format`` string:\n\n- ``postfix`` also needs to be passed as an initial argument in a compatible\n  format, and\n- ``postfix`` will be auto-converted to a string if it is a ``dict``-like\n  object. To prevent this behaviour, insert an extra item into the dictionary\n  where the key is not a string.\n\nAdditional ``bar_format`` parameters may also be defined by overriding\n``format_dict``, and the bar itself may be modified using ``ascii``:\n\n.. code:: python\n\n    from tqdm import tqdm\n    class TqdmExtraFormat(tqdm):\n        \"\"\"Provides a `total_time` format parameter\"\"\"\n        @property\n        def format_dict(self):\n            d = super().format_dict\n            total_time = d[\"elapsed\"] * (d[\"total\"] or 0) / max(d[\"n\"], 1)\n            d.update(total_time=self.format_interval(total_time) + \" in total\")\n            return d\n\n    for i in TqdmExtraFormat(\n          range(9), ascii=\" .oO0\",\n          bar_format=\"{total_time}: {percentage:.0f}%|{bar}{r_bar}\"):\n        if i == 4:\n            break\n\n.. code::\n\n    00:00 in total: 44%|0000.     | 4/9 [00:00<00:00, 962.93it/s]\n\nNote that ``{bar}`` also supports a format specifier ``[width][type]``.\n\n- ``width``\n\n  * unspecified (default): automatic to fill ``ncols``\n  * ``int >= 0``: fixed width overriding ``ncols`` logic\n  * ``int < 0``: subtract from the automatic default\n\n- ``type``\n\n  * ``a``: ascii (``ascii=True`` override)\n  * ``u``: unicode (``ascii=False`` override)\n  * ``b``: blank (``ascii=\"  \"`` override)\n\nThis means a fixed bar with right-justified text may be created by using:\n``bar_format=\"{l_bar}{bar:10}|{bar:-10b}right-justified\"``\n\nNested progress bars\n~~~~~~~~~~~~~~~~~~~~\n\n``tqdm`` supports nested progress bars. Here's an example:\n\n.. code:: python\n\n    from tqdm.auto import trange\n    from time import sleep\n\n    for i in trange(4, desc='1st loop'):\n        for j in trange(5, desc='2nd loop'):\n            for k in trange(50, desc='3rd loop', leave=False):\n                sleep(0.01)\n\nFor manual control over positioning (e.g. for multi-processing use),\nyou may specify ``position=n`` where ``n=0`` for the outermost bar,\n``n=1`` for the next, and so on.\nHowever, it's best to check if ``tqdm`` can work without manual ``position``\nfirst.\n\n.. code:: python\n\n    from time import sleep\n    from tqdm import trange, tqdm\n    from multiprocessing import Pool, RLock, freeze_support\n\n    L = list(range(9))\n\n    def progresser(n):\n        interval = 0.001 / (n + 2)\n        total = 5000\n        text = f\"#{n}, est. {interval * total:<04.2}s\"\n        for _ in trange(total, desc=text, position=n):\n            sleep(interval)\n\n    if __name__ == '__main__':\n        freeze_support()  # for Windows support\n        tqdm.set_lock(RLock())  # for managing output contention\n        p = Pool(initializer=tqdm.set_lock, initargs=(tqdm.get_lock(),))\n        p.map(progresser, L)\n\nNote that in Python 3, ``tqdm.write`` is thread-safe:\n\n.. code:: python\n\n    from time import sleep\n    from tqdm import tqdm, trange\n    from concurrent.futures import ThreadPoolExecutor\n\n    L = list(range(9))\n\n    def progresser(n):\n        interval = 0.001 / (n + 2)\n        total = 5000\n        text = f\"#{n}, est. {interval * total:<04.2}s\"\n        for _ in trange(total, desc=text):\n            sleep(interval)\n        if n == 6:\n            tqdm.write(\"n == 6 completed.\")\n            tqdm.write(\"`tqdm.write()` is thread-safe in py3!\")\n\n    if __name__ == '__main__':\n        with ThreadPoolExecutor() as p:\n            p.map(progresser, L)\n\nHooks and callbacks\n~~~~~~~~~~~~~~~~~~~\n\n``tqdm`` can easily support callbacks/hooks and manual updates.\nHere's an example with ``urllib``:\n\n**``urllib.urlretrieve`` documentation**\n\n    | [...]\n    | If present, the hook function will be called once\n    | on establishment of the network connection and once after each block read\n    | thereafter. The hook will be passed three arguments; a count of blocks\n    | transferred so far, a block size in bytes, and the total size of the file.\n    | [...]\n\n.. code:: python\n\n    import urllib, os\n    from tqdm import tqdm\n    urllib = getattr(urllib, 'request', urllib)\n\n    class TqdmUpTo(tqdm):\n        \"\"\"Provides `update_to(n)` which uses `tqdm.update(delta_n)`.\"\"\"\n        def update_to(self, b=1, bsize=1, tsize=None):\n            \"\"\"\n            b  : int, optional\n                Number of blocks transferred so far [default: 1].\n            bsize  : int, optional\n                Size of each block (in tqdm units) [default: 1].\n            tsize  : int, optional\n                Total size (in tqdm units). If [default: None] remains unchanged.\n            \"\"\"\n            if tsize is not None:\n                self.total = tsize\n            return self.update(b * bsize - self.n)  # also sets self.n = b * bsize\n\n    eg_link = \"https://caspersci.uk.to/matryoshka.zip\"\n    with TqdmUpTo(unit='B', unit_scale=True, unit_divisor=1024, miniters=1,\n                  desc=eg_link.split('/')[-1]) as t:  # all optional kwargs\n        urllib.urlretrieve(eg_link, filename=os.devnull,\n                           reporthook=t.update_to, data=None)\n        t.total = t.n\n\nInspired by `twine#242 <https://github.com/pypa/twine/pull/242>`__.\nFunctional alternative in\n`examples/tqdm_wget.py <https://github.com/tqdm/tqdm/blob/master/examples/tqdm_wget.py>`__.\n\nIt is recommend to use ``miniters=1`` whenever there is potentially\nlarge differences in iteration speed (e.g. downloading a file over\na patchy connection).\n\n**Wrapping read/write methods**\n\nTo measure throughput through a file-like object's ``read`` or ``write``\nmethods, use ``CallbackIOWrapper``:\n\n.. code:: python\n\n    from tqdm.auto import tqdm\n    from tqdm.utils import CallbackIOWrapper\n\n    with tqdm(total=file_obj.size,\n              unit='B', unit_scale=True, unit_divisor=1024) as t:\n        fobj = CallbackIOWrapper(t.update, file_obj, \"read\")\n        while True:\n            chunk = fobj.read(chunk_size)\n            if not chunk:\n                break\n        t.reset()\n        # ... continue to use `t` for something else\n\nAlternatively, use the even simpler ``wrapattr`` convenience function,\nwhich would condense both the ``urllib`` and ``CallbackIOWrapper`` examples\ndown to:\n\n.. code:: python\n\n    import urllib, os\n    from tqdm import tqdm\n\n    eg_link = \"https://caspersci.uk.to/matryoshka.zip\"\n    response = getattr(urllib, 'request', urllib).urlopen(eg_link)\n    with tqdm.wrapattr(open(os.devnull, \"wb\"), \"write\",\n                       miniters=1, desc=eg_link.split('/')[-1],\n                       total=getattr(response, 'length', None)) as fout:\n        for chunk in response:\n            fout.write(chunk)\n\nThe ``requests`` equivalent is nearly identical:\n\n.. code:: python\n\n    import requests, os\n    from tqdm import tqdm\n\n    eg_link = \"https://caspersci.uk.to/matryoshka.zip\"\n    response = requests.get(eg_link, stream=True)\n    with tqdm.wrapattr(open(os.devnull, \"wb\"), \"write\",\n                       miniters=1, desc=eg_link.split('/')[-1],\n                       total=int(response.headers.get('content-length', 0))) as fout:\n        for chunk in response.iter_content(chunk_size=4096):\n            fout.write(chunk)\n\n**Custom callback**\n\n``tqdm`` is known for intelligently skipping unnecessary displays. To make a\ncustom callback take advantage of this, simply use the return value of\n``update()``. This is set to ``True`` if a ``display()`` was triggered.\n\n.. code:: python\n\n    from tqdm.auto import tqdm as std_tqdm\n\n    def external_callback(*args, **kwargs):\n        ...\n\n    class TqdmExt(std_tqdm):\n        def update(self, n=1):\n            displayed = super().update(n)\n            if displayed:\n                external_callback(**self.format_dict)\n            return displayed\n\n``asyncio``\n~~~~~~~~~~~\n\nNote that ``break`` isn't currently caught by asynchronous iterators.\nThis means that ``tqdm`` cannot clean up after itself in this case:\n\n.. code:: python\n\n    from tqdm.asyncio import tqdm\n\n    async for i in tqdm(range(9)):\n        if i == 2:\n            break\n\nInstead, either call ``pbar.close()`` manually or use the context manager syntax:\n\n.. code:: python\n\n    from tqdm.asyncio import tqdm\n\n    with tqdm(range(9)) as pbar:\n        async for i in pbar:\n            if i == 2:\n                break\n\nPandas Integration\n~~~~~~~~~~~~~~~~~~\n\nDue to popular demand we've added support for ``pandas`` -- here's an example\nfor ``DataFrame.progress_apply`` and ``DataFrameGroupBy.progress_apply``:\n\n.. code:: python\n\n    import pandas as pd\n    import numpy as np\n    from tqdm import tqdm\n\n    df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))\n\n    # Register `pandas.progress_apply` and `pandas.Series.map_apply` with `tqdm`\n    # (can use `tqdm.gui.tqdm`, `tqdm.notebook.tqdm`, optional kwargs, etc.)\n    tqdm.pandas(desc=\"my bar!\")\n\n    # Now you can use `progress_apply` instead of `apply`\n    # and `progress_map` instead of `map`\n    df.progress_apply(lambda x: x**2)\n    # can also groupby:\n    # df.groupby(0).progress_apply(lambda x: x**2)\n\nIn case you're interested in how this works (and how to modify it for your\nown callbacks), see the\n`examples <https://github.com/tqdm/tqdm/tree/master/examples>`__\nfolder or import the module and run ``help()``.\n\nKeras Integration\n~~~~~~~~~~~~~~~~~\n\nA ``keras`` callback is also available:\n\n.. code:: python\n\n    from tqdm.keras import TqdmCallback\n\n    ...\n\n    model.fit(..., verbose=0, callbacks=[TqdmCallback()])\n\nDask Integration\n~~~~~~~~~~~~~~~~\n\nA ``dask`` callback is also available:\n\n.. code:: python\n\n    from tqdm.dask import TqdmCallback\n\n    with TqdmCallback(desc=\"compute\"):\n        ...\n        arr.compute()\n\n    # or use callback globally\n    cb = TqdmCallback(desc=\"global\")\n    cb.register()\n    arr.compute()\n\nIPython/Jupyter Integration\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIPython/Jupyter is supported via the ``tqdm.notebook`` submodule:\n\n.. code:: python\n\n    from tqdm.notebook import trange, tqdm\n    from time import sleep\n\n    for i in trange(3, desc='1st loop'):\n        for j in tqdm(range(100), desc='2nd loop'):\n            sleep(0.01)\n\nIn addition to ``tqdm`` features, the submodule provides a native Jupyter\nwidget (compatible with IPython v1-v4 and Jupyter), fully working nested bars\nand colour hints (blue: normal, green: completed, red: error/interrupt,\nlight blue: no ETA); as demonstrated below.\n\n|Screenshot-Jupyter1|\n|Screenshot-Jupyter2|\n|Screenshot-Jupyter3|\n\nThe ``notebook`` version supports percentage or pixels for overall width\n(e.g.: ``ncols='100%'`` or ``ncols='480px'``).\n\nIt is also possible to let ``tqdm`` automatically choose between\nconsole or notebook versions by using the ``autonotebook`` submodule:\n\n.. code:: python\n\n    from tqdm.autonotebook import tqdm\n    tqdm.pandas()\n\nNote that this will issue a ``TqdmExperimentalWarning`` if run in a notebook\nsince it is not meant to be possible to distinguish between ``jupyter notebook``\nand ``jupyter console``. Use ``auto`` instead of ``autonotebook`` to suppress\nthis warning.\n\nNote that notebooks will display the bar in the cell where it was created.\nThis may be a different cell from the one where it is used.\nIf this is not desired, either\n\n- delay the creation of the bar to the cell where it must be displayed, or\n- create the bar with ``display=False``, and in a later cell call\n  ``display(bar.container)``:\n\n.. code:: python\n\n    from tqdm.notebook import tqdm\n    pbar = tqdm(..., display=False)\n\n.. code:: python\n\n    # different cell\n    display(pbar.container)\n\nThe ``keras`` callback has a ``display()`` method which can be used likewise:\n\n.. code:: python\n\n    from tqdm.keras import TqdmCallback\n    cbk = TqdmCallback(display=False)\n\n.. code:: python\n\n    # different cell\n    cbk.display()\n    model.fit(..., verbose=0, callbacks=[cbk])\n\nAnother possibility is to have a single bar (near the top of the notebook)\nwhich is constantly re-used (using ``reset()`` rather than ``close()``).\nFor this reason, the notebook version (unlike the CLI version) does not\nautomatically call ``close()`` upon ``Exception``.\n\n.. code:: python\n\n    from tqdm.notebook import tqdm\n    pbar = tqdm()\n\n.. code:: python\n\n    # different cell\n    iterable = range(100)\n    pbar.reset(total=len(iterable))  # initialise with new `total`\n    for i in iterable:\n        pbar.update()\n    pbar.refresh()  # force print final status but don't `close()`\n\nCustom Integration\n~~~~~~~~~~~~~~~~~~\n\nTo change the default arguments (such as making ``dynamic_ncols=True``),\nsimply use built-in Python magic:\n\n.. code:: python\n\n    from functools import partial\n    from tqdm import tqdm as std_tqdm\n    tqdm = partial(std_tqdm, dynamic_ncols=True)\n\nFor further customisation,\n``tqdm`` may be inherited from to create custom callbacks (as with the\n``TqdmUpTo`` example `above <#hooks-and-callbacks>`__) or for custom frontends\n(e.g. GUIs such as notebook or plotting packages). In the latter case:\n\n1. ``def __init__()`` to call ``super().__init__(..., gui=True)`` to disable\n   terminal ``status_printer`` creation.\n2. Redefine: ``close()``, ``clear()``, ``display()``.\n\nConsider overloading ``display()`` to use e.g.\n``self.frontend(**self.format_dict)`` instead of ``self.sp(repr(self))``.\n\nSome submodule examples of inheritance:\n\n- `tqdm/notebook.py <https://github.com/tqdm/tqdm/blob/master/tqdm/notebook.py>`__\n- `tqdm/gui.py <https://github.com/tqdm/tqdm/blob/master/tqdm/gui.py>`__\n- `tqdm/tk.py <https://github.com/tqdm/tqdm/blob/master/tqdm/tk.py>`__\n- `tqdm/contrib/slack.py <https://github.com/tqdm/tqdm/blob/master/tqdm/contrib/slack.py>`__\n- `tqdm/contrib/discord.py <https://github.com/tqdm/tqdm/blob/master/tqdm/contrib/discord.py>`__\n- `tqdm/contrib/telegram.py <https://github.com/tqdm/tqdm/blob/master/tqdm/contrib/telegram.py>`__\n\nDynamic Monitor/Meter\n~~~~~~~~~~~~~~~~~~~~~\n\nYou can use a ``tqdm`` as a meter which is not monotonically increasing.\nThis could be because ``n`` decreases (e.g. a CPU usage monitor) or ``total``\nchanges.\n\nOne example would be recursively searching for files. The ``total`` is the\nnumber of objects found so far, while ``n`` is the number of those objects which\nare files (rather than folders):\n\n.. code:: python\n\n    from tqdm import tqdm\n    import os.path\n\n    def find_files_recursively(path, show_progress=True):\n        files = []\n        # total=1 assumes `path` is a file\n        t = tqdm(total=1, unit=\"file\", disable=not show_progress)\n        if not os.path.exists(path):\n            raise IOError(\"Cannot find:\" + path)\n\n        def append_found_file(f):\n            files.append(f)\n            t.update()\n\n        def list_found_dir(path):\n            \"\"\"returns os.listdir(path) assuming os.path.isdir(path)\"\"\"\n            listing = os.listdir(path)\n            # subtract 1 since a \"file\" we found was actually this directory\n            t.total += len(listing) - 1\n            # fancy way to give info without forcing a refresh\n            t.set_postfix(dir=path[-10:], refresh=False)\n            t.update(0)  # may trigger a refresh\n            return listing\n\n        def recursively_search(path):\n            if os.path.isdir(path):\n                for f in list_found_dir(path):\n                    recursively_search(os.path.join(path, f))\n            else:\n                append_found_file(path)\n\n        recursively_search(path)\n        t.set_postfix(dir=path)\n        t.close()\n        return files\n\nUsing ``update(0)`` is a handy way to let ``tqdm`` decide when to trigger a\ndisplay refresh to avoid console spamming.\n\nWriting messages\n~~~~~~~~~~~~~~~~\n\nThis is a work in progress (see\n`#737 <https://github.com/tqdm/tqdm/issues/737>`__).\n\nSince ``tqdm`` uses a simple printing mechanism to display progress bars,\nyou should not write any message in the terminal using ``print()`` while\na progressbar is open.\n\nTo write messages in the terminal without any collision with ``tqdm`` bar\ndisplay, a ``.write()`` method is provided:\n\n.. code:: python\n\n    from tqdm.auto import tqdm, trange\n    from time import sleep\n\n    bar = trange(10)\n    for i in bar:\n        # Print using tqdm class method .write()\n        sleep(0.1)\n        if not (i % 3):\n            tqdm.write(\"Done task %i\" % i)\n        # Can also use bar.write()\n\nBy default, this will print to standard output ``sys.stdout``. but you can\nspecify any file-like object using the ``file`` argument. For example, this\ncan be used to redirect the messages writing to a log file or class.\n\nRedirecting writing\n~~~~~~~~~~~~~~~~~~~\n\nIf using a library that can print messages to the console, editing the library\nby  replacing ``print()`` with ``tqdm.write()`` may not be desirable.\nIn that case, redirecting ``sys.stdout`` to ``tqdm.write()`` is an option.\n\nTo redirect ``sys.stdout``, create a file-like class that will write\nany input string to ``tqdm.write()``, and supply the arguments\n``file=sys.stdout, dynamic_ncols=True``.\n\nA reusable canonical example is given below:\n\n.. code:: python\n\n    from time import sleep\n    import contextlib\n    import sys\n    from tqdm import tqdm\n    from tqdm.contrib import DummyTqdmFile\n\n\n    @contextlib.contextmanager\n    def std_out_err_redirect_tqdm():\n        orig_out_err = sys.stdout, sys.stderr\n        try:\n            sys.stdout, sys.stderr = map(DummyTqdmFile, orig_out_err)\n            yield orig_out_err[0]\n        # Relay exceptions\n        except Exception as exc:\n            raise exc\n        # Always restore sys.stdout/err if necessary\n        finally:\n            sys.stdout, sys.stderr = orig_out_err\n\n    def some_fun(i):\n        print(\"Fee, fi, fo,\".split()[i])\n\n    # Redirect stdout to tqdm.write() (don't forget the `as save_stdout`)\n    with std_out_err_redirect_tqdm() as orig_stdout:\n        # tqdm needs the original stdout\n        # and dynamic_ncols=True to autodetect console width\n        for i in tqdm(range(3), file=orig_stdout, dynamic_ncols=True):\n            sleep(.5)\n            some_fun(i)\n\n    # After the `with`, printing is restored\n    print(\"Done!\")\n\nRedirecting ``logging``\n~~~~~~~~~~~~~~~~~~~~~~~\n\nSimilar to ``sys.stdout``/``sys.stderr`` as detailed above, console ``logging``\nmay also be redirected to ``tqdm.write()``.\n\nWarning: if also redirecting ``sys.stdout``/``sys.stderr``, make sure to\nredirect ``logging`` first if needed.\n\nHelper methods are available in ``tqdm.contrib.logging``. For example:\n\n.. code:: python\n\n    import logging\n    from tqdm import trange\n    from tqdm.contrib.logging import logging_redirect_tqdm\n\n    LOG = logging.getLogger(__name__)\n\n    if __name__ == '__main__':\n        logging.basicConfig(level=logging.INFO)\n        with logging_redirect_tqdm():\n            for i in trange(9):\n                if i == 4:\n                    LOG.info(\"console logging redirected to `tqdm.write()`\")\n        # logging restored\n\nMonitoring thread, intervals and miniters\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n``tqdm`` implements a few tricks to increase efficiency and reduce overhead.\n\n- Avoid unnecessary frequent bar refreshing: ``mininterval`` defines how long\n  to wait between each refresh. ``tqdm`` always gets updated in the background,\n  but it will display only every ``mininterval``.\n- Reduce number of calls to check system clock/time.\n- ``mininterval`` is more intuitive to configure than ``miniters``.\n  A clever adjustment system ``dynamic_miniters`` will automatically adjust\n  ``miniters`` to the amount of iterations that fit into time ``mininterval``.\n  Essentially, ``tqdm`` will check if it's time to print without actually\n  checking time. This behaviour can be still be bypassed by manually setting\n  ``miniters``.\n\nHowever, consider a case with a combination of fast and slow iterations.\nAfter a few fast iterations, ``dynamic_miniters`` will set ``miniters`` to a\nlarge number. When iteration rate subsequently slows, ``miniters`` will\nremain large and thus reduce display update frequency. To address this:\n\n- ``maxinterval`` defines the maximum time between display refreshes.\n  A concurrent monitoring thread checks for overdue updates and forces one\n  where necessary.\n\nThe monitoring thread should not have a noticeable overhead, and guarantees\nupdates at least every 10 seconds by default.\nThis value can be directly changed by setting the ``monitor_interval`` of\nany ``tqdm`` instance (i.e. ``t = tqdm.tqdm(...); t.monitor_interval = 2``).\nThe monitor thread may be disabled application-wide by setting\n``tqdm.tqdm.monitor_interval = 0`` before instantiation of any ``tqdm`` bar.\n\n\nMerch\n-----\n\nYou can buy `tqdm branded merch <https://tqdm.github.io/merch>`__ now!\n\nContributions\n-------------\n\n|GitHub-Commits| |GitHub-Issues| |GitHub-PRs| |OpenHub-Status| |GitHub-Contributions| |CII Best Practices|\n\nAll source code is hosted on `GitHub <https://github.com/tqdm/tqdm>`__.\nContributions are welcome.\n\nSee the\n`CONTRIBUTING <https://github.com/tqdm/tqdm/blob/master/CONTRIBUTING.md>`__\nfile for more information.\n\nDevelopers who have made significant contributions, ranked by *SLoC*\n(surviving lines of code,\n`git fame <https://github.com/casperdcl/git-fame>`__ ``-wMC --excl '\\.(png|gif|jpg)$'``),\nare:\n\n==================== ======================================================== ==== ================================\nName                 ID                                                       SLoC Notes\n==================== ======================================================== ==== ================================\nCasper da Costa-Luis `casperdcl <https://github.com/casperdcl>`__             ~80% primary maintainer |Gift-Casper|\nStephen Larroque     `lrq3000 <https://github.com/lrq3000>`__                 ~9%  team member\nMartin Zugnoni       `martinzugnoni <https://github.com/martinzugnoni>`__     ~3%\nDaniel Ecer          `de-code <https://github.com/de-code>`__                 ~2%\nRichard Sheridan     `richardsheridan <https://github.com/richardsheridan>`__ ~1%\nGuangshuo Chen       `chengs <https://github.com/chengs>`__                   ~1%\nHelio Machado        `0x2b3bfa0 <https://github.com/0x2b3bfa0>`__             ~1%\nKyle Altendorf       `altendky <https://github.com/altendky>`__               <1%\nNoam Yorav-Raphael   `noamraph <https://github.com/noamraph>`__               <1%  original author\nMatthew Stevens      `mjstevens777 <https://github.com/mjstevens777>`__       <1%\nHadrien Mary         `hadim <https://github.com/hadim>`__                     <1%  team member\nMikhail Korobov      `kmike <https://github.com/kmike>`__                     <1%  team member\n==================== ======================================================== ==== ================================\n\nPorts to Other Languages\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nA list is available on\n`this wiki page <https://github.com/tqdm/tqdm/wiki/tqdm-ports>`__.\n\n\nLICENCE\n-------\n\nOpen Source (OSI approved): |LICENCE|\n\nCitation information: |DOI|\n\n|README-Hits| (Since 19 May 2016)\n\n.. |Logo| image:: https://tqdm.github.io/img/logo.gif\n.. |Screenshot| image:: https://tqdm.github.io/img/tqdm.gif\n.. |Video| image:: https://tqdm.github.io/img/video.jpg\n   :target: https://tqdm.github.io/video\n.. |Slides| image:: https://tqdm.github.io/img/slides.jpg\n   :target: https://tqdm.github.io/PyData2019/slides.html\n.. |Merch| image:: https://tqdm.github.io/img/merch.jpg\n   :target: https://tqdm.github.io/merch\n.. |Build-Status| image:: https://img.shields.io/github/actions/workflow/status/tqdm/tqdm/test.yml?branch=master&label=tqdm&logo=GitHub\n   :target: https://github.com/tqdm/tqdm/actions/workflows/test.yml\n.. |Coverage-Status| image:: https://img.shields.io/coveralls/github/tqdm/tqdm/master?logo=coveralls\n   :target: https://coveralls.io/github/tqdm/tqdm\n.. |Branch-Coverage-Status| image:: https://codecov.io/gh/tqdm/tqdm/branch/master/graph/badge.svg\n   :target: https://codecov.io/gh/tqdm/tqdm\n.. |Codacy-Grade| image:: https://app.codacy.com/project/badge/Grade/3f965571598f44549c7818f29cdcf177\n   :target: https://www.codacy.com/gh/tqdm/tqdm/dashboard\n.. |CII Best Practices| image:: https://bestpractices.coreinfrastructure.org/projects/3264/badge\n   :target: https://bestpractices.coreinfrastructure.org/projects/3264\n.. |GitHub-Status| image:: https://img.shields.io/github/tag/tqdm/tqdm.svg?maxAge=86400&logo=github&logoColor=white\n   :target: https://github.com/tqdm/tqdm/releases\n.. |GitHub-Forks| image:: https://img.shields.io/github/forks/tqdm/tqdm.svg?logo=github&logoColor=white\n   :target: https://github.com/tqdm/tqdm/network\n.. |GitHub-Stars| image:: https://img.shields.io/github/stars/tqdm/tqdm.svg?logo=github&logoColor=white\n   :target: https://github.com/tqdm/tqdm/stargazers\n.. |GitHub-Commits| image:: https://img.shields.io/github/commit-activity/y/tqdm/tqdm.svg?logo=git&logoColor=white\n   :target: https://github.com/tqdm/tqdm/graphs/commit-activity\n.. |GitHub-Issues| image:: https://img.shields.io/github/issues-closed/tqdm/tqdm.svg?logo=github&logoColor=white\n   :target: https://github.com/tqdm/tqdm/issues?q=\n.. |GitHub-PRs| image:: https://img.shields.io/github/issues-pr-closed/tqdm/tqdm.svg?logo=github&logoColor=white\n   :target: https://github.com/tqdm/tqdm/pulls\n.. |GitHub-Contributions| image:: https://img.shields.io/github/contributors/tqdm/tqdm.svg?logo=github&logoColor=white\n   :target: https://github.com/tqdm/tqdm/graphs/contributors\n.. |GitHub-Updated| image:: https://img.shields.io/github/last-commit/tqdm/tqdm/master.svg?logo=github&logoColor=white&label=pushed\n   :target: https://github.com/tqdm/tqdm/pulse\n.. |Gift-Casper| image:: https://img.shields.io/badge/dynamic/json.svg?color=ff69b4&label=gifts%20received&prefix=%C2%A3&query=%24..sum&url=https%3A%2F%2Fcaspersci.uk.to%2Fgifts.json\n   :target: https://cdcl.ml/sponsor\n.. |Versions| image:: https://img.shields.io/pypi/v/tqdm.svg\n   :target: https://tqdm.github.io/releases\n.. |PyPI-Downloads| image:: https://img.shields.io/pypi/dm/tqdm.svg?label=pypi%20downloads&logo=PyPI&logoColor=white\n   :target: https://pepy.tech/project/tqdm\n.. |Py-Versions| image:: https://img.shields.io/pypi/pyversions/tqdm.svg?logo=python&logoColor=white\n   :target: https://pypi.org/project/tqdm\n.. |Conda-Forge-Status| image:: https://img.shields.io/conda/v/conda-forge/tqdm.svg?label=conda-forge&logo=conda-forge\n   :target: https://anaconda.org/conda-forge/tqdm\n.. |Snapcraft| image:: https://img.shields.io/badge/snap-install-82BEA0.svg?logo=snapcraft\n   :target: https://snapcraft.io/tqdm\n.. |Docker| image:: https://img.shields.io/badge/docker-pull-blue.svg?logo=docker&logoColor=white\n   :target: https://hub.docker.com/r/tqdm/tqdm\n.. |Libraries-Rank| image:: https://img.shields.io/librariesio/sourcerank/pypi/tqdm.svg?logo=koding&logoColor=white\n   :target: https://libraries.io/pypi/tqdm\n.. |Libraries-Dependents| image:: https://img.shields.io/librariesio/dependent-repos/pypi/tqdm.svg?logo=koding&logoColor=white\n    :target: https://github.com/tqdm/tqdm/network/dependents\n.. |OpenHub-Status| image:: https://www.openhub.net/p/tqdm/widgets/project_thin_badge?format=gif\n   :target: https://www.openhub.net/p/tqdm?ref=Thin+badge\n.. |awesome-python| image:: https://awesome.re/mentioned-badge.svg\n   :target: https://github.com/vinta/awesome-python\n.. |LICENCE| image:: https://img.shields.io/pypi/l/tqdm.svg\n   :target: https://raw.githubusercontent.com/tqdm/tqdm/master/LICENCE\n.. |DOI| image:: https://img.shields.io/badge/DOI-10.5281/zenodo.595120-blue.svg\n   :target: https://doi.org/10.5281/zenodo.595120\n.. |binder-demo| image:: https://mybinder.org/badge_logo.svg\n   :target: https://mybinder.org/v2/gh/tqdm/tqdm/master?filepath=DEMO.ipynb\n.. |Screenshot-Jupyter1| image:: https://tqdm.github.io/img/jupyter-1.gif\n.. |Screenshot-Jupyter2| image:: https://tqdm.github.io/img/jupyter-2.gif\n.. |Screenshot-Jupyter3| image:: https://tqdm.github.io/img/jupyter-3.gif\n.. |README-Hits| image:: https://cgi.cdcl.ml/hits?q=tqdm&style=social&r=https://github.com/tqdm/tqdm&l=https://tqdm.github.io/img/favicon.png&f=https://tqdm.github.io/img/logo.gif\n   :target: https://cgi.cdcl.ml/hits?q=tqdm&a=plot&r=https://github.com/tqdm/tqdm&l=https://tqdm.github.io/img/favicon.png&f=https://tqdm.github.io/img/logo.gif&style=social\n",
    "bugtrack_url": null,
    "license": "MPL-2.0 AND MIT",
    "summary": "Fast, Extensible Progress Meter",
    "version": "4.67.0",
    "project_urls": {
        "changelog": "https://tqdm.github.io/releases",
        "homepage": "https://tqdm.github.io",
        "repository": "https://github.com/tqdm/tqdm",
        "wiki": "https://github.com/tqdm/tqdm/wiki"
    },
    "split_keywords": [
        "progressbar",
        " progressmeter",
        " progress",
        " bar",
        " meter",
        " rate",
        " eta",
        " console",
        " terminal",
        " time"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2b7857043611a16c655c8350b4c01b8d6abfb38cc2acb475238b62c2146186d7",
                "md5": "04d05514ac0a5cf558db54d15f649a8b",
                "sha256": "0cd8af9d56911acab92182e88d763100d4788bdf421d251616040cc4d44863be"
            },
            "downloads": -1,
            "filename": "tqdm-4.67.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "04d05514ac0a5cf558db54d15f649a8b",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 78590,
            "upload_time": "2024-11-06T16:35:35",
            "upload_time_iso_8601": "2024-11-06T16:35:35.023820Z",
            "url": "https://files.pythonhosted.org/packages/2b/78/57043611a16c655c8350b4c01b8d6abfb38cc2acb475238b62c2146186d7/tqdm-4.67.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "e84f0153c21dc5779a49a0598c445b1978126b1344bab9ee71e53e44877e14e0",
                "md5": "3495f2a40a26a4f1caea279630f13521",
                "sha256": "fe5a6f95e6fe0b9755e9469b77b9c3cf850048224ecaa8293d7d2d31f97d869a"
            },
            "downloads": -1,
            "filename": "tqdm-4.67.0.tar.gz",
            "has_sig": false,
            "md5_digest": "3495f2a40a26a4f1caea279630f13521",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 169739,
            "upload_time": "2024-11-06T16:35:37",
            "upload_time_iso_8601": "2024-11-06T16:35:37.677419Z",
            "url": "https://files.pythonhosted.org/packages/e8/4f/0153c21dc5779a49a0598c445b1978126b1344bab9ee71e53e44877e14e0/tqdm-4.67.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-11-06 16:35:37",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "tqdm",
    "github_project": "tqdm",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "tqdm"
}