added prefix/suffix arguments to fix #168

Author: wolph

examples.py

@@ -37,6 +37,18 @@ def shortcut_example():
         time.sleep(0.1)
 
 
+@example
+def prefixed_shortcut_example():
+    for i in progressbar.progressbar(range(10), prefix='Hi: '):
+        time.sleep(0.1)
+
+
+@example
+def templated_shortcut_example():
+    for i in progressbar.progressbar(range(10), suffix='{seconds_elapsed:.1}'):
+        time.sleep(0.1)
+
+
 @example
 def with_example_stdout_redirection():
     with progressbar.ProgressBar(max_value=10, redirect_stdout=True) as p:

progressbar/bar.py

@@ -178,6 +178,8 @@ class ProgressBar(StdRedirectMixin, ResizableMixin, ProgressBarBase):
         max_error (bool): When True the progressbar will raise an error if it
             goes beyond it's set max_value. Otherwise the max_value is simply
             raised when needed
+            prefix (str): Prefix the progressbar with the given string
+            suffix (str): Prefix the progressbar with the given string
 
     A common way of using it is like:
 
@@ -228,7 +230,7 @@ class ProgressBar(StdRedirectMixin, ResizableMixin, ProgressBarBase):
     def __init__(self, min_value=0, max_value=None,
                  widgets=None, left_justify=True, initial_value=0,
                  poll_interval=None, widget_kwargs=None, custom_len=len,
-                 max_error=True, **kwargs):
+                 max_error=True, prefix=None, suffix=None, **kwargs):
         '''
         Initializes a progress bar with sane defaults
         '''
@@ -253,6 +255,8 @@ def __init__(self, min_value=0, max_value=None,
         self.max_value = max_value
         self.max_error = max_error
         self.widgets = widgets
+        self.prefix = prefix
+        self.suffix = suffix
         self.widget_kwargs = widget_kwargs or {}
         self.left_justify = left_justify
         self.value = initial_value
@@ -626,6 +630,14 @@ def start(self, max_value=None, init=True):
         if self.widgets is None:
             self.widgets = self.default_widgets()
 
+        if self.prefix:
+            self.widgets.insert(0, widgets.FormatLabel(
+                self.prefix, new_style=True))
+
+        if self.suffix:
+            self.widgets.append(widgets.FormatLabel(
+                self.suffix, new_style=True))
+
         for widget in self.widgets:
             interval = getattr(widget, 'INTERVAL', None)
             if interval is not None:

progressbar/shortcuts.py

@@ -2,10 +2,10 @@
 
 
 def progressbar(iterator, min_value=0, max_value=None,
-                widgets=None, **kwargs):
+                widgets=None, prefix=None, suffix=None, **kwargs):
     progressbar = bar.ProgressBar(
         min_value=min_value, max_value=max_value,
-        widgets=widgets, **kwargs)
+        widgets=widgets, prefix=prefix, suffix=suffix, **kwargs)
 
     for result in progressbar(iterator):
         yield result

progressbar/widgets.py

@@ -65,13 +65,17 @@ class FormatWidgetMixin(object):
     '''
     required_values = []
 
-    def __init__(self, format, **kwargs):
+    def __init__(self, format, new_style=False, **kwargs):
+        self.new_style = new_style
         self.format = format
 
     def __call__(self, progress, data, format=None):
         '''Formats the widget into a string'''
         try:
-            return (format or self.format) % data
+            if self.new_style:
+                return (format or self.format).format(**data)
+            else:
+                return (format or self.format) % data
         except (TypeError, KeyError):
             print('Error while formatting %r' % self.format, file=sys.stderr)
             pprint.pprint(data, stream=sys.stderr)
@@ -173,6 +177,10 @@ class FormatLabel(FormatWidgetMixin, WidthWidgetMixin):
     >>> str(label(Progress, dict(value='test')))
     ''
 
+    >>> label = FormatLabel('{value} :: {value:^6}', new_style=True)
+    >>> str(label(Progress, dict(value='test')))
+    'test ::  test '
+
     '''
 
     mapping = {