mirror of https://github.com/tqdm/tqdm.git
260 lines
8.5 KiB
ReStructuredText
260 lines
8.5 KiB
ReStructuredText
|Logo|
|
||
|
||
tqdm
|
||
====
|
||
|
||
|Build Status| |Coverage Status| |PyPi Status| |PyPi Downloads|
|
||
|
||
tqdm (read taqadum, تقدّم) means "progress" in arabic.
|
||
|
||
Instantly make your loops show a progress meter - just wrap any
|
||
iterable with "tqdm(iterable)", and you're done!
|
||
|
||
.. code:: python
|
||
|
||
from tqdm import tqdm
|
||
for i in tqdm(range(9)):
|
||
...
|
||
|
||
Here's what the output looks like:
|
||
|
||
76%\|████████████████████\ \| 7641/10000 [00:34<00:10,
|
||
222.22 it/s]
|
||
|
||
You can also use ``trange(N)`` as a shortcut for ``tqdm(xrange(N))``
|
||
|
||
|Screenshot|
|
||
|
||
Overhead is low -- about 60ns per iteration (80ns with ``gui=True``).
|
||
By comparison, the well established
|
||
`ProgressBar <https://code.google.com/p/python-progressbar/>`__ has
|
||
an 800ns/iter overhead. It's a matter of taste, but we also like to think our
|
||
version is much more visually appealing.
|
||
|
||
tqdm works on any platform (Linux/Windows/Mac), in any console or in a GUI,
|
||
and is also friendly with IPython/Jupyter notebooks.
|
||
|
||
|
||
Installation
|
||
------------
|
||
|
||
Latest pypi stable release
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
.. code:: sh
|
||
|
||
pip install tqdm
|
||
|
||
Latest development release on github
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Pull and install in the current directory:
|
||
|
||
.. code:: sh
|
||
|
||
pip install -e git+https://github.com/tqdm/tqdm.git@master#egg=tqdm
|
||
|
||
|
||
Documentation
|
||
-------------
|
||
|
||
.. code:: python
|
||
|
||
class tqdm(object):
|
||
"""
|
||
Decorate an iterable object, returning an iterator which acts exactly
|
||
like the orignal iterable, but prints a dynamically updating
|
||
progressbar every time a value is requested.
|
||
"""
|
||
|
||
def __init__(self, iterable=None, desc=None, total=None, leave=False,
|
||
file=sys.stderr, ncols=None, mininterval=0.1,
|
||
miniters=None, ascii=None, disable=False,
|
||
unit='it', unit_scale=False, gui=False, dynamic_ncols=False):
|
||
"""
|
||
Parameters
|
||
----------
|
||
iterable : iterable, optional
|
||
Iterable to decorate with a progressbar.
|
||
Leave blank [default: None] to manually manage the updates.
|
||
desc : str, optional
|
||
Prefix for the progressbar [default: None].
|
||
total : int, optional
|
||
The number of expected iterations. If not given, len(iterable) is
|
||
used if possible. As a last resort, only basic progress
|
||
statistics are displayed (no ETA, no progressbar). If `gui` is
|
||
True and this parameter needs subsequent updating, specify an
|
||
initial arbitrary large positive integer, e.g. int(9e9).
|
||
leave : bool, optional
|
||
If [default: False], removes all traces of the progressbar
|
||
upon termination of iteration.
|
||
file : `io.TextIOWrapper` or `io.StringIO`, optional
|
||
Specifies where to output the progress messages
|
||
[default: sys.stderr]. Uses `file.write(str)` and `file.flush()`
|
||
methods.
|
||
ncols : int, optional
|
||
The width of the entire output message. If specified, dynamically
|
||
resizes the progressbar to stay within this bound. If
|
||
[default: None], attempts to use environment width. The fallback
|
||
is a meter width of 10 and no limit for the counter and
|
||
statistics. If 0, will not print any meter (only stats).
|
||
mininterval : float, optional
|
||
Minimum progress update interval, in seconds [default: 0.1].
|
||
miniters : int, optional
|
||
Minimum progress update interval, in iterations [default: None].
|
||
If specified, will set `mininterval` to 0.
|
||
ascii : bool, optional
|
||
If [default: None] or false, use unicode (smooth blocks) to fill
|
||
the meter. The fallback is to use ASCII characters `1-9 #`.
|
||
disable : bool
|
||
Whether to disable the entire progressbar wrapper [default: False].
|
||
unit : str, optional
|
||
String that will be used to define the unit of each iteration
|
||
[default: 'it'].
|
||
unit_scale : bool, optional
|
||
If set, the number of iterations will be reduced/scaled
|
||
automatically and a metric prefix following the
|
||
International System of Units standard will be added
|
||
(kilo, mega, etc.) [default: False].
|
||
gui : bool, optional
|
||
If set, will attempt to use matplotlib animations for a
|
||
graphical output [default: false].
|
||
dynamic_ncols : bool, optional
|
||
If set, constantly alters `ncols` to the environment (allowing
|
||
for window resizes) [default: False].
|
||
|
||
Returns
|
||
-------
|
||
out : decorated iterator.
|
||
"""
|
||
|
||
def update(self, n=1):
|
||
"""
|
||
Manually update the progress bar, useful for streams
|
||
such as reading files.
|
||
E.g.:
|
||
>>> t = tqdm(total=filesize) # Initialise
|
||
>>> for current_buffer in stream:
|
||
... ...
|
||
... t.update(len(current_buffer))
|
||
>>> t.close()
|
||
The last line is highly recommended, but possibly not necessary if
|
||
`t.update()` will be called in such a way that `filesize` will be
|
||
exactly reached and printed.
|
||
|
||
Parameters
|
||
----------
|
||
n : int
|
||
Increment to add to the internal counter of iterations
|
||
[default: 1].
|
||
"""
|
||
|
||
def close(self):
|
||
"""
|
||
Cleanup and (if leave=False) close the progressbar.
|
||
"""
|
||
|
||
def trange(*args, **kwargs):
|
||
"""
|
||
A shortcut for tqdm(xrange(*args), **kwargs).
|
||
On Python3+ range is used instead of xrange.
|
||
"""
|
||
|
||
Examples and Advanced Usage
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
See the ``examples`` folder.
|
||
|
||
``tqdm`` can easily support callbacks/hooks and manual updates.
|
||
Here's an example with ``urllib``:
|
||
|
||
**urllib.urlretrieve documentation**
|
||
|
||
| [...]
|
||
| If present, the hook function will be called once
|
||
| on establishment of the network connection and once after each
|
||
block read
|
||
| thereafter. The hook will be passed three arguments; a count of
|
||
blocks
|
||
| transferred so far, a block size in bytes, and the total size of
|
||
the file.
|
||
| [...]
|
||
|
||
.. code:: python
|
||
|
||
import tqdm
|
||
import urllib
|
||
|
||
def my_hook(**kwargs):
|
||
t = tqdm.tqdm(**kwargs)
|
||
last_b = [0]
|
||
|
||
def inner(b=1, bsize=1, tsize=None, close=False):
|
||
if close:
|
||
t.close()
|
||
return
|
||
t.total = tsize
|
||
t.update((b - last_b[0]) * bsize) # manually update the progressbar
|
||
last_b[0] = b
|
||
return inner
|
||
|
||
eg_link = 'http://www.doc.ic.ac.uk/~cod11/matryoshka.zip'
|
||
eg_hook = my_hook(unit='B', unit_scale=True, leave=True, miniters=1,
|
||
desc=eg_link.split('/')[-1]) # all optional kwargs
|
||
urllib.urlretrieve(eg_link,
|
||
filename='/dev/null', reporthook=eg_hook, data=None)
|
||
eg_hook(close=True)
|
||
|
||
It is recommend to use ``miniters=1`` whenever there is potentially
|
||
large differences in iteration speed (e.g. downloading a file over
|
||
a patchy connection).
|
||
|
||
|
||
Contributions
|
||
-------------
|
||
|
||
To run the testing suite please make sure tox (http://tox.testrun.org/)
|
||
is installed, then type ``tox`` from the command line.
|
||
|
||
Alternatively if you don't want to use ``tox``, a Makefile is provided
|
||
with the following command:
|
||
|
||
.. code:: sh
|
||
|
||
$ make flake8
|
||
$ make test
|
||
$ make coverage
|
||
|
||
See the `CONTRIBUTE <https://raw.githubusercontent.com/tqdm/tqdm/master/CONTRIBUTE>`__
|
||
file for more information.
|
||
|
||
|
||
License
|
||
-------
|
||
|
||
`MIT LICENSE <https://raw.githubusercontent.com/tqdm/tqdm/master/LICENSE>`__.
|
||
|
||
|
||
Authors
|
||
-------
|
||
|
||
- Casper da Costa-Luis (casperdcl)
|
||
- Stephen Larroque (lrq3000)
|
||
- Hadrien Mary (hadim)
|
||
- Noam Yorav-Raphael (noamraph)*
|
||
- Ivan Ivanov (obiwanus)
|
||
- Mikhail Korobov (kmike)
|
||
|
||
`*` Original author
|
||
|
||
.. |Logo| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/logo.png
|
||
.. |Build Status| image:: https://travis-ci.org/tqdm/tqdm.svg?branch=master
|
||
:target: https://travis-ci.org/tqdm/tqdm
|
||
.. |Coverage Status| image:: https://coveralls.io/repos/tqdm/tqdm/badge.svg
|
||
:target: https://coveralls.io/r/tqdm/tqdm
|
||
.. |PyPi Status| image:: https://img.shields.io/pypi/v/tqdm.svg
|
||
:target: https://pypi.python.org/pypi/tqdm
|
||
.. |PyPi Downloads| image:: https://img.shields.io/pypi/dm/tqdm.svg
|
||
:target: https://pypi.python.org/pypi/tqdm
|
||
.. |Screenshot| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/tqdm.gif
|