[Python-modules-commits] [tqdm] 01/03: import tqdm_4.4.1.orig.tar.gz
Sandro Tosi
morph at moszumanska.debian.org
Sun Apr 24 20:34:55 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 b2b60face6e630f5cddf3064f9edb033bd2bc1eb
Author: Sandro Tosi <morph at debian.org>
Date: Sun Apr 24 21:33:06 2016 +0100
import tqdm_4.4.1.orig.tar.gz
---
.coveragerc | 5 +
CONTRIBUTE | 94 ++++
MANIFEST.in | 16 +
Makefile | 113 ++++
PKG-INFO | 666 ++++++++++++++++++++++
README.rst | 626 +++++++++++++++++++++
RELEASE | 84 +++
examples/include_no_requirements.py | 8 +
examples/pandas_progress_apply.py | 26 +
examples/progressbar/__init__.py | 49 ++
examples/progressbar/__init__.pyc | Bin 0 -> 1290 bytes
examples/progressbar/compat.py | 45 ++
examples/progressbar/compat.pyc | Bin 0 -> 791 bytes
examples/progressbar/progressbar.py | 306 ++++++++++
examples/progressbar/progressbar.pyc | Bin 0 -> 10014 bytes
examples/progressbar/widgets.py | 356 ++++++++++++
examples/progressbar/widgets.pyc | Bin 0 -> 15096 bytes
examples/simple_examples.py | 35 ++
examples/tqdm_wget.py | 65 +++
logo.png | Bin 0 -> 4982 bytes
setup.cfg | 8 +
setup.py | 217 +++++++
tox.ini | 43 ++
tqdm.egg-info/PKG-INFO | 666 ++++++++++++++++++++++
tqdm.egg-info/SOURCES.txt | 40 ++
tqdm.egg-info/dependency_links.txt | 1 +
tqdm.egg-info/entry_points.txt | 3 +
tqdm.egg-info/top_level.txt | 1 +
tqdm/__init__.py | 10 +
tqdm/__main__.py | 2 +
tqdm/_main.py | 56 ++
tqdm/_tqdm.py | 766 +++++++++++++++++++++++++
tqdm/_tqdm_gui.py | 351 ++++++++++++
tqdm/_tqdm_pandas.py | 58 ++
tqdm/_utils.py | 140 +++++
tqdm/_version.py | 31 +
tqdm/tests/tests_main.py | 52 ++
tqdm/tests/tests_pandas.py | 54 ++
tqdm/tests/tests_perf.py | 325 +++++++++++
tqdm/tests/tests_tqdm.py | 1031 ++++++++++++++++++++++++++++++++++
tqdm/tests/tests_version.py | 12 +
41 files changed, 6361 insertions(+)
diff --git a/.coveragerc b/.coveragerc
new file mode 100644
index 0000000..bc69d52
--- /dev/null
+++ b/.coveragerc
@@ -0,0 +1,5 @@
+[run]
+branch = True
+omit =
+ tqdm/tests/*
+ tqdm/_tqdm_gui.py
diff --git a/CONTRIBUTE b/CONTRIBUTE
new file mode 100644
index 0000000..76f61e6
--- /dev/null
+++ b/CONTRIBUTE
@@ -0,0 +1,94 @@
+HOW TO CONTRIBUTE TO TQDM
+=========================
+
+This file describes how to contribute changes to the project, and how to
+upload 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).
+
+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).
+
+
+HOW TO COMMIT YOUR 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
+(go to your fork's webpage and click on "Pull Request."
+You can then add a message to describe your proposal.)
+
+
+TESTING
+-------
+
+To test functionality on your machine (such as before submitting a Pull
+Request), there are a number of unit tests.
+
+
+Standard unit testing
+~~~~~~~~~~~~~~~~~~~~~
+
+The standard way to run the tests:
+
+- install `tox`
+- `cd` to the root of the `tqdm` directory (in the same folder as this file)
+- run the following command:
+
+```
+python setup.py make test
+```
+
+or
+
+```
+make test
+```
+
+or
+
+```
+tox --skip-missing-interpreters
+```
+
+This will build the module and run the tests in a virtual environment.
+Errors and coverage rates will be output to the console/log. (Ignore missing
+interpreters errors - these are due to the local machine missing certain
+versions of Python.)
+
+Note: to install all versions of the Python interpreter that are specified
+in [tox.ini](https://raw.githubusercontent.com/tqdm/tqdm/master/tox.ini),
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively, use `nose` to run the tests just for your Python version:
+
+- install `nose` and `flake8`
+- run the following command:
+
+```
+python setup.py make alltests
+```
+
+or
+
+```
+nosetests --with-coverage --cover-package=tqdm -v tqdm/
+python -m flake8 tqdm/_tqdm.py
+```
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 0000000..983da59
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,16 @@
+# Misc
+include .coveragerc
+include CONTRIBUTE
+include LICENSE
+include logo.png
+include Makefile
+include README.rst
+include RELEASE
+include tox.ini
+# include tqdm.gif # too big...
+
+# Test suite
+recursive-include tqdm/tests *.py
+
+# Examples/Documentation
+recursive-include examples *
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..ce0c711
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,113 @@
+# 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
+#
+# Sample makefile compatible with `python setup.py make`:
+#```
+#all:
+# @make test
+# @make install
+#test:
+# nosetest
+#install:
+# python setup.py install
+#```
+
+.PHONY:
+ alltests
+ all
+ flake8
+ test
+ testnose
+ testsetup
+ testcoverage
+ testperf
+ testtimer
+ distclean
+ coverclean
+ prebuildclean
+ clean
+ installdev
+ install
+ build
+ pypimeta
+ pypi
+ none
+
+alltests:
+ @+make testcoverage
+ @+make testperf
+ @+make flake8
+ @+make testsetup
+
+all:
+ @+make alltests
+ @+make build
+
+flake8:
+ @+flake8 --max-line-length=80 --count --statistics --exit-zero tqdm/
+ @+flake8 --max-line-length=80 --count --statistics --exit-zero examples/
+ @+flake8 --max-line-length=80 --count --statistics --exit-zero .
+ @+flake8 --max-line-length=80 --count --statistics --exit-zero tqdm/tests/
+
+test:
+ tox --skip-missing-interpreters
+
+testnose:
+ nosetests tqdm -d -v
+
+testsetup:
+ python setup.py check --restructuredtext --strict
+ python setup.py make none
+
+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)
+ nosetests tqdm/tests/tests_perf.py -d -v
+
+testtimer:
+ nosetests tqdm --with-timer -d -v
+
+distclean:
+ @+make coverclean
+ @+make prebuildclean
+ @+make clean
+prebuildclean:
+ @+python -c "import shutil; shutil.rmtree('build', True)"
+ @+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"
+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]')]"
+
+installdev:
+ python setup.py develop --uninstall
+ python setup.py develop
+
+install:
+ python setup.py install
+
+build:
+ @make prebuildclean
+ python setup.py sdist --formats=gztar,zip bdist_wheel
+ python setup.py bdist_wininst
+
+pypimeta:
+ python setup.py register
+
+pypi:
+ twine upload dist/*
+
+buildupload:
+ @make testsetup
+ @make build
+ @make pypimeta
+ @make pypi
+
+none:
+ # used for unit testing
diff --git a/PKG-INFO b/PKG-INFO
new file mode 100644
index 0000000..6c8046a
--- /dev/null
+++ b/PKG-INFO
@@ -0,0 +1,666 @@
+Metadata-Version: 1.1
+Name: tqdm
+Version: 4.4.1
+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
+Description: |Logo|
+
+ tqdm
+ ====
+
+ |PyPi Status| |PyPi Downloads|
+ |Build Status| |Coverage Status| |Branch Coverage Status|
+
+ ``tqdm`` (read taqadum, تقدّم) means "progress" in arabic.
+
+ Instantly make your loops show a smart progress meter - just wrap any
+ iterable with "tqdm(iterable)", and you're done!
+
+ .. code:: python
+
+ 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))``.
+
+ |Screenshot|
+
+ It can also be executed as a module with pipes:
+
+ .. code:: sh
+
+ $ seq 9999999 | tqdm --unit_scale True | wc -l
+ 10.0Mit [00:02, 3.58Mit/s]
+ 9999999
+
+ Overhead is low -- about 60ns per iteration (80ns with ``gui=True``), and is
+ unit tested against performance regression.
+ By comparison, the well established
+ `ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has
+ an 800ns/iter overhead.
+
+ 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),
+ 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.
+
+ ------------------------------------------
+
+ .. contents:: Table of contents
+ :backlinks: top
+ :local:
+
+
+ Installation
+ ------------
+
+ Latest pypi stable release
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ .. code:: sh
+
+ pip install tqdm
+
+ Latest development release on github
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ Pull and install in the current directory:
+
+ .. code:: sh
+
+ pip install -e git+https://github.com/tqdm/tqdm.git@master#egg=tqdm
+
+
+ Changelog
+ ---------
+
+ The list of all changes is available either on
+ `Github's Releases <https://github.com/tqdm/tqdm/releases>`_
+ or on crawlers such as
+ `allmychanges.com <https://allmychanges.com/p/python/tqdm/>`_.
+
+
+ Usage
+ -----
+
+ ``tqdm`` is very versatile and can be used in a number of ways.
+ The three main ones are given below.
+
+ Iterable-based
+ ~~~~~~~~~~~~~~
+
+ Wrap ``tqdm()`` around any iterable:
+
+ .. code:: python
+
+ text = ""
+ for char in tqdm(["a", "b", "c", "d"]):
+ text = text + char
+
+ ``trange(i)`` is a special optimised instance of ``tqdm(range(i))``:
+
+ .. code:: python
+
+ for i in trange(100):
+ pass
+
+ Instantiation outside of the loop allows for manual control over ``tqdm()``:
+
+ .. code:: python
+
+ pbar = tqdm(["a", "b", "c", "d"])
+ for char in pbar:
+ pbar.set_description("Processing %s" % char)
+
+ Manual
+ ~~~~~~
+
+ Manual control on ``tqdm()`` updates by using a ``with`` statement:
+
+ .. code:: python
+
+ with tqdm(total=100) as pbar:
+ for i in range(10):
+ pbar.update(10)
+
+ If the optional variable ``total`` (or an iterable with ``len()``) is
+ provided, predictive stats are displayed.
+
+ ``with`` is also optional (you can just assign ``tqdm()`` to a variable,
+ but in this case don't forget to ``del`` or ``close()`` at the end:
+
+ .. code:: python
+
+ pbar = tqdm(total=100)
+ for i in range(10):
+ pbar.update(10)
+ pbar.close()
+
+
+ Module
+ ~~~~~~
+
+ 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
+ in the current directory, with timing information included.
+
+ .. code:: sh
+
+ $ time find . -name '*.py' -exec cat \{} \; | wc -l
+ 857365
+
+ real 0m3.458s
+ user 0m0.274s
+ sys 0m3.325s
+
+ $ time find . -name '*.py' -exec cat \{} \; | tqdm | wc -l
+ 857366it [00:03, 246471.31it/s]
+ 857365
+
+ real 0m3.585s
+ user 0m0.862s
+ sys 0m3.358s
+
+ Note that the usual arguments for ``tqdm`` can also be specified.
+
+ .. code:: sh
+
+ $ find . -name '*.py' -exec cat \{} \; |
+ tqdm --unit loc --unit_scale True --total 857366 >> /dev/null
+ 100%|███████████████████████████████████| 857K/857K [00:04<00:00, 246Kloc/s]
+
+
+ Documentation
+ -------------
+
+ .. code:: python
+
+ class tqdm(object):
+ """
+ Decorate an iterable object, returning an iterator which acts exactly
+ like the original iterable, but prints a dynamically updating
+ progressbar every time a value is requested.
+ """
+
+ def __init__(self, iterable=None, desc=None, total=None, leave=True,
+ 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, bar_format=None, initial=0, position=None):
+
+ 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 [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.
+ * 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].
+ * maxinterval : float, optional
+ Maximum progress update interval, in seconds [default: 10.0].
+ * 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].
+ * dynamic_ncols : bool, optional
+ If set, constantly alters `ncols` to the environment (allowing
+ for window resizes) [default: False].
+ * smoothing : float
+ 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
+ '{desc}{percentage:3.0f}%|' and r_bar is
+ '| {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
+ The initial counter value. Useful when restarting a progress
+ bar [default: 0].
+ * position : int, optional
+ Specify the line offset to print this bar (starting from 0)
+ Automatic if [default: None].
+ Useful to manage multiple bars at once (eg, from threads).
+
+ Returns
+ ~~~~~~~
+
+ * out : decorated iterator.
+
+ .. code:: python
+
+ 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 <https://github.com/tqdm/tqdm/tree/master/examples>`__
+ folder or import the module and run ``help()``.
+
+ Hooks and callbacks
+ ~~~~~~~~~~~~~~~~~~~
+
+ ``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 urllib
+ 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, leave=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)
+
+ 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).
+
+ Pandas Integration
+ ~~~~~~~~~~~~~~~~~~
+
+ Due to popular demand we've added support for ``pandas`` -- here's an example
+ for ``DataFrameGroupBy.progress_apply``:
+
+ .. code:: python
+
+ import pandas as pd
+ 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`
+ # (can use tqdm_gui, optional kwargs, etc.)
+ tqdm_pandas(tqdm())
+
+ # Now you can use `progress_apply` instead of `apply`
+ 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
+ ~~~~~~~~~~~~~~~~~~~~
+
+ ``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.
+
+
+ How to make a good progress bar
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ A good progress bar is a useful progress bar. To be useful, ``tqdm`` displays
+ statistics and uses smart algorithms to predict and automagically adapt to
+ a variety of use cases with no or minimal configuration.
+
+ However, there is one thing that ``tqdm`` cannot do: choose a pertinent
+ progress indicator. To display a useful progress bar, it is very important that
+ ``tqdm`` is supplied with the most pertinent progress indicator.
+ This will reflect most accurately the current state of your program.
+ Usually, a good way is to preprocess quickly to first evaluate the total amount
+ of work to do before beginning the real processing.
+
+ To illustrate the importance of a good progress indicator, take the
+ following example: you want to walk through all files of a directory and
+ process their contents with some external function:
+
+ .. code:: python
+
+ import os
+ from tqdm import tqdm, trange
+ from time import sleep
+
+ def dosomething(buf):
+ """Do something with the content of a file"""
+ sleep(0.01)
+ pass
+
+ def walkdir(folder):
+ """Walk through each files in a directory"""
+ for dirpath, dirs, files in os.walk(folder):
+ for filename in files:
+ yield os.path.abspath(os.path.join(dirpath, filename))
+
+ def process_content_no_progress(inputpath, blocksize=1024):
+ for filepath in walkdir(inputpath):
+ with open(filepath, 'rb') as fh:
+ buf = 1
+ while (buf):
+ buf = fh.read(blocksize)
+ dosomething(buf)
+
+ ``process_content_no_progress()`` does the job, but does not show
+ any information about the current progress, nor how long it will take.
+
+ To quickly fix that using ``tqdm``, we can use this naive approach:
+
+ .. code:: python
+
+ def process_content_with_progress1(inputpath, blocksize=1024):
+ for filepath in tqdm(walkdir(inputpath), leave=True):
+ with open(filepath, 'rb') as fh:
+ buf = 1
+ while (buf):
+ buf = fh.read(blocksize)
+ dosomething(buf)
+
+ ``process_content_with_progress1()`` will load ``tqdm()``, but since the
+ iterator does not provide any length (``os.walkdir()`` does not have a
+ ``__len__()`` method for the total files count), there is only an indication
+ of the current and past program state, no prediction:
+
+ ``4it [00:03, 2.79it/s]``
+
+ The way to get predictive information is to know the total amount of work to be
+ done. Since ``os.walkdir()`` cannot give us this information, we need to
+ precompute this by ourselves:
+
+ .. code:: python
+
+ def process_content_with_progress2(inputpath, blocksize=1024):
+ # Preprocess the total files count
+ filecounter = 0
+ for dirpath, dirs, files in tqdm(os.walk(inputpath)):
+ for filename in files:
+ filecounter += 1
+
+ for filepath in tqdm(walkdir(inputpath), total=filecounter, leave=True):
+ with open(filepath, 'rb') as fh:
+ buf = 1
+ while (buf):
+ buf = fh.read(blocksize)
+ dosomething(buf)
+
+ ``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]
+
+ 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,
+ but we process the files contents. Thus, if we stumble on one very large file
+ which takes a great deal more time to process than other smaller files,
+ the progress bar
+ will still considers that file is of equal processing weight.
+
+ To fix this, we should use another indicator than the files count: the total
+ sum of all files sizes. This would be more pertinent since the data we
+ process is the files' content, so there is a direct relation between size and
+ content.
+
+ Below we implement this approach using a manually updated ``tqdm`` bar, where
+ ``tqdm`` will work on size, while the ``for`` loop works on files paths:
+
+ .. code:: python
+
+ def process_content_with_progress3(inputpath, blocksize=1024):
+ # Preprocess the total files sizes
+ sizecounter = 0
+ for dirpath, dirs, files in tqdm(os.walk(inputpath)):
+ for filename in files:
+ fullpath = os.path.abspath(os.path.join(dirpath, filename))
+ 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:
+ for dirpath, dirs, files in os.walk(inputpath):
+ for filename in files:
+ fullpath = os.path.abspath(os.path.join(dirpath, filename))
+ with open(fullpath, 'rb') as fh:
+ buf = 1
+ while (buf):
+ buf = fh.read(blocksize)
+ dosomething(buf)
+ if buf: pbar.update(len(buf))
+
+ 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]
+
+
+ Contributions
+ -------------
+
+ To run the testing suite please make sure tox (https://testrun.org/tox/latest/)
+ is installed, then type ``tox`` from the command line.
+
+ Where ``tox`` is unavailable, a Makefile-like setup is
+ provided with the following command:
+
+ .. code:: sh
+
+ $ python setup.py make alltests
+
+ To see all options, run:
+
+ .. code:: sh
+
+ $ python setup.py make
+
+ See the
+ `CONTRIBUTE <https://raw.githubusercontent.com/tqdm/tqdm/master/CONTRIBUTE>`__
+ file for more information.
+
+
+ License
+ -------
+
+ Multiple licences, mostly `MPLv2.0, MIT licences <https://raw.githubusercontent.com/tqdm/tqdm/master/LICENCE>`__.
+
+
+ Authors
+ -------
+
+ - Casper da Costa-Luis (casperdcl)
+ - Stephen Larroque (lrq3000)
+ - Hadrien Mary (hadim)
+ - Noam Yorav-Raphael (noamraph)*
+ - Ivan Ivanov (obiwanus)
+ - Mikhail Korobov (kmike)
+
+ `*` Original author
+
+ .. |Logo| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/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
+ .. |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
+ :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
+ .. |Screenshot| image:: https://raw.githubusercontent.com/tqdm/tqdm/master/tqdm.gif
+
+Keywords: progressbar progressmeter progress bar meter rate eta console terminal time
+Platform: any
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Framework :: IPython
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: POSIX :: BSD
+Classifier: Operating System :: POSIX :: BSD :: FreeBSD
+Classifier: Operating System :: POSIX :: SunOS/Solaris
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.6
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.2
+Classifier: Programming Language :: Python :: 3.3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Programming Language :: Python :: Implementation :: IronPython
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Classifier: Intended Audience :: Developers
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..4c27786
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,626 @@
+|Logo|
+
+tqdm
+====
+
+|PyPi Status| |PyPi Downloads|
+|Build Status| |Coverage Status| |Branch Coverage Status|
+
+``tqdm`` (read taqadum, تقدّم) means "progress" in arabic.
+
+Instantly make your loops show a smart progress meter - just wrap any
+iterable with "tqdm(iterable)", and you're done!
+
+.. code:: python
+
+ from tqdm import tqdm
+ for i in tqdm(range(9)):
+ ...
+
+Here's what the output looks like:
+
... 5647 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