tqdm
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!
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))
Overhead is low – about 60ns per iteration (80ns with gui=True). By comparison, the well established ProgressBar has an 800ns/iter overhead. It’s a matter of taste, but we also like to think our version is much more visually appealing.
tqdm works on any platform (Linux/Windows/Mac), in any console or in a GUI, and is also friendly with IPython/Jupyter notebooks.
Installation
Latest pypi stable release
pip install tqdmLatest development release on github
Pull and install in the current directory:
pip install -e git+https://github.com/tqdm/tqdm.git@master#egg=tqdmDocumentation
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 onceon establishment of the network connection and once after each block readthereafter. The hook will be passed three arguments; a count of blockstransferred so far, a block size in bytes, and the total size of the file.[…]
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:
$ make flake8
$ make test
$ make coverageSee the CONTRIBUTE file for more information.
License
2 maintainers
Metadata
2 maintainers
Release files for tqdm 2.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distributions (sdists)
| File | Size | Uploaded | |
|---|---|---|---|
| tqdm-2.2.3.zip | 38.9 kB | Details | |
| tqdm-2.2.3.tar.gz | 31.0 kB | Details |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tqdm-2.2.3.win32.exe | Details | |||
| tqdm-2.2.3-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details |
Total release size: 305.9 kB
Release files / tqdm-2.2.3.zip
| Download URL | tqdm-2.2.3.zip |
|---|---|
| Size | 38.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
525de0c3e8cb56a4854c33d7de90766561b4b974dcd0360ea4b312abdfa59c0f
|
|
BLAKE2b-256 checksum How to use checksums |
7c7a5ebf3dddb606ede35bc4d25db0615f0f0d95ed06afa46ef21fa640562b74
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Release files / tqdm-2.2.3.tar.gz
| Download URL | tqdm-2.2.3.tar.gz |
|---|---|
| Size | 31.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3c21de7d600e5b6e2d30914e07d8e9743277950212122f1853fe8f7374418f18
|
|
BLAKE2b-256 checksum How to use checksums |
25db7a1e354dad2fa41b1cb702e417376eb7f6a148ad2ae6f156f6015c66f6a2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Release files / tqdm-2.2.3.win32.exe
| Download URL | tqdm-2.2.3.win32.exe |
|---|---|
| Size | 218.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fe3e943bc69c6b5d4730a39a4e8df662b8a42d2c0585798fefdf4c1c747b2009
|
|
BLAKE2b-256 checksum How to use checksums |
a8683f98aa107729c7d96c88d329898bc65607e79797b9c88392849a1c3ed385
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Release files / tqdm-2.2.3-py2.py3-none-any.whl
| Download URL | tqdm-2.2.3-py2.py3-none-any.whl |
|---|---|
| Size | 17.4 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
742c07c729605c3fd6757ffb63d480f1570fc6597e8c5c3a320e52365afab02d
|
|
BLAKE2b-256 checksum How to use checksums |
8bdc816b5d21a3ebb6e43053614e39ed55b3f502926241ff91ca6118bbedf64a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
