add callable support for bar_format argument

lrq3000 · lrq3000 · commit cff7413282dc · 2016-06-07T21:59:17.000+02:00
Signed-off-by: Stephen L. &lt;lrq3000@gmail.com&gt;
diff --git a/README.rst b/README.rst
@@ -271,8 +271,9 @@ Parameters
     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  
+* bar_format  : str or callable, optional  
     Specify a custom bar string formatting. May impact performance.
+    Can be a callable that will handle bar display.
     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}]'
@@ -462,6 +463,34 @@ 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).
 
+Integration in a GUI
+~~~~~~~~~~~~~~~~~~~~
+``tqdm`` can easily be integrated in your own GUI by providing ``bar_format`` with
+a callback function that will update your GUI bar display:
+
+.. code:: python
+
+    from tqdm import tqdm
+    from time import sleep
+    from awesome import GUI
+    
+    class my_gui_bar(object):
+        '''Toy GUI bar'''
+        def __init__(self):
+            self.gui_bar = GUI()
+            self.gui_bar.init()
+            # etc.
+
+        def update(self, bar_args={}):
+            '''Callback for tqdm to update the bar display'''
+            self.gui_bar.set_text = "{n_fmt}/{n_total} [{elapsed}>{remaining}]".format(bar_args)
+            self.gui_bar.set_progress = bar_args['n']
+
+    gbar = my_gui_bar()
+    for i in tqdm(range(100), bar_format=gbar.update):
+        sleep(0.1)
+
+
 Pandas Integration
 ~~~~~~~~~~~~~~~~~~
 
diff --git a/tqdm/_tqdm.py b/tqdm/_tqdm.py
@@ -135,8 +135,9 @@ def format_meter(n, total, elapsed, ncols=None, prefix='',
         rate  : float, optional
             Manual override for iteration rate.
             If [default: None], uses n/elapsed.
-        bar_format  : str, optional
+        bar_format  : str or callable, optional
             Specify a custom bar string formatting. May impact performance.
+            Can be a callable that will handle bar display.
             [default: '{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}]'
@@ -216,7 +217,10 @@ def format_meter(n, total, elapsed, ncols=None, prefix='',
                             }
 
                 # Interpolate supplied bar format with the dict
-                if '{bar}' in bar_format:
+                if hasattr(bar_format, '__call__'):
+                    # Callback user provided function/method to handle display
+                    bar_format(bar_args)
+                elif '{bar}' in bar_format:
                     # Format left/right sides of the bar, and format the bar
                     # later in the remaining space (avoid breaking display)
                     l_bar_user, r_bar_user = bar_format.split('{bar}')
@@ -385,8 +389,9 @@ def __init__(self, iterable=None, desc=None, total=None, leave=True,
             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
+        bar_format  : str or callable, optional
             Specify a custom bar string formatting. May impact performance.
+            Can be a callable that will handle bar display.
             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}]'
