update reporthook example with with syntax

netluxe · Nov 29, 2015 · d2263d9 · d2263d9
1 parent 4d9ec57
commit d2263d9
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 33 deletions.
diff --git a/README.rst b/README.rst
@@ -202,28 +202,44 @@ Here's an example with ``urllib``:
 
 .. code:: python
 
-    import tqdm
     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
+      -------
 
-    def my_hook(**kwargs):
-        t = tqdm.tqdm(**kwargs)
-        last_b = [0]
+      >>> with tqdm(...) as t:
+      ...     reporthook = my_hook(t)
+      ...     urllib.urlretrieve(..., reporthook=reporthook)
 
-        def inner(b=1, bsize=1, tsize=None, close=False):
-            if close:
-                t.close()
-                return
+      """
+      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) # manually update the progressbar
-            last_b[0] = b
-        return inner
+        t.update((b - last_b[0]) * bsize)
+        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)
+    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

diff --git a/examples/tqdm_wget.py b/examples/tqdm_wget.py
@@ -1,4 +1,4 @@
-"""An example of manual tqdm updates applied to urllib
+"""An example of wrapping manual tqdm updates for urllib reporthook.
 
 # urllib.urlretrieve documentation
 > If present, the hook function will be called once
@@ -10,7 +10,8 @@
     tqdm_wget.py [options]
 
 Options:
--h, --help  : print this help message and exit
+-h, --help
+    Print this help message and exit
 -u URL, --url URL  : string, optional
     The url to fetch.
     [default: http://www.doc.ic.ac.uk/~cod11/matryoshka.zip]
@@ -23,24 +24,30 @@
 from docopt import docopt
 
 
-def my_hook(**kwargs):
-    t = tqdm(**kwargs)
+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, close=False):
-        '''
+    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.
-        close  : bool, optional
-            Whether to cleanly terminate the progressbar [default: False].
-        '''
-        if close:
-            t.close()
-            return
+        """
         if tsize is not None:
             t.total = tsize
         t.update((b - last_b[0]) * bsize)
@@ -52,8 +59,7 @@ def inner(b=1, bsize=1, tsize=None, close=False):
 
 eg_link = opts['--url']
 eg_file = eg_link.replace('/', ' ').split()[-1]
-eg_hook = my_hook(unit='B', unit_scale=True, leave=True, miniters=1,
-                  desc=eg_file)  # all optional kwargs
-urllib.urlretrieve(eg_link, filename=opts['--output'],
-                   reporthook=eg_hook, data=None)
-eg_hook(close=True)  # close the progressbar
+with tqdm(unit='B', unit_scale=True, leave=True, miniters=1,
+          desc=eg_file) as t:  # all optional kwargs
+    urllib.urlretrieve(eg_link, filename=opts['--output'],
+                       reporthook=my_hook(t), data=None)