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]
trange(N) can be also used as a convenient 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, maxinterval=10.0, miniters=None,
ascii=None, disable=False, unit='it', unit_scale=False,
dynamic_ncols=False, smoothing=0.3):Parameters
- iterableiterable, optional
Iterable to decorate with a progressbar. Leave blank [default: None] to manually manage the updates.
- descstr, optional
Prefix for the progressbar [default: None].
- totalint, 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).
- leavebool, optional
If [default: False], removes all traces of the progressbar upon termination of iteration.
- fileio.TextIOWrapper or io.StringIO, optional
Specifies where to output the progress messages [default: sys.stderr]. Uses file.write(str) and file.flush() methods.
- ncolsint, 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).
- minintervalfloat, optional
Minimum progress update interval, in seconds [default: 0.1].
- maxintervalfloat, optional
Maximum progress update interval, in seconds [default: 10.0].
- minitersint, optional
Minimum progress update interval, in iterations [default: None]. If specified, will set mininterval to 0.
- asciibool, optional
If [default: None] or false, use unicode (smooth blocks) to fill the meter. The fallback is to use ASCII characters 1-9 #.
- disablebool
Whether to disable the entire progressbar wrapper [default: False].
- unitstr, optional
String that will be used to define the unit of each iteration [default: ‘it’].
- unit_scalebool, 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].
- dynamic_ncolsbool, optional
If set, constantly alters ncols to the environment (allowing for window resizes) [default: False].
- smoothingfloat
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].
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.
"""
class tqdm_gui(tqdm):
"""
Experimental GUI version of tqdm!
"""
def tgrange(*args, **kwargs):
"""
Experimental GUI version of trange!
"""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
Release files for tqdm 3.1.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-3.1.3.zip | 44.0 kB | Details | |
| tqdm-3.1.3.tar.gz | 35.5 kB | Details |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tqdm-3.1.3.win32.exe | Details | |||
| tqdm-3.1.3-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details |
Total release size: 320.8 kB
Release files / tqdm-3.1.3.zip
| Download URL | tqdm-3.1.3.zip |
|---|---|
| Size | 44.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
47d869242f7f69204200167d6c6f031cf4db4758cbfa90fcad66d88046cc8df1
|
|
BLAKE2b-256 checksum How to use checksums |
c0cfa6b2035a22c4e3a2a00c3dd3a3c6cbf019c448a019364d10570ae9356850
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Release files / tqdm-3.1.3.tar.gz
| Download URL | tqdm-3.1.3.tar.gz |
|---|---|
| Size | 35.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
61bd6eabe05643bbc34609d5bd95b6588300202b847b7115c19b3fd24878d7e0
|
|
BLAKE2b-256 checksum How to use checksums |
d62400b393e4a8e78196c719c224ba80a60301eb76a5f4fffd76f6bdd4194f2b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Release files / tqdm-3.1.3.win32.exe
| Download URL | tqdm-3.1.3.win32.exe |
|---|---|
| Size | 221.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
173a654ab8b719c2f95e5312d46890417846caba816e207f6c64c57fc842e1ba
|
|
BLAKE2b-256 checksum How to use checksums |
5c00344b70d5754f0651b86c909883e046ef2377e1e4fca336661f7e7971987d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Release files / tqdm-3.1.3-py2.py3-none-any.whl
| Download URL | tqdm-3.1.3-py2.py3-none-any.whl |
|---|---|
| Size | 20.0 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
82eb59662e020e1c466dd03c0528cc94533ce0585da97ca377d385f026f11d4a
|
|
BLAKE2b-256 checksum How to use checksums |
ce5fa5821bfe8e7d9e6d73d4bd25e9be6144c247804e48324f3621a41ec2a76f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
