From 6346b8f5eb07f3a276acc9f097d1806ade0b4044 Mon Sep 17 00:00:00 2001 From: Hadrien Mary Date: Sun, 11 Oct 2015 19:01:12 +0200 Subject: [PATCH 1/6] Add small test for version variable --- tqdm/tests/tests_version.py | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 tqdm/tests/tests_version.py diff --git a/tqdm/tests/tests_version.py b/tqdm/tests/tests_version.py new file mode 100644 index 00000000..8cd6e76c --- /dev/null +++ b/tqdm/tests/tests_version.py @@ -0,0 +1,3 @@ +def test_version(): + from tqdm import __version__ + assert len(__version__.split('.')) == 4 From 5428709d9f51a142ebf6a591932749a061d0606b Mon Sep 17 00:00:00 2001 From: Stephen L Date: Sun, 11 Oct 2015 19:11:45 +0200 Subject: [PATCH 2/6] README in reStructuredText Signed-off-by: Stephen L. --- README.rst | 226 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..b310b203 --- /dev/null +++ b/README.rst @@ -0,0 +1,226 @@ +|Logo| + +tqdm +==== + +| |Build Status| +| |Coverage Status| + +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! + +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 `__ has +an 800ns/iter overhead. It's a matter of taste, but we also like to think our +version is much more visually appealing. + +Installation +------------ + +.. code:: sh + + # Latest stable release on pypi + pip install tqdm + # Latest development release on github + pip install -e git+https://github.com/tqdm/tqdm.git@master#egg=tqdm + +Documentation +------------- + +.. code:: python + + class tqdm: + """ + 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): + """ + 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 + [default: None]. 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 (▏▎▋█ █) 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]. + + 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 also the CONTRIBUTE file for more information. + +License +------- + +`MIT LICENSE `__. + +Authors +------- + +- Noam Yorav-Raphael (noamraph, Original Author) +- Ivan Ivanov (obiwanus) +- Mikhail Korobov (kmike) +- Hadrien Mary (hadim) +- Casper da Costa-Luis (casperdcl) +- Stephen Larroque (lrq3000) + +.. |Logo| image:: 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 +.. |Screenshot| image:: tqdm.gif From 22474d1152388c1357d14c3dac5663e5b6ec2149 Mon Sep 17 00:00:00 2001 From: Hadrien Mary Date: Sun, 11 Oct 2015 19:01:12 +0200 Subject: [PATCH 3/6] Add small test for version variable --- tqdm/__init__.py | 6 +++--- tqdm/tests/tests_version.py | 3 +++ 2 files changed, 6 insertions(+), 3 deletions(-) create mode 100644 tqdm/tests/tests_version.py diff --git a/tqdm/__init__.py b/tqdm/__init__.py index 6264e6ef..d7487066 100644 --- a/tqdm/__init__.py +++ b/tqdm/__init__.py @@ -2,7 +2,7 @@ from ._tqdm import tqdm from ._tqdm import trange from ._tqdm import format_interval from ._tqdm import format_meter - -__all__ = ['tqdm', 'trange', 'format_interval', 'format_meter'] - from ._version import __version__ + +__all__ = ['tqdm', 'trange', 'format_interval', 'format_meter', '__version__'] + diff --git a/tqdm/tests/tests_version.py b/tqdm/tests/tests_version.py new file mode 100644 index 00000000..8cd6e76c --- /dev/null +++ b/tqdm/tests/tests_version.py @@ -0,0 +1,3 @@ +def test_version(): + from tqdm import __version__ + assert len(__version__.split('.')) == 4 From 6844fdf7ad7e3790f24a5dae2ec8bd0ac154f77c Mon Sep 17 00:00:00 2001 From: Stephen L Date: Sun, 11 Oct 2015 19:18:30 +0200 Subject: [PATCH 4/6] Update README.rst Signed-off-by: Stephen L. --- README.rst | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index b310b203..258a8ab3 100644 --- a/README.rst +++ b/README.rst @@ -11,6 +11,12 @@ 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(16)): + ... + Here's what the output looks like: 76%\|████████████████████\ ````` ````` \| 7641/10000 [00:34<00:10, @@ -29,11 +35,19 @@ version is much more visually appealing. Installation ------------ +Latest pypi stable release +~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code:: sh - # Latest stable release on pypi pip install tqdm - # Latest development release on github + +Latest development release on github +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Pull and install in the current directory: + +:: pip install -e git+https://github.com/tqdm/tqdm.git@master#egg=tqdm Documentation @@ -201,7 +215,7 @@ with the following command: $ make test $ make coverage -See also the CONTRIBUTE file for more information. +See the `CONTRIBUTE `__ file for more information. License ------- From 22338ad750ef181e99fceb6f8f5256a5a5af1918 Mon Sep 17 00:00:00 2001 From: Stephen L Date: Sun, 11 Oct 2015 19:19:55 +0200 Subject: [PATCH 5/6] Fix grey bars in README.rst Signed-off-by: Stephen L. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 258a8ab3..b1f26bcc 100644 --- a/README.rst +++ b/README.rst @@ -19,7 +19,7 @@ iterable with "tqdm(iterable)", and you're done! Here's what the output looks like: -76%\|████████████████████\ ````` ````` \| 7641/10000 [00:34<00:10, +76%\|████████████████████\ ```` ```` \| 7641/10000 [00:34<00:10, 222.22 it/s] You can also use ``trange(N)`` as a shortcut for ``tqdm(xrange(N))`` From c7c89bd78483d89ef0f395b12c3b2c7cc5bcc80b Mon Sep 17 00:00:00 2001 From: Stephen L Date: Sun, 11 Oct 2015 19:22:09 +0200 Subject: [PATCH 6/6] Revert grey bars in README.rst Signed-off-by: Stephen L. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index b1f26bcc..258a8ab3 100644 --- a/README.rst +++ b/README.rst @@ -19,7 +19,7 @@ iterable with "tqdm(iterable)", and you're done! Here's what the output looks like: -76%\|████████████████████\ ```` ```` \| 7641/10000 [00:34<00:10, +76%\|████████████████████\ ````` ````` \| 7641/10000 [00:34<00:10, 222.22 it/s] You can also use ``trange(N)`` as a shortcut for ``tqdm(xrange(N))``