diff --git a/README.rst b/README.rst index b9f61e2a..d0eb90e1 100644 --- a/README.rst +++ b/README.rst @@ -71,6 +71,14 @@ Pull and install in the current directory: 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 `_ or on crawlers such as +`allmychanges.com `_. + + Usage ----- @@ -118,7 +126,7 @@ 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 ``close()`` at the end: +but in this case don't forget to ``del`` or ``close()`` at the end: .. code:: python @@ -140,7 +148,7 @@ Documentation progressbar every time a value is requested. """ - def __init__(self, iterable=None, desc=None, total=None, leave=False, + 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, @@ -161,7 +169,7 @@ Parameters 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 + If [default: True], removes all traces of the progressbar upon termination of iteration. * file : `io.TextIOWrapper` or `io.StringIO`, optional Specifies where to output the progress messages @@ -369,9 +377,9 @@ Nested progress bars from tqdm import trange from time import sleep - for i in trange(10, desc='1st loop', leave=True): - for j in trange(5, desc='2nd loop', leave=True): - for k in trange(100, desc='3nd loop', leave=True): + 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 `__ will be used if @@ -391,16 +399,14 @@ 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 -you ensure that you supply ``tqdm`` with the most pertinent progress indicator, -which will reflect most accurately the current state of your program. +``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, let's take the +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 to do your biddings. - -Here is a basic program to do that: +process their contents with some external function: .. code:: python @@ -427,7 +433,7 @@ Here is a basic program to do that: buf = fh.read(blocksize) dosomething(buf) -``process_content_no_progress()`` does the job alright, but it does not show +``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: @@ -476,10 +482,10 @@ now we have predictive information: 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 big fat file, -it will take a huge deal more time to process than other smaller files, but -the progress bar cannot know that, because we only supplied the files count, -so it considers that every element is of equal processing weight. +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 @@ -516,6 +522,7 @@ predicted time and statistics: 47%|██████████████████▍\ \| 152K/321K [00:03<00:03, 46.2KB/s] + Contributions ------------- @@ -542,7 +549,7 @@ file for more information. License ------- -`MIT LICENSE `__. +Mostly `CC, MIT licence `__. Authors diff --git a/tqdm/_tqdm.py b/tqdm/_tqdm.py index d8626ddf..097211fb 100644 --- a/tqdm/_tqdm.py +++ b/tqdm/_tqdm.py @@ -280,7 +280,7 @@ class tqdm(object): except KeyError: pass - def __init__(self, iterable=None, desc=None, total=None, leave=False, + 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, @@ -301,7 +301,7 @@ class tqdm(object): 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 + If [default: True], removes all traces of the progressbar upon termination of iteration. file : `io.TextIOWrapper` or `io.StringIO`, optional Specifies where to output the progress messages diff --git a/tqdm/_version.py b/tqdm/_version.py index 1dc9c54e..84e3a4cb 100644 --- a/tqdm/_version.py +++ b/tqdm/_version.py @@ -1,5 +1,5 @@ # Definition of the version number -version_info = 3, 7, 1 # major, minor, patch, -extra +version_info = 3, 8, 0 # major, minor, patch, -extra # Nice string for the version __version__ = '.'.join(map(str, version_info)).replace('.-', '-').strip('.-')