tqdm/README.rst

260 lines
8.5 KiB
ReStructuredText
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

|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