[Python-modules-commits] [tqdm] 01/05: Import tqdm_4.7.4.orig.tar.gz
Sandro Tosi
morph at moszumanska.debian.org
Sat Jun 11 18:20:18 UTC 2016
This is an automated email from the git hooks/post-receive script.
morph pushed a commit to branch master
in repository tqdm.
commit c9de85067edc847320f9b01a010b7fb2d77fdf16
Author: Sandro Tosi <morph at debian.org>
Date: Sat Jun 11 18:56:53 2016 +0100
Import tqdm_4.7.4.orig.tar.gz
---
CONTRIBUTE | 250 ++++++++++++++++++++++++-----
LICENCE | 43 +++++
MANIFEST.in | 2 +-
Makefile | 3 +
PKG-INFO | 297 ++++++++++++++++++++++++++++-------
README.rst | 292 +++++++++++++++++++++++++++-------
RELEASE | 84 ----------
examples/pandas_progress_apply.py | 14 +-
examples/progressbar/__init__.pyc | Bin 1290 -> 1282 bytes
examples/progressbar/compat.pyc | Bin 791 -> 767 bytes
examples/progressbar/progressbar.pyc | Bin 10014 -> 9870 bytes
examples/progressbar/widgets.pyc | Bin 15096 -> 14752 bytes
setup.py | 3 +-
tox.ini | 2 -
tqdm.egg-info/PKG-INFO | 297 ++++++++++++++++++++++++++++-------
tqdm.egg-info/SOURCES.txt | 3 +-
tqdm/__init__.py | 20 ++-
tqdm/_main.py | 154 ++++++++++++++----
tqdm/_tqdm.py | 145 ++++++++++++-----
tqdm/_tqdm_gui.py | 15 +-
tqdm/_tqdm_notebook.py | 232 +++++++++++++++++++++++++++
tqdm/_tqdm_pandas.py | 20 ++-
tqdm/_utils.py | 22 ++-
tqdm/_version.py | 11 +-
tqdm/tests/tests_main.py | 65 ++++++--
tqdm/tests/tests_pandas.py | 25 ++-
tqdm/tests/tests_perf.py | 54 ++++---
tqdm/tests/tests_tqdm.py | 203 +++++++++++++++++++++++-
28 files changed, 1821 insertions(+), 435 deletions(-)
diff --git a/CONTRIBUTE b/CONTRIBUTE
index 76f61e6..5973a19 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -1,31 +1,35 @@
HOW TO CONTRIBUTE TO TQDM
=========================
-This file describes how to contribute changes to the project, and how to
-upload to the pypi repository.
+This file describes how to
+
+- contribute changes to the project, and
+- upload released to the pypi repository.
Most of the management commands have been directly placed inside the
-Makefile: `python setup.py make [alias]`, (or simply `make [alias]` in
-UNIX-like environments).
+Makefile:
+
+```
+make [<alias>] # on UNIX-like environments
+python setup.py make [<alias>] # if make is unavailable
+```
-Note: to use the Makefile on Windows, you need to install make.exe,
-for example by installing [MinGW MSYS](http://www.mingw.org/wiki/msys).
+Use the alias `help` (or leave blank) to list all available aliases.
-HOW TO COMMIT YOUR CONTRIBUTIONS
---------------------------------
+HOW TO COMMIT CONTRIBUTIONS
+---------------------------
Contributions to the project are made using the "Fork & Pull" model. The
typical steps would be:
-- create an account on [github](https://github.com)
-- fork [tqdm](https://github.com/tqdm/tqdm)
-- make a local clone: `git clone https://github.com/your_account/tqdm.git`
-- make your changes on your local copy
-- commit your changes `git commit -a -m "my message"`
-- TEST YOUR CHANGES (see below)
-- `push` to your github account: `git push origin`
-- finally, create a Pull Request (PR) from your github fork
+1. create an account on [github](https://github.com)
+2. fork [tqdm](https://github.com/tqdm/tqdm)
+3. make a local clone: `git clone https://github.com/your_account/tqdm.git`
+4. make changes on the local copy
+5. test (see below) and commit changes `git commit -a -m "my message"`
+6. `push` to your github account: `git push origin`
+7. create a Pull Request (PR) from your github fork
(go to your fork's webpage and click on "Pull Request."
You can then add a message to describe your proposal.)
@@ -33,12 +37,11 @@ You can then add a message to describe your proposal.)
TESTING
-------
-To test functionality on your machine (such as before submitting a Pull
+To test functionality (such as before submitting a Pull
Request), there are a number of unit tests.
-
-Standard unit testing
-~~~~~~~~~~~~~~~~~~~~~
+Standard unit tests
+~~~~~~~~~~~~~~~~~~~
The standard way to run the tests:
@@ -47,18 +50,8 @@ The standard way to run the tests:
- run the following command:
```
-python setup.py make test
-```
-
-or
-
-```
-make test
-```
-
-or
-
-```
+[python setup.py] make test
+# or:
tox --skip-missing-interpreters
```
@@ -73,22 +66,201 @@ you can use `MiniConda` to install a minimal setup. You must also make sure
that each distribution has an alias to call the Python interpreter:
`python27` for Python 2.7's interpreter, `python32` for Python 3.2's, etc.
-
-Alternative unit testing with Nose
+Alternative unit tests with Nose
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Alternatively, use `nose` to run the tests just for your Python version:
+Alternatively, use `nose` to run the tests just for the current Python version:
- install `nose` and `flake8`
- run the following command:
```
-python setup.py make alltests
+[python setup.py] make alltests
```
-or
+
+
+MANAGE A NEW RELEASE
+=====================
+
+This section is intended for the project's maintainers and describes
+how to build and upload a new release. Once again,
+`[python setup.py] make [<alias>]` will help.
+
+
+SEMANTIC VERSIONING
+-------------------
+
+The tqdm repository managers should:
+
+- regularly bump the version number in the file
+[_version.py](https://raw.githubusercontent.com/tqdm/tqdm/master/tqdm/_version.py)
+- follow the [Semantic Versioning](http://semver.org/) convention
+- take care of this (instead of users) to avoid PR conflicts
+solely due to the version file bumping
+
+Note: tools can be used to automate this process, such as
+[bumpversion](https://github.com/peritus/bumpversion) or
+[python-semanticversion](https://github.com/rbarrois/python-semanticversion/).
+
+
+CHECKING SETUP.PY
+-----------------
+
+To check that the `setup.py` file is compliant with PyPi requirements (e.g.
+version number; reStructuredText in README.rst) use:
+
+```
+[python setup.py] make testsetup
+```
+
+To upload just metadata (including overwriting mistakenly uploaded metadata)
+to PyPi, use:
+
+```
+[python setup.py] make pypimeta
+```
+
+
+MERGING PULL REQUESTS
+---------------------
+
+This section describes how to cleanly merge PRs.
+
+1 Rebase
+~~~~~~~~
+
+From your project repository, merge and test
+(replace `pr-branch-name` as appropriate):
```
-nosetests --with-coverage --cover-package=tqdm -v tqdm/
-python -m flake8 tqdm/_tqdm.py
+git fetch origin
+git checkout -b pr-branch-name origin/pr-branch-name
+git rebase master
+```
+
+If there are conflicts:
+
+```
+git mergetool
+git rebase --continue
+```
+
+2 Push
+~~~~~~
+
+Update branch with the rebased history:
+
```
+git push origin pr-branch-name --force
+```
+
+Non maintainers can stop here.
+
+Note: NEVER just `git push --force` (this will push all local branches,
+overwriting remotes).
+
+3 Merge
+~~~~~~~
+
+```
+git checkout master
+git merge --no-ff pr-branch-name
+```
+
+4 Test
+~~~~~~
+
+```
+[python setup.py] make alltests
+```
+
+5 Version
+~~~~~~~~~
+
+Modify tqdm/_version.py and ammend the last (merge) commit:
+
+```
+git add tqdm/_version.py
+git commit --amend # Add "+ bump version" in the commit message
+```
+
+6 Push to master
+~~~~~~~~~~~~~~~~
+
+```
+git push origin master
+```
+
+
+BUILDING A RELEASE AND UPLOADING TO PYPI
+----------------------------------------
+
+Formally publishing requires additional steps: testing and tagging.
+
+Test
+~~~~
+
+- ensure that all online CI tests have passed
+- check `setup.py` and `MANIFEST.in` - which define the packaging
+process and info that will be uploaded to [pypi](pypi.python.org) -
+using `[python setup.py] make installdev`
+
+Tag
+~~~
+
+- ensure the version has been bumped, committed **and** tagged.
+The tag format is `v{major}.{minor}.{patch}`, for example: `v4.4.1`.
+The current commit's tag is used in the version checking process.
+If the current commit is not tagged appropriately, the version will
+display as `v{major}.{minor}.{patch}-{commit_hash}`.
+
+Upload
+~~~~~~
+
+Build tqdm into a distributable python package:
+
+```
+[python setup.py] make build
+```
+
+This will generate several builds in the `dist/` folder. On non-windows
+machines the windows `exe` installer may fail to build. This is normal.
+
+Finally, upload everything to pypi. This can be done easily using the
+[twine](https://github.com/pypa/twine) module:
+
+```
+[python setup.py] make pypi
+```
+
+Also, the new release can (should) be added to `github` by creating a new
+release from the web interface; uploading packages from the `dist/` folder
+created by `[python setup.py] make build`.
+
+Notes
+~~~~~
+
+- you can also test on the pypi test servers `testpypi.python.org/pypi`
+before the real deployment
+- in case of a mistake, you can delete an uploaded release on pypi, but you
+cannot re-upload another with the same version number
+- in case of a mistake in the metadata on pypi (e.g. bad README),
+updating just the metadata is possible: `[python setup.py] make pypimeta`
+
+
+QUICK DEV SUMMARY
+-----------------
+
+For expereinced devs, once happy with local master:
+
+1. bump version in `tqdm/_version.py`
+2. test (`[python setup.py] make alltests`)
+3. `git commit [--amend] # -m "bump version"`
+4. `git push`
+5. wait for tests to pass
+ a) in case of failure, fix and go back to (2)
+6. `git tag vM.m.p && git push --tags`
+7. `[python setup.py] make distclean`
+8. `[python setup.py] make build`
+9. `[python setup.py] make pypi`
diff --git a/LICENCE b/LICENCE
new file mode 100644
index 0000000..b0b4be5
--- /dev/null
+++ b/LICENCE
@@ -0,0 +1,43 @@
+`tqdm` is a product of collaborative work.
+Unless otherwise stated, all authors (see commit logs) retain copyright
+for their respective work, and release the work under the MIT licence
+(text below).
+
+Exceptions or notable authors are listed below
+in reverse chronological order:
+
+* MPLv2.0 (text below) 2015-2016 (c) Casper da Costa-Luis
+ [casperdcl](https://github.com/casperdcl).
+* MIT 2016 (c) [PR #96] on behalf of Google Inc.
+
+ [PR #96]: https://github.com/tqdm/tqdm/pull/96
+
+
+Mozilla Public Licence (MPL) v. 2.0 - Exhibit A
+-----------------------------------------------
+
+This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+
+MIT License (MIT)
+-----------------
+
+Copyright (c) 2013 noamraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/MANIFEST.in b/MANIFEST.in
index 983da59..b2d0577 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,7 +1,7 @@
# Misc
include .coveragerc
include CONTRIBUTE
-include LICENSE
+include LICENCE
include logo.png
include Makefile
include README.rst
diff --git a/Makefile b/Makefile
index ce0c711..6688e77 100644
--- a/Makefile
+++ b/Makefile
@@ -34,6 +34,9 @@
pypi
none
+help:
+ @python setup.py make
+
alltests:
@+make testcoverage
@+make testperf
diff --git a/PKG-INFO b/PKG-INFO
index 6c8046a..12f39a5 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,18 +1,22 @@
Metadata-Version: 1.1
Name: tqdm
-Version: 4.4.1
+Version: 4.7.4
Summary: A Fast, Extensible Progress Meter
Home-page: https://github.com/tqdm/tqdm
Author: tqdm developers
Author-email: python.tqdm at gmail.com
-License: MIT License
+License: MPLv2.0, MIT Licenses
Description: |Logo|
tqdm
====
- |PyPi Status| |PyPi Downloads|
- |Build Status| |Coverage Status| |Branch Coverage Status|
+ |PyPi-Status| |PyPi-Versions|
+
+ |Build-Status| |Coverage-Status| |Branch-Coverage-Status|
+
+ |DOI-URI| |Licence|
+
``tqdm`` (read taqadum, تقدّم) means "progress" in arabic.
@@ -39,11 +43,11 @@ Description: |Logo|
.. code:: sh
- $ seq 9999999 | tqdm --unit_scale True | wc -l
+ $ seq 9999999 | tqdm --unit_scale | wc -l
10.0Mit [00:02, 3.58Mit/s]
9999999
- Overhead is low -- about 60ns per iteration (80ns with ``gui=True``), and is
+ Overhead is low -- about 60ns per iteration (80ns with ``tqdm_gui``), and is
unit tested against performance regression.
By comparison, the well established
`ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has
@@ -73,6 +77,8 @@ Description: |Logo|
Latest pypi stable release
~~~~~~~~~~~~~~~~~~~~~~~~~~
+ |PyPi-Status|
+
.. code:: sh
pip install tqdm
@@ -80,6 +86,8 @@ Description: |Logo|
Latest development release on github
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ |Github-Status| |Github-Stars| |Github-Forks|
+
Pull and install in the current directory:
.. code:: sh
@@ -90,9 +98,8 @@ Description: |Logo|
Changelog
---------
- The list of all changes is available either on
- `Github's Releases <https://github.com/tqdm/tqdm/releases>`_
- or on crawlers such as
+ The list of all changes is available either on Github's Releases:
+ |Github-Status| or on crawlers such as
`allmychanges.com <https://allmychanges.com/p/python/tqdm/>`_.
@@ -152,7 +159,6 @@ Description: |Logo|
pbar.update(10)
pbar.close()
-
Module
~~~~~~
@@ -185,13 +191,23 @@ Description: |Logo|
.. code:: sh
$ find . -name '*.py' -exec cat \{} \; |
- tqdm --unit loc --unit_scale True --total 857366 >> /dev/null
+ tqdm --unit loc --unit_scale --total 857366 >> /dev/null
100%|███████████████████████████████████| 857K/857K [00:04<00:00, 246Kloc/s]
+ Backing up a large directory?
+
+ .. code:: sh
+
+ $ 7z a -bd -r backup.7z docs/ | grep Compressing |
+ tqdm --total $(find docs/ -type f | wc -l) --unit files >> backup.log
+ 100%|███████████████████████████████▉| 8014/8014 [01:37<00:00, 82.29files/s]
+
Documentation
-------------
+ |PyPi-Versions| |Readme-Hits| (Since 19 May 2016)
+
.. code:: python
class tqdm(object):
@@ -212,15 +228,16 @@ Description: |Logo|
* iterable : iterable, optional
Iterable to decorate with a progressbar.
- Leave blank [default: None] to manually manage the updates.
+ Leave blank to manually manage the updates.
* desc : str, optional
- Prefix for the progressbar [default: None].
+ Prefix for the progressbar.
* total : int, optional
- The number of expected iterations. If [default: None], 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).
+ The number of expected iterations. If (default: None),
+ 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: True], keeps all traces of the progressbar
upon termination of iteration.
@@ -231,7 +248,7 @@ Description: |Logo|
* 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
+ If unspecified, 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
@@ -239,12 +256,12 @@ Description: |Logo|
* maxinterval : float, optional
Maximum progress update interval, in seconds [default: 10.0].
* miniters : int, optional
- Minimum progress update interval, in iterations [default: None].
+ Minimum progress update interval, in iterations.
If specified, will set `mininterval` to 0.
* ascii : bool, optional
- If [default: None] or False, use unicode (smooth blocks) to fill
+ If unspecified or False, use unicode (smooth blocks) to fill
the meter. The fallback is to use ASCII characters `1-9 #`.
- * disable : bool
+ * disable : bool, optional
Whether to disable the entire progressbar wrapper
[default: False].
* unit : str, optional
@@ -258,15 +275,15 @@ Description: |Logo|
* dynamic_ncols : bool, optional
If set, constantly alters `ncols` to the environment (allowing
for window resizes) [default: False].
- * smoothing : float
+ * smoothing : float, optional
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].
* bar_format : str, optional
Specify a custom bar string formatting. May impact performance.
- If [default: None], will use '{l_bar}{bar}{r_bar}', where l_bar is
+ 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_str}<{remaining_str}, {rate_fmt}]'.
+ '| {n_fmt}/{total_fmt} [{elapsed_str}<{remaining_str}, {rate_fmt}]'
Possible vars: bar, n, n_fmt, total, total_fmt, percentage,
rate, rate_fmt, elapsed, remaining, l_bar, r_bar, desc.
* initial : int, optional
@@ -274,9 +291,19 @@ Description: |Logo|
bar [default: 0].
* position : int, optional
Specify the line offset to print this bar (starting from 0)
- Automatic if [default: None].
+ Automatic if unspecified.
Useful to manage multiple bars at once (eg, from threads).
+ Extra CLI Options
+ ~~~~~~~~~~~~~~~~~
+
+ * delim : chr, optional
+ Delimiting character [default: '\n']. Use '\0' for null.
+ N.B.: on Windows systems, Python converts '\n' to '\r\n'.
+ * buf_size : int, optional
+ String buffer size in bytes [default: 256]
+ used when `delim` is specified.
+
Returns
~~~~~~~
@@ -310,6 +337,21 @@ Description: |Logo|
Cleanup and (if leave=False) close the progressbar.
"""
+ def clear(self):
+ """
+ Clear current bar display
+ """
+
+ def refresh(self):
+ """
+ Force refresh the display of this bar
+ """
+
+ def write(cls, s, file=sys.stdout, end="\n"):
+ """
+ Print a message via tqdm (without overlap with bars)
+ """
+
def trange(*args, **kwargs):
"""
A shortcut for tqdm(xrange(*args), **kwargs).
@@ -326,6 +368,16 @@ Description: |Logo|
Experimental GUI version of trange!
"""
+ class tqdm_notebook(tqdm):
+ """
+ Experimental IPython/Jupyter Notebook widget using tqdm!
+ """
+
+ def tnrange(*args, **kwargs):
+ """
+ Experimental IPython/Jupyter Notebook widget using tqdm!
+ """
+
Examples and Advanced Usage
---------------------------
@@ -333,6 +385,28 @@ Description: |Logo|
See the `examples <https://github.com/tqdm/tqdm/tree/master/examples>`__
folder or import the module and run ``help()``.
+ Nested progress bars
+ ~~~~~~~~~~~~~~~~~~~~
+
+ ``tqdm`` supports nested progress bars. Here's an example:
+
+ .. code:: python
+
+ from tqdm import trange
+ from time import sleep
+
+ for i in trange(10, desc='1st loop'):
+ for j in trange(5, desc='2nd loop', leave=False):
+ for k in trange(100, desc='3nd loop'):
+ sleep(0.01)
+
+ On Windows `colorama <https://github.com/tartley/colorama>`__ will be used if
+ available to produce a beautiful nested display.
+
+ 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.
+
Hooks and callbacks
~~~~~~~~~~~~~~~~~~~
@@ -387,7 +461,7 @@ Description: |Logo|
return inner
eg_link = 'http://www.doc.ic.ac.uk/~cod11/matryoshka.zip'
- with tqdm(unit='B', unit_scale=True, leave=True, miniters=1,
+ 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)
@@ -400,7 +474,7 @@ Description: |Logo|
~~~~~~~~~~~~~~~~~~
Due to popular demand we've added support for ``pandas`` -- here's an example
- for ``DataFrameGroupBy.progress_apply``:
+ for ``DataFrame.progress_apply`` and ``DataFrameGroupBy.progress_apply``:
.. code:: python
@@ -408,6 +482,8 @@ Description: |Logo|
import numpy as np
from tqdm import tqdm, tqdm_pandas
+ ...
+
df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))
# Create and register a new `tqdm` instance with `pandas`
@@ -415,35 +491,123 @@ Description: |Logo|
tqdm_pandas(tqdm())
# Now you can use `progress_apply` instead of `apply`
- df.groupby(0).progress_apply(lambda x: x**2)
+ df.progress_apply(lambda x: x**2)
+ # can also groupby:
+ # df.groupby(0).progress_apply(lambda x: x**2)
In case you're interested in how this works (and how to modify it for your
own callbacks), see the
`examples <https://github.com/tqdm/tqdm/tree/master/examples>`__
folder or import the module and run ``help()``.
- Nested progress bars
- ~~~~~~~~~~~~~~~~~~~~
+ IPython/Jupyter Integration
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- ``tqdm`` supports nested progress bars. Here's an example:
+ IPython/Jupyter is supported via the `tqdm_notebook` submodule:
.. code:: python
- from tqdm import trange
+ from tqdm import tnrange, tqdm_notebook
from time import sleep
- for i in trange(10, desc='1st loop'):
- for j in trange(5, desc='2nd loop', leave=False):
- for k in trange(100, desc='3nd loop'):
- sleep(0.01)
+ for i in tnrange(10, desc='1st loop'):
+ for j in tqdm_notebook(xrange(100), desc='2nd loop'):
+ sleep(0.01)
- On Windows `colorama <https://github.com/tartley/colorama>`__ will be used if
- available to produce a beautiful nested display.
+ 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.
- 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.
+ |Screenshot-Jupyter1|
+ |Screenshot-Jupyter2|
+ |Screenshot-Jupyter3|
+
+ Writing messages
+ ~~~~~~~~~~~~~~~~
+
+ Since ``tqdm`` uses a simple printing mechanism to display progress bars,
+ you should not write any message in the terminal using ``print()``.
+ To write messages in the terminal without any collision with ``tqdm`` bar
+ display, a ``.write()`` method is provided:
+
+ .. code:: python
+
+ from tqdm import tqdm, trange
+ from time import sleep
+
+ bar = trange(10)
+ for i in bar:
+ # Print using tqdm class method .write()
+ sleep(0.1)
+ if not (i % 3):
+ tqdm.write("Done task %i" % i)
+ # Can also use bar.write()
+
+ By default, this will print to standard output ``sys.stdout``. but you can
+ specify any file-like object using the ``file`` argument. For example, this
+ can be used to redirect the messages writing to a log file or class.
+
+ Redirecting writing
+ ~~~~~~~~~~~~~~~~~~~
+
+ If using a library that can print messages to the console, editing the library
+ by replacing ``print()`` with ``tqdm.write()`` may not be desirable.
+ In that case, redirecting ``sys.stdout`` to ``tqdm.write()`` is an option.
+
+ To redirect ``sys.stdout``, create a file-like class that will write
+ any input string to ``tqdm.write()``, and supply the arguments
+ ``file=sys.stdout, dynamic_ncols=True``.
+
+ A reusable canonical example is given below:
+
+ .. code:: python
+
+ from time import sleep
+
+ import contextlib
+ import sys
+
+ from tqdm import tqdm
+
+ class DummyTqdmFile(object):
+ """Dummy file-like that will write to tqdm"""
+ file = None
+ def __init__(self, file):
+ self.file = file
+
+ def write(self, x):
+ # Avoid print() second call (useless \n)
+ if len(x.rstrip()) > 0:
+ tqdm.write(x, file=self.file)
+
+ @contextlib.contextmanager
+ def stdout_redirect_to_tqdm():
+ save_stdout = sys.stdout
+ try:
+ sys.stdout = DummyTqdmFile(sys.stdout)
+ yield save_stdout
+ # Relay exceptions
+ except Exception as exc:
+ raise exc
+ # Always restore sys.stdout if necessary
+ finally:
+ sys.stdout = save_stdout
+
+ def blabla():
+ print("Foo blabla")
+
+ # 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)
+ # and dynamic_ncols=True to autodetect console width
+ for _ in tqdm(range(3), file=save_stdout, dynamic_ncols=True):
+ blabla()
+ sleep(.5)
+
+ # After the `with`, printing is restored
+ print('Done!')
How to make a good progress bar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -496,7 +660,7 @@ Description: |Logo|
.. code:: python
def process_content_with_progress1(inputpath, blocksize=1024):
- for filepath in tqdm(walkdir(inputpath), leave=True):
+ for filepath in tqdm(walkdir(inputpath)):
with open(filepath, 'rb') as fh:
buf = 1
while (buf):
@@ -523,7 +687,7 @@ Description: |Logo|
for filename in files:
filecounter += 1
- for filepath in tqdm(walkdir(inputpath), total=filecounter, leave=True):
+ for filepath in tqdm(walkdir(inputpath), total=filecounter):
with open(filepath, 'rb') as fh:
buf = 1
while (buf):
@@ -533,7 +697,7 @@ Description: |Logo|
``process_content_with_progress2()`` is better than the naive approach because
now we have predictive information:
- 50%|██████████████████████\ \| 2/4 [00:00<00:00, 4.06it/s]
+ 50%|████████████\ \| 2/4 [00:00<00:00, 4.06it/s]
However, the progress is not smooth: it increments in steps, 1 step being
1 file processed. The problem is that we do not just walk through files tree,
@@ -561,7 +725,7 @@ Description: |Logo|
sizecounter += os.stat(fullpath).st_size
# Load tqdm with size counter instead of files counter
- with tqdm(total=sizecounter, leave=True, unit='B', unit_scale=True) as pbar:
+ with tqdm(total=sizecounter, unit='B', unit_scale=True) as pbar:
for dirpath, dirs, files in os.walk(inputpath):
for filename in files:
fullpath = os.path.abspath(os.path.join(dirpath, filename))
@@ -575,7 +739,7 @@ Description: |Logo|
And here is the result: a much smoother progress bar with meaningful
predicted time and statistics:
- 47%|██████████████████▍\ \| 152K/321K [00:03<00:03, 46.2KB/s]
+ 47%|████████████\ \| 152K/321K [00:03<00:03, 46.2KB/s]
Contributions
@@ -602,15 +766,19 @@ Description: |Logo|
file for more information.
- License
+ Licence
-------
- Multiple licences, mostly `MPLv2.0, MIT licences <https://raw.githubusercontent.com/tqdm/tqdm/master/LICENCE>`__.
+ Open Source (OSI approved): |Licence|
+
+ Citation information: |DOI-URI|
Authors
-------
+ Ranked by contributions.
+
- Casper da Costa-Luis (casperdcl)
- Stephen Larroque (lrq3000)
- Hadrien Mary (hadim)
@@ -620,22 +788,41 @@ Description: |Logo|
`*` Original author
+ |Readme-Hits| (Since 19 May 2016)
+
.. |Logo| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/logo.png
- .. |Build Status| image:: https://travis-ci.org/tqdm/tqdm.svg?branch=master
+ .. |Screenshot| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/images/tqdm.gif
+ .. |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
+ .. |Coverage-Status| image:: https://coveralls.io/repos/tqdm/tqdm/badge.svg
:target: https://coveralls.io/r/tqdm/tqdm
- .. |Branch Coverage Status| image:: https://codecov.io/github/tqdm/tqdm/coverage.svg?branch=master
+ .. |Branch-Coverage-Status| image:: https://codecov.io/github/tqdm/tqdm/coverage.svg?branch=master
:target: https://codecov.io/github/tqdm/tqdm?branch=master
- .. |PyPi Status| image:: https://img.shields.io/pypi/v/tqdm.svg
+ .. |Github-Status| image:: https://img.shields.io/github/tag/tqdm/tqdm.svg?maxAge=2592000
+ :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
+ .. |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
- .. |PyPi Downloads| image:: https://img.shields.io/pypi/dm/tqdm.svg
+ .. |PyPi-Versions| image:: https://img.shields.io/pypi/pyversions/tqdm.svg
:target: https://pypi.python.org/pypi/tqdm
- .. |Screenshot| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/tqdm.gif
+ .. |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
+ :target: https://zenodo.org/badge/latestdoi/21637/tqdm/tqdm
+ .. |Screenshot-Jupyter1| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/images/tqdm-jupyter-1.gif
+ .. |Screenshot-Jupyter2| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/images/tqdm-jupyter-2.gif
+ .. |Screenshot-Jupyter3| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/images/tqdm-jupyter-3.gif
+ .. |Readme-Hits| image:: http://hitt.herokuapp.com/tqdm/tqdm.svg
Keywords: progressbar progressmeter progress bar meter rate eta console terminal time
Platform: any
Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Framework :: IPython
diff --git a/README.rst b/README.rst
index 4c27786..cdfb6b7 100644
--- a/README.rst
+++ b/README.rst
@@ -3,8 +3,12 @@
tqdm
====
-|PyPi Status| |PyPi Downloads|
-|Build Status| |Coverage Status| |Branch Coverage Status|
+|PyPi-Status| |PyPi-Versions|
+
+|Build-Status| |Coverage-Status| |Branch-Coverage-Status|
+
+|DOI-URI| |Licence|
+
``tqdm`` (read taqadum, تقدّم) means "progress" in arabic.
@@ -31,11 +35,11 @@ It can also be executed as a module with pipes:
.. code:: sh
- $ seq 9999999 | tqdm --unit_scale True | wc -l
+ $ seq 9999999 | tqdm --unit_scale | wc -l
10.0Mit [00:02, 3.58Mit/s]
9999999
-Overhead is low -- about 60ns per iteration (80ns with ``gui=True``), and is
+Overhead is low -- about 60ns per iteration (80ns with ``tqdm_gui``), and is
unit tested against performance regression.
By comparison, the well established
`ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has
@@ -65,6 +69,8 @@ Installation
Latest pypi stable release
~~~~~~~~~~~~~~~~~~~~~~~~~~
+|PyPi-Status|
+
.. code:: sh
... 2661 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