[Python-modules-commits] [tqdm] 01/10: Import tqdm_4.19.5.orig.tar.gz
Sandro Tosi
morph at moszumanska.debian.org
Mon Jan 1 03:48:16 UTC 2018
This is an automated email from the git hooks/post-receive script.
morph pushed a commit to branch master
in repository tqdm.
commit 3edc9c3cda1b1ed411f7556927e9da514134572a
Author: Sandro Tosi <morph at debian.org>
Date: Sun Dec 31 11:36:27 2017 -0500
Import tqdm_4.19.5.orig.tar.gz
---
LICENCE | 10 +-
MANIFEST.in | 6 +-
Makefile | 25 +-
PKG-INFO | 292 +++++++++++--------
README.rst | 289 +++++++++++--------
examples/7zx.py | 34 +--
examples/include_no_requirements.py | 1 +
examples/pandas_progress_apply.py | 1 -
examples/parallel_bars.py | 29 ++
examples/progressbar/__init__.pyc | Bin 1282 -> 0 bytes
examples/progressbar/compat.pyc | Bin 767 -> 0 bytes
examples/progressbar/progressbar.pyc | Bin 9870 -> 0 bytes
examples/progressbar/widgets.pyc | Bin 14752 -> 0 bytes
examples/redirect_print.py | 65 +++++
examples/simple_examples.py | 3 +-
examples/tqdm_wget.py | 51 +++-
setup.cfg | 1 -
setup.py | 2 +
tox.ini | 28 +-
tqdm.1 | 222 ++++++++++++++
tqdm.egg-info/PKG-INFO | 292 +++++++++++--------
tqdm.egg-info/SOURCES.txt | 8 +-
tqdm/_main.py | 8 +-
tqdm/_tqdm.py | 545 ++++++++++++++++++++++-------------
tqdm/_tqdm_gui.py | 11 +-
tqdm/_tqdm_notebook.py | 32 +-
tqdm/_utils.py | 34 ++-
tqdm/_version.py | 14 +-
tqdm/tests/tests_main.py | 8 +-
tqdm/tests/tests_pandas.py | 23 +-
tqdm/tests/tests_perf.py | 96 +++---
tqdm/tests/tests_tqdm.py | 350 ++++++++++++++--------
tqdm/tests/tests_version.py | 2 +-
33 files changed, 1645 insertions(+), 837 deletions(-)
diff --git a/LICENCE b/LICENCE
index b0b4be5..19b83e5 100644
--- a/LICENCE
+++ b/LICENCE
@@ -6,11 +6,15 @@ for their respective work, and release the work under the MIT licence
Exceptions or notable authors are listed below
in reverse chronological order:
-* MPLv2.0 (text below) 2015-2016 (c) Casper da Costa-Luis
+* files: *
+ MPLv2.0 2015-2017 (c) Casper da Costa-Luis
[casperdcl](https://github.com/casperdcl).
-* MIT 2016 (c) [PR #96] on behalf of Google Inc.
+* files: tqdm/_tqdm.py
+ MIT 2016 (c) [PR #96] on behalf of Google Inc.
+* files: tqdm/_tqdm.py setup.py README.rst MANIFEST.in .gitignore
+ MIT 2013 (c) Noam Yorav-Raphael, original author.
- [PR #96]: https://github.com/tqdm/tqdm/pull/96
+[PR #96]: https://github.com/tqdm/tqdm/pull/96
Mozilla Public Licence (MPL) v. 2.0 - Exhibit A
diff --git a/MANIFEST.in b/MANIFEST.in
index 9810bbf..557332d 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -5,12 +5,12 @@ include LICENCE
include logo.png
# include images/logo.gif
include Makefile
-include README.rst
-include RELEASE
include tox.ini
# Test suite
recursive-include tqdm/tests *.py
# Examples/Documentation
-recursive-include examples *
+recursive-include examples *.py
+include README.rst
+include tqdm.1
diff --git a/Makefile b/Makefile
index 70b4c72..bfaa62a 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,7 @@
# IMPORTANT: for compatibility with `python setup.py make [alias]`, ensure:
# 1. Every alias is preceded by @[+]make (eg: @make alias)
# 2. A maximum of one @make alias or command per line
+# 3. Only use tabs, not spaces to indent (compatibility with linux make)
#
# Sample makefile compatible with `python setup.py make`:
#```
@@ -48,7 +49,7 @@ all:
@+make build
flake8:
- @+flake8 --max-line-length=80 --count --statistics --exit-zero -j 8 --exclude .asv .
+ @+flake8 --max-line-length=80 --count --statistics --exit-zero -j 8 --exclude .asv,.tox .
test:
tox --skip-missing-interpreters
@@ -64,17 +65,21 @@ testcoverage:
@make coverclean
nosetests tqdm --with-coverage --cover-package=tqdm --cover-erase --cover-min-percentage=80 --ignore-files="tests_perf\.py" -d -v
-testperf: # do not use coverage (which is extremely slow)
+testperf:
+ # do not use coverage (which is extremely slow)
nosetests tqdm/tests/tests_perf.py -d -v
testtimer:
nosetests tqdm --with-timer -d -v
+# another performance test, to check evolution across commits
testasv:
+ # Test only the last 3 commits (quick test)
asv run -j 8 HEAD~3..HEAD
@make viewasv
testasvfull:
+ # Test all the commits since the beginning (full test)
asv run -j 8 v1.0.0..master
@make testasv
@@ -82,6 +87,12 @@ viewasv:
asv publish
asv preview
+tqdm.1: tqdm.1.md
+ python -m tqdm --help | tail -n+5 | cat "$<" - |\
+ sed -r 's/^ (--.*)=<(.*)> : (.*)$$/\n\\\1=*\2*\n: \3./' |\
+ sed -r 's/ (-.*, --.*) /\n\1\n: /' |\
+ pandoc -o "$@" -s -t man
+
distclean:
@+make coverclean
@+make prebuildclean
@@ -91,12 +102,12 @@ prebuildclean:
@+python -c "import shutil; shutil.rmtree('dist', True)"
@+python -c "import shutil; shutil.rmtree('tqdm.egg-info', True)"
coverclean:
- @+python -c "import os; os.remove('.coverage') if os.path.exists('.coverage') else None"
+ @+python -c "import os, glob; [os.remove(i) for i in glob.glob('.coverage')]"
clean:
- @+python -c "import os; import glob; [os.remove(i) for i in glob.glob('*.py[co]')]"
- @+python -c "import os; import glob; [os.remove(i) for i in glob.glob('tqdm/*.py[co]')]"
- @+python -c "import os; import glob; [os.remove(i) for i in glob.glob('tqdm/tests/*.py[co]')]"
- @+python -c "import os; import glob; [os.remove(i) for i in glob.glob('tqdm/examples/*.py[co]')]"
+ @+python -c "import os, glob; [os.remove(i) for i in glob.glob('*.py[co]')]"
+ @+python -c "import os, glob; [os.remove(i) for i in glob.glob('tqdm/*.py[co]')]"
+ @+python -c "import os, glob; [os.remove(i) for i in glob.glob('tqdm/tests/*.py[co]')]"
+ @+python -c "import os, glob; [os.remove(i) for i in glob.glob('tqdm/examples/*.py[co]')]"
installdev:
python setup.py develop --uninstall
diff --git a/PKG-INFO b/PKG-INFO
index cd4a4e8..bc2be50 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,11 +1,12 @@
Metadata-Version: 1.1
Name: tqdm
-Version: 4.11.2
+Version: 4.19.5
Summary: Fast, Extensible Progress Meter
Home-page: https://github.com/tqdm/tqdm
Author: tqdm developers
Author-email: python.tqdm at gmail.com
License: MPLv2.0, MIT Licences
+Description-Content-Type: UNKNOWN
Description: |Logo|
tqdm
@@ -15,7 +16,7 @@ Description: |Logo|
|Build-Status| |Coverage-Status| |Branch-Coverage-Status| |Codacy-Grade|
- |DOI-URI| |LICENCE|
+ |DOI-URI| |LICENCE| |OpenHub-Status|
``tqdm`` means "progress" in Arabic (taqadum, تقدّم)
@@ -51,7 +52,7 @@ Description: |Logo|
Overhead is low -- about 60ns per iteration (80ns with ``tqdm_gui``), and is
unit tested against performance regression.
- By comparison, the well established
+ By comparison, the well-established
`ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has
an 800ns/iter overhead.
@@ -59,12 +60,13 @@ Description: |Logo|
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, Solaris/SunOS),
+ ``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 library (not even curses!) to run, just a
- vanilla Python interpreter will do and an environment supporting ``carriage
- return \r`` and ``line feed \n`` control characters.
+ ``tqdm`` does not require any dependencies (not even ``curses``!), just
+ Python and an environment supporting ``carriage return \r`` and
+ ``line feed \n`` control characters.
------------------------------------------
@@ -85,10 +87,10 @@ Description: |Logo|
pip install tqdm
- Latest development release on github
+ Latest development release on GitHub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- |GitHub-Status| |GitHub-Stars| |GitHub-Forks|
+ |GitHub-Status| |GitHub-Stars| |GitHub-Commits| |GitHub-Forks|
Pull and install in the current directory:
@@ -177,7 +179,7 @@ Description: |Logo|
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 demonstrated counting the number of lines in all python files
+ The example below demonstrated counting the number of lines in all Python files
in the current directory, with timing information included.
.. code:: sh
@@ -217,29 +219,32 @@ Description: |Logo|
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``).
- 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>`__,
+ 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>`__ and
`here <https://github.com/tqdm/tqdm/issues/307>`__)
lack full support.
- * Windows: additionally may require the python module ``colorama``.
+ * Windows: additionally may require the Python module ``colorama``
+ to ensure nested bars stay within their respective lines.
- Wrapping enumerated iterables: use ``enumerate(tqdm(...))`` instead of
- ``tqdm(enumerate(...))`. The same applies to ``numpy.ndenumerate``.
+ ``tqdm(enumerate(...))``. The same applies to ``numpy.ndenumerate``.
This is because enumerate functions tend to hide the length of iterables.
``tqdm`` does not.
- Wrapping zipped iterables has similar issues due to internal optimisations.
``tqdm(zip(a, b))`` should be replaced with ``zip(tqdm(a), b)`` or even
- ``zip(tqdm(a), tqdm(b))``
+ ``zip(tqdm(a), tqdm(b))``.
- If you come across any other difficulties, browse/open issues
- `here <https://github.com/tqdm/tqdm/issues?q=is%3Aissue>`__.
+ If you come across any other difficulties, browse and file |GitHub-Issues|.
Documentation
-------------
@@ -256,7 +261,7 @@ Description: |Logo|
"""
def __init__(self, iterable=None, desc=None, total=None, leave=True,
- file=sys.stderr, ncols=None, mininterval=0.1,
+ 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,
@@ -282,7 +287,7 @@ Description: |Logo|
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()``
+ (default: sys.stderr). Uses ``file.write(str)`` and ``file.flush()``
methods.
* ncols : int, optional
The width of the entire output message. If specified,
@@ -314,11 +319,12 @@ Description: |Logo|
* 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
+ * 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].
+ (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`` to the environment (allowing
for window resizes) [default: False].
@@ -328,11 +334,15 @@ Description: |Logo|
(current/instantaneous speed) [default: 0.3].
* bar_format : str, optional
Specify a custom bar string formatting. May impact performance.
- If unspecified, will use '{l_bar}{bar}{r_bar}', where l_bar is
- '{desc}{percentage:3.0f}%|' and r_bar is
- '| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, {rate_fmt}]'
- Possible vars: bar, n, n_fmt, total, total_fmt, percentage,
- rate, rate_fmt, elapsed, remaining, l_bar, r_bar, desc.
+ [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, rate, rate_fmt, rate_noinv, rate_noinv_fmt,
+ rate_inv, rate_inv_fmt, elapsed, remaining, desc, postfix.
+ Note that a trailing ": " is automatically removed after {desc}
+ if the latter is empty.
* initial : int, optional
The initial counter value. Useful when restarting a progress
bar [default: 0].
@@ -342,6 +352,10 @@ Description: |Logo|
Useful to manage multiple bars at once (eg, from threads).
* postfix : dict, optional
Specify additional stats to display at the end of the bar.
+ Note: postfix is a dict ({'key': value} pairs) for this method,
+ not a string.
+ * unit_divisor : float, optional
+ [default: 1000], ignored unless `unit_scale` is True.
Extra CLI Options
~~~~~~~~~~~~~~~~~
@@ -378,7 +392,7 @@ Description: |Logo|
Parameters
----------
- n : int
+ n : int, optional
Increment to add to the internal counter of iterations
[default: 1].
"""
@@ -388,7 +402,12 @@ Description: |Logo|
Cleanup and (if leave=False) close the progressbar.
"""
- def clear(self):
+ def unpause(self):
+ """
+ Restart tqdm timer from last print time.
+ """
+
+ def clear(self, nomove=False):
"""
Clear current bar display
"""
@@ -403,15 +422,26 @@ Description: |Logo|
Print a message via tqdm (without overlap with bars)
"""
- def set_description(self, desc=None):
+ 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, **kwargs):
+ def set_postfix(self, ordered_dict=None, refresh=True, **kwargs):
"""
Set/modify postfix (additional stats)
with automatic formatting based on datatype.
+
+ Parameters
+ ----------
+ refresh : bool, optional
+ Forces refresh [default: True].
"""
def trange(*args, **kwargs):
@@ -448,7 +478,9 @@ Description: |Logo|
folder;
- import the module and run ``help()``, or
- 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.
+ - 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.
Description and additional stats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -466,7 +498,7 @@ Description: |Logo|
for i in t:
# Description will be displayed on the left
t.set_description('GEN %i' % i)
- # Postfix will be displayed on the right, and will format automatically
+ # Postfix will be displayed on the right, and will format automatically
# based on argument's datatype
t.set_postfix(loss=random(), gen=randint(1,999), str='h', lst=[1, 2])
sleep(0.1)
@@ -487,11 +519,34 @@ Description: |Logo|
sleep(0.01)
On Windows `colorama <https://github.com/tartley/colorama>`__ will be used if
- available to produce a beautiful nested display.
+ available to keep nested bars on their respective lines.
For manual control over positioning (e.g. for multi-threaded use),
- you may specify `position=n` where `n=0` for the outermost bar,
- `n=1` for the next, and so on.
+ you may specify ``position=n`` where ``n=0`` for the outermost bar,
+ ``n=1`` for the next, and so on:
+
+ .. code:: python
+
+ from time import sleep
+ from tqdm import trange
+ from multiprocessing import Pool, freeze_support, RLock
+
+ L = list(range(9))
+
+ def progresser(n):
+ interval = 0.001 / (n + 2)
+ total = 5000
+ text = "#{}, est. {:<04.2}s".format(n, interval * total)
+ for i in trange(total, desc=text, position=n):
+ sleep(interval)
+
+ if __name__ == '__main__':
+ freeze_support() # for Windows support
+ p = Pool(len(L),
+ # again, for Windows support
+ initializer=tqdm.set_lock, initargs=(RLock(),))
+ p.map(progresser, L)
+ print("\n" * (len(L) - 2))
Hooks and callbacks
~~~~~~~~~~~~~~~~~~~
@@ -503,54 +558,40 @@ Description: |Logo|
| [...]
| 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.
+ | 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
+ import urllib, os
from tqdm import tqdm
- def my_hook(t):
- """
- Wraps tqdm instance. Don't forget to close() or __exit__()
- the tqdm instance once you're done with it (easiest using `with` syntax).
-
- Example
- -------
-
- >>> with tqdm(...) as t:
- ... reporthook = my_hook(t)
- ... urllib.urlretrieve(..., reporthook=reporthook)
-
- """
- last_b = [0]
-
- def inner(b=1, bsize=1, tsize=None):
- """
- b : int, optional
- Number of blocks just transferred [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:
- t.total = tsize
- t.update((b - last_b[0]) * bsize)
- last_b[0] = b
- return inner
-
- eg_link = 'http://www.doc.ic.ac.uk/~cod11/matryoshka.zip'
- with tqdm(unit='B', unit_scale=True, miniters=1,
- desc=eg_link.split('/')[-1]) as t: # all optional kwargs
- urllib.urlretrieve(eg_link, filename='/dev/null',
- reporthook=my_hook(t), data=None)
+ 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
+ self.update(b * bsize - self.n) # will also set self.n = b * bsize
+
+ eg_link = "https://caspersci.uk.to/matryoshka.zip"
+ with TqdmUpTo(unit='B', unit_scale=True, 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)
+
+ 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
@@ -588,7 +629,7 @@ Description: |Logo|
IPython/Jupyter Integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- IPython/Jupyter is supported via the `tqdm_notebook` submodule:
+ IPython/Jupyter is supported via the ``tqdm_notebook`` submodule:
.. code:: python
@@ -599,7 +640,7 @@ Description: |Logo|
for j in tqdm_notebook(xrange(100), desc='2nd loop'):
sleep(0.01)
- In addition to `tqdm` features, the submodule provides a native Jupyter
+ In addition to ``tqdm`` features, the submodule provides a native Jupyter
widget (compatible with IPython v1-v4 and Jupyter), fully working nested bars
and color hints (blue: normal, green: completed, red: error/interrupt,
light blue: no ETA); as demonstrated below.
@@ -612,7 +653,8 @@ Description: |Logo|
~~~~~~~~~~~~~~~~
Since ``tqdm`` uses a simple printing mechanism to display progress bars,
- you should not write any message in the terminal using ``print()``.
+ 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:
@@ -650,10 +692,8 @@ Description: |Logo|
.. code:: python
from time import sleep
-
import contextlib
import sys
-
from tqdm import tqdm
class DummyTqdmFile(object):
@@ -667,57 +707,60 @@ Description: |Logo|
if len(x.rstrip()) > 0:
tqdm.write(x, file=self.file)
+ def flush(self):
+ return getattr(self.file, "flush", lambda: None)()
+
@contextlib.contextmanager
- def stdout_redirect_to_tqdm():
- save_stdout = sys.stdout
+ def std_out_err_redirect_tqdm():
+ orig_out_err = sys.stdout, sys.stderr
try:
- sys.stdout = DummyTqdmFile(sys.stdout)
- yield save_stdout
+ 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 if necessary
+ # Always restore sys.stdout/err if necessary
finally:
- sys.stdout = save_stdout
+ sys.stdout, sys.stderr = orig_out_err
- def blabla():
- print("Foo blabla")
+ def some_fun(i):
+ print("Fee, fi, fo,".split()[i])
# Redirect stdout to tqdm.write() (don't forget the `as save_stdout`)
- with stdout_redirect_to_tqdm() as save_stdout:
- # tqdm call need to specify sys.stdout, not sys.stderr (default)
+ with std_out_err_redirect_tqdm() as orig_stdout:
+ # tqdm needs the original stdout
# and dynamic_ncols=True to autodetect console width
- for _ in tqdm(range(3), file=save_stdout, dynamic_ncols=True):
- blabla()
+ 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!')
+ print("Done!")
Monitoring thread, intervals and miniters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``tqdm`` implements a few tricks to to increase efficiency and reduce overhead.
- 1. Avoid unnecessary frequent bar refreshing: ``mininterval`` defines how long
- to wait between each refresh. ``tqdm`` always gets updated in the background,
- but it will diplay only every ``mininterval``.
- 2. Reduce number of calls to check system clock/time.
- 3. ``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 behavior can be still be bypassed by manually setting
- ``miniters``.
+ - Avoid unnecessary frequent bar refreshing: ``mininterval`` defines how long
+ to wait between each refresh. ``tqdm`` always gets updated in the background,
+ but it will diplay 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 interation rate subsequently slows, ``miniters`` will
+ large number. When iteration rate subsequently slows, ``miniters`` will
remain large and thus reduce display update frequency. To address this:
- 4. ``maxinterval`` defines the maximum time between display refreshes.
- A concurrent monitoring thread checks for overdue updates and forces one
- where necessary.
+ - ``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.
@@ -730,6 +773,8 @@ Description: |Logo|
Contributions
-------------
+ |GitHub-Commits| |GitHub-Issues| |GitHub-PRs| |OpenHub-Status|
+
All source code is hosted on `GitHub <https://github.com/tqdm/tqdm>`__.
Contributions are welcome.
@@ -749,16 +794,15 @@ Description: |Logo|
Authors
-------
- Ranked by contributions.
+ The main developers, ranked by surviving lines of code, are:
- - Casper da Costa-Luis (casperdcl)
- - Stephen Larroque (lrq3000)
- - Hadrien Mary (hadim)
- - Noam Yorav-Raphael (noamraph)*
- - Ivan Ivanov (obiwanus)
- - Mikhail Korobov (kmike)
+ - Casper da Costa-Luis (`casperdcl <https://github.com/casperdcl>`__, ~2/3, |Gift-Casper|)
+ - Stephen Larroque (`lrq3000 <https://github.com/lrq3000>`__, ~1/3)
+ - Noam Yorav-Raphael (`noamraph <https://github.com/noamraph>`__, ~1%, original author)
+ - Hadrien Mary (`hadim <https://github.com/hadim>`__, ~1%)
+ - Mikhail Korobov (`kmike <https://github.com/kmike>`__, ~1%)
- `*` Original author
+ There are also many |GitHub-Contributions| which we are grateful for.
|README-Hits| (Since 19 May 2016)
@@ -772,12 +816,22 @@ Description: |Logo|
:target: https://codecov.io/github/tqdm/tqdm?branch=master
.. |Codacy-Grade| image:: https://api.codacy.com/project/badge/Grade/3f965571598f44549c7818f29cdcf177
:target: https://www.codacy.com/app/tqdm/tqdm?utm_source=github.com&utm_medium=referral&utm_content=tqdm/tqdm&utm_campaign=Badge_Grade
- .. |GitHub-Status| image:: https://img.shields.io/github/tag/tqdm/tqdm.svg?maxAge=2592000
+ .. |GitHub-Status| image:: https://img.shields.io/github/tag/tqdm/tqdm.svg?maxAge=86400
:target: https://github.com/tqdm/tqdm/releases
.. |GitHub-Forks| image:: https://img.shields.io/github/forks/tqdm/tqdm.svg
:target: https://github.com/tqdm/tqdm/network
.. |GitHub-Stars| image:: https://img.shields.io/github/stars/tqdm/tqdm.svg
:target: https://github.com/tqdm/tqdm/stargazers
+ .. |GitHub-Commits| image:: https://img.shields.io/github/commit-activity/y/tqdm/tqdm.svg
+ :target: https://github.com/tqdm/tqdm/graphs/commit-activity
+ .. |GitHub-Issues| image:: https://img.shields.io/github/issues-closed/tqdm/tqdm.svg
+ :target: https://github.com/tqdm/tqdm/issues
+ .. |GitHub-PRs| image:: https://img.shields.io/github/issues-pr-closed/tqdm/tqdm.svg
+ :target: https://github.com/tqdm/tqdm/pulls
+ .. |GitHub-Contributions| image:: https://img.shields.io/github/contributors/tqdm/tqdm.svg
+ :target: https://github.com/tqdm/tqdm/graphs/contributors
+ .. |Gift-Casper| image:: https://img.shields.io/badge/gift-donate-ff69b4.svg
+ :target: https://caspersci.uk.to/donate.html
.. |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
@@ -786,6 +840,8 @@ Description: |Logo|
:target: https://pypi.python.org/pypi/tqdm
.. |Conda-Forge-Status| image:: https://anaconda.org/conda-forge/tqdm/badges/version.svg
:target: https://anaconda.org/conda-forge/tqdm
+ .. |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
.. |LICENCE| image:: https://img.shields.io/pypi/l/tqdm.svg
:target: https://raw.githubusercontent.com/tqdm/tqdm/master/LICENCE
.. |DOI-URI| image:: https://zenodo.org/badge/21637/tqdm/tqdm.svg
diff --git a/README.rst b/README.rst
index 862810a..05f01b8 100644
--- a/README.rst
+++ b/README.rst
@@ -7,7 +7,7 @@ tqdm
|Build-Status| |Coverage-Status| |Branch-Coverage-Status| |Codacy-Grade|
-|DOI-URI| |LICENCE|
+|DOI-URI| |LICENCE| |OpenHub-Status|
``tqdm`` means "progress" in Arabic (taqadum, تقدّم)
@@ -43,7 +43,7 @@ It can also be executed as a module with pipes:
Overhead is low -- about 60ns per iteration (80ns with ``tqdm_gui``), and is
unit tested against performance regression.
-By comparison, the well established
+By comparison, the well-established
`ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has
an 800ns/iter overhead.
@@ -51,12 +51,13 @@ 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, Solaris/SunOS),
+``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 library (not even curses!) to run, just a
-vanilla Python interpreter will do and an environment supporting ``carriage
-return \r`` and ``line feed \n`` control characters.
+``tqdm`` does not require any dependencies (not even ``curses``!), just
+Python and an environment supporting ``carriage return \r`` and
+``line feed \n`` control characters.
------------------------------------------
@@ -77,10 +78,10 @@ Latest PyPI stable release
pip install tqdm
-Latest development release on github
+Latest development release on GitHub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-|GitHub-Status| |GitHub-Stars| |GitHub-Forks|
+|GitHub-Status| |GitHub-Stars| |GitHub-Commits| |GitHub-Forks|
Pull and install in the current directory:
@@ -169,7 +170,7 @@ 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 demonstrated counting the number of lines in all python files
+The example below demonstrated counting the number of lines in all Python files
in the current directory, with timing information included.
.. code:: sh
@@ -209,29 +210,32 @@ Backing up a large directory?
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``).
- 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>`__,
+ 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>`__ and
`here <https://github.com/tqdm/tqdm/issues/307>`__)
lack full support.
- * Windows: additionally may require the python module ``colorama``.
+ * Windows: additionally may require the Python module ``colorama``
+ to ensure nested bars stay within their respective lines.
- Wrapping enumerated iterables: use ``enumerate(tqdm(...))`` instead of
- ``tqdm(enumerate(...))`. The same applies to ``numpy.ndenumerate``.
+ ``tqdm(enumerate(...))``. The same applies to ``numpy.ndenumerate``.
This is because enumerate functions tend to hide the length of iterables.
``tqdm`` does not.
- Wrapping zipped iterables has similar issues due to internal optimisations.
``tqdm(zip(a, b))`` should be replaced with ``zip(tqdm(a), b)`` or even
- ``zip(tqdm(a), tqdm(b))``
+ ``zip(tqdm(a), tqdm(b))``.
-If you come across any other difficulties, browse/open issues
-`here <https://github.com/tqdm/tqdm/issues?q=is%3Aissue>`__.
+If you come across any other difficulties, browse and file |GitHub-Issues|.
Documentation
-------------
@@ -248,7 +252,7 @@ Documentation
"""
def __init__(self, iterable=None, desc=None, total=None, leave=True,
- file=sys.stderr, ncols=None, mininterval=0.1,
+ 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,
@@ -274,7 +278,7 @@ Parameters
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()``
+ (default: sys.stderr). Uses ``file.write(str)`` and ``file.flush()``
methods.
* ncols : int, optional
The width of the entire output message. If specified,
@@ -306,11 +310,12 @@ Parameters
* 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
+* 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].
+ (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`` to the environment (allowing
for window resizes) [default: False].
@@ -320,11 +325,15 @@ Parameters
(current/instantaneous speed) [default: 0.3].
* bar_format : str, optional
Specify a custom bar string formatting. May impact performance.
- If unspecified, will use '{l_bar}{bar}{r_bar}', where l_bar is
- '{desc}{percentage:3.0f}%|' and r_bar is
- '| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, {rate_fmt}]'
- Possible vars: bar, n, n_fmt, total, total_fmt, percentage,
- rate, rate_fmt, elapsed, remaining, l_bar, r_bar, desc.
+ [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, rate, rate_fmt, rate_noinv, rate_noinv_fmt,
+ rate_inv, rate_inv_fmt, elapsed, remaining, desc, postfix.
+ Note that a trailing ": " is automatically removed after {desc}
+ if the latter is empty.
* initial : int, optional
The initial counter value. Useful when restarting a progress
bar [default: 0].
@@ -334,6 +343,10 @@ Parameters
Useful to manage multiple bars at once (eg, from threads).
* postfix : dict, optional
Specify additional stats to display at the end of the bar.
+ Note: postfix is a dict ({'key': value} pairs) for this method,
+ not a string.
+* unit_divisor : float, optional
+ [default: 1000], ignored unless `unit_scale` is True.
Extra CLI Options
~~~~~~~~~~~~~~~~~
@@ -370,7 +383,7 @@ Returns
Parameters
----------
- n : int
+ n : int, optional
Increment to add to the internal counter of iterations
[default: 1].
"""
@@ -380,7 +393,12 @@ Returns
Cleanup and (if leave=False) close the progressbar.
"""
- def clear(self):
+ def unpause(self):
+ """
+ Restart tqdm timer from last print time.
+ """
+
+ def clear(self, nomove=False):
"""
Clear current bar display
"""
@@ -395,15 +413,26 @@ Returns
Print a message via tqdm (without overlap with bars)
"""
- def set_description(self, desc=None):
+ 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, **kwargs):
+ def set_postfix(self, ordered_dict=None, refresh=True, **kwargs):
"""
Set/modify postfix (additional stats)
with automatic formatting based on datatype.
+
+ Parameters
+ ----------
+ refresh : bool, optional
+ Forces refresh [default: True].
"""
def trange(*args, **kwargs):
@@ -440,7 +469,9 @@ Examples and Advanced Usage
folder;
- import the module and run ``help()``, or
- 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.
+ - 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.
Description and additional stats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -458,7 +489,7 @@ with the ``desc`` and ``postfix`` arguments:
for i in t:
# Description will be displayed on the left
t.set_description('GEN %i' % i)
- # Postfix will be displayed on the right, and will format automatically
+ # Postfix will be displayed on the right, and will format automatically
# based on argument's datatype
t.set_postfix(loss=random(), gen=randint(1,999), str='h', lst=[1, 2])
sleep(0.1)
@@ -479,11 +510,34 @@ Nested progress bars
sleep(0.01)
On Windows `colorama <https://github.com/tartley/colorama>`__ will be used if
-available to produce a beautiful nested display.
+available to keep nested bars on their respective lines.
For manual control over positioning (e.g. for multi-threaded use),
-you may specify `position=n` where `n=0` for the outermost bar,
-`n=1` for the next, and so on.
+you may specify ``position=n`` where ``n=0`` for the outermost bar,
+``n=1`` for the next, and so on:
+
+.. code:: python
+
+ from time import sleep
+ from tqdm import trange
+ from multiprocessing import Pool, freeze_support, RLock
+
+ L = list(range(9))
+
+ def progresser(n):
+ interval = 0.001 / (n + 2)
+ total = 5000
+ text = "#{}, est. {:<04.2}s".format(n, interval * total)
+ for i in trange(total, desc=text, position=n):
+ sleep(interval)
+
+ if __name__ == '__main__':
+ freeze_support() # for Windows support
+ p = Pool(len(L),
+ # again, for Windows support
+ initializer=tqdm.set_lock, initargs=(RLock(),))
+ p.map(progresser, L)
+ print("\n" * (len(L) - 2))
... 4001 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/tqdm.git
More information about the Python-modules-commits
mailing list