better docs (wording, linebreaks), new-style string formatting

tqdm/_tqdm.py

@@ -1,9 +1,19 @@
-from __future__ import division, absolute_import
+"""
+Customisable progressbar decorator for iterators.
+Includes a default (x)range iterator printing to stderr.
 
+Usage:
+  from tqdm import trange[, tqdm]
+  for i in trange(10):
+    ...
+"""
+from __future__ import division, absolute_import
 import sys
 import time
 
 
+__author__ = {"github.com/" : ["noamraph", "JackMc", "arkottke", "obiwanus",
+        "fordhurley", "kmike", "hadim", "casperdcl"]}
 __all__ = ['tqdm', 'trange', 'format_interval', 'format_meter']
 
 
@@ -11,9 +21,9 @@ def format_interval(t):
     mins, s = divmod(int(t), 60)
     h, m = divmod(mins, 60)
     if h:
-        return '%d:%02d:%02d' % (h, m, s)
+        return '{0:d}:{1:02d}:{2:02d}'.format(h, m, s)
     else:
-        return '%02d:%02d' % (m, s)
+        return '{0:02d}:{1:02d}'.format(m, s)
 
 
 def format_meter(n, total, elapsed):
@@ -24,7 +34,7 @@ def format_meter(n, total, elapsed):
         total = None
 
     elapsed_str = format_interval(elapsed)
-    rate = '%5.2f' % (n / elapsed) if elapsed else '?'
+    rate = '{0:5.2f}'.format(n / elapsed) if elapsed else '?'
 
     if total:
         frac = float(n) / total
@@ -33,15 +43,13 @@ def format_meter(n, total, elapsed):
         bar_length = int(frac*N_BARS)
         bar = '#'*bar_length + '-'*(N_BARS-bar_length)
 
-        percentage = '%3d%%' % (frac * 100)
+        left_str = format_interval(elapsed * (total-n) / n) if n else '?'
 
-        left_str = format_interval(elapsed / n * (total-n)) if n else '?'
-
-        return '|%s| %d/%d %s [elapsed: %s left: %s, %s iters/sec]' % (
-            bar, n, total, percentage, elapsed_str, left_str, rate)
+        return '|{0}| {1}/{2} {3:3.0f}% [elapsed: {4} left: {5}, {6} iters/sec]'.format(
+            bar, n, total, frac * 100, elapsed_str, left_str, rate)
 
     else:
-        return '%d [elapsed: %s, %s iters/sec]' % (n, elapsed_str, rate)
+        return '{0:d} [elapsed: {1}, {2} iters/sec]'.format(n, elapsed_str, rate)
 
 
 class StatusPrinter(object):
@@ -55,36 +63,36 @@ class StatusPrinter(object):
         self.last_printed_len = len(s)
 
 
-def tqdm(iterable, desc='', total=None,
-         leave=False, file=sys.stderr,
+def tqdm(iterable, desc=None, total=None, leave=False, file=sys.stderr,
          mininterval=0.5, miniters=1):
-    """Get an iterable object, and return an iterator which acts exactly like
-    the iterable, but prints a progress meter and updates it every time a
-    value is requested.
-
+    """
+    Decorate an iterable object, returning an iterator which acts exactly
+    like the orignal iterable, but prints a dynamically updating
+    progressbar.
+    
     Parameters
     ----------
-    iterable: iterable
-        Iterable to show progress for.
-    desc: str, optional
-        A short string, describing the progress, that is added in the beginning
-        of the line.
-    total : int, optional
-        The number of expected iterations. If not given, len(iterable) is used
-        if it is defined.
-    file : `io.TextIOWrapper` or `io.StringIO`, optional
-        A file-like object to output the progress message to. By default,
-        sys.stderr is used.
-    leave : bool, optional
-        If it is False (default), tqdm deletes its traces from screen after
-        it has finished iterating over all elements.
-    mininterval : float, optional
-        If less than mininterval seconds have passed since the last progress
-        meter update, it is not updated again (default: 0.5).
-    miniters : float, optional
-        If less than miniters iterations have passed since the last progress
-        meter update, it is not updated again (default: 1).
-
+    iterable  : iterable
+        Iterable to decorate with a progressbar.
+    desc  : str, optional
+        Prefix for the progressbar.
+    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.
+    file  : `io.TextIOWrapper` or `io.StringIO`, optional
+        Specifies where to output the progress messages.
+    leave  : bool, optional
+        if unset, removes all traces of the progressbar upon termination of
+        iteration [default: False].
+    mininterval  : float, optional
+        Minimum progress update interval, in seconds [default: 0.5].
+    miniters  : int, optional
+        Minimum progress update interval, in iterations [default: 1].
+    
+    Returns
+    -------
+    out  : decorated iterator.
     """
     if total is None:
         try:
@@ -123,7 +131,10 @@ def tqdm(iterable, desc='', total=None,
 
 
 def trange(*args, **kwargs):
-    """A shortcut for writing tqdm(range()) on py3 or tqdm(xrange()) on py2"""
+    """
+    A shortcut for tqdm(xrange(*args), **kwargs).
+    On Python3+ range is used instead of xrange.
+    """
     try:
         f = xrange
     except NameError: