Add GranularBar widget

pR0Ps · wolph · commit 0ad8251f0bb6 · 2023-08-21T03:10:57.000+02:00
`GranularBar` is a widget that displays progress at a sub-character
granularity by using multiple marker characters.

Using the `GranularBar` in its default configuration will show a smooth
progress bar using unicode block characters. More examples are provided
in `examples.py`
diff --git a/README.rst b/README.rst
@@ -60,6 +60,7 @@ of widgets:
  - `FormatCustomText <http://progressbar-2.readthedocs.io/en/latest/_modules/progressbar/widgets.html#FormatCustomText>`_
  - `FormatLabel <http://progressbar-2.readthedocs.io/en/latest/_modules/progressbar/widgets.html#FormatLabel>`_
  - `FormatLabelBar <http://progressbar-2.readthedocs.io/en/latest/_modules/progressbar/widgets.html#FormatLabel>`_
+ - `GranularBar <http://progressbar-2.readthedocs.io/en/latest/_modules/progressbar/widgets.html#GranularBar>`_
  - `Percentage <http://progressbar-2.readthedocs.io/en/latest/_modules/progressbar/widgets.html#Percentage>`_
  - `PercentageLabelBar <http://progressbar-2.readthedocs.io/en/latest/_modules/progressbar/widgets.html#PercentageLabelBar>`_
  - `ReverseBar <http://progressbar-2.readthedocs.io/en/latest/_modules/progressbar/widgets.html#ReverseBar>`_
diff --git a/examples.py b/examples.py
@@ -176,6 +176,19 @@ def multi_progress_bar_example(left=True):
             bar.update(progress, jobs=jobs, force=True)
             time.sleep(0.02)
 
+@example
+def granular_progress_example():
+    widgets=[
+        progressbar.GranularBar(markers=" &#9615;&#9614;&#9613;&#9612;&#9611;&#9610;&#9609;&#9608;", left='', right='|'),
+        progressbar.GranularBar(markers=" &#9601;&#9602;&#9603;&#9604;&#9605;&#9606;&#9607;&#9608;", left='', right='|'),
+        progressbar.GranularBar(markers=" &#9622;&#9612;&#9627;&#9608;", left='', right='|'),
+        progressbar.GranularBar(markers=" &#9617;&#9618;&#9619;&#9608;", left='', right='|'),
+        progressbar.GranularBar(markers=" &#10304;&#10308;&#10310;&#10311;&#10439;&#10471;&#10487;&#10495;", left='', right='|'),
+        progressbar.GranularBar(markers=" .oO", left='', right=''),
+    ]
+    for i in progressbar.progressbar(range(100), widgets=widgets):
+        time.sleep(0.03)
+
 
 @example
 def percentage_label_bar_example():
diff --git a/progressbar/__init__.py b/progressbar/__init__.py
@@ -26,6 +26,7 @@
     VariableMixin,
     MultiRangeBar,
     MultiProgressBar,
+    GranularBar,
     FormatLabelBar,
     PercentageLabelBar,
     Variable,
@@ -74,6 +75,7 @@
     'VariableMixin',
     'MultiRangeBar',
     'MultiProgressBar',
+    'GranularBar',
     'FormatLabelBar',
     'PercentageLabelBar',
     'Variable',
diff --git a/progressbar/widgets.py b/progressbar/widgets.py
@@ -909,6 +909,62 @@ def get_values(self, progress, data):
         return ranges
 
 
+class GranularBar(AutoWidthWidgetBase):
+    '''A progressbar that can display progress at a sub-character granularity
+    by using multiple marker characters.
+
+    Examples of markers:
+     - Smooth: ` &#9615;&#9614;&#9613;&#9612;&#9611;&#9610;&#9609;&#9608;` (default)
+     - Bar: ` &#9601;&#9602;&#9603;&#9604;&#9605;&#9606;&#9607;&#9608;`
+     - Snake: ` &#9622;&#9612;&#9627;&#9608;`
+     - Fade in: ` &#9617;&#9618;&#9619;&#9608;`
+     - Dots: ` &#10304;&#10308;&#10310;&#10311;&#10439;&#10471;&#10487;&#10495;`
+     - Growing circles: ` .oO`
+    '''
+
+    def __init__(self, markers=' &#9615;&#9614;&#9613;&#9612;&#9611;&#9610;&#9609;&#9608;', left='|', right='|', **kwargs):
+        '''Creates a customizable progress bar.
+
+        markers - string of characters to use as granular progress markers. The
+                  first character should represent 0% and the last 100%.
+                  Ex: ` .oO`
+        left - string or callable object to use as a left border
+        right - string or callable object to use as a right border
+        '''
+        self.markers = markers
+        self.left = string_or_lambda(left)
+        self.right = string_or_lambda(right)
+
+        AutoWidthWidgetBase.__init__(self, **kwargs)
+
+    def __call__(self, progress, data, width):
+        left = converters.to_unicode(self.left(progress, data, width))
+        right = converters.to_unicode(self.right(progress, data, width))
+        width -= progress.custom_len(left) + progress.custom_len(right)
+
+        if progress.max_value is not base.UnknownLength \
+                and progress.max_value > 0:
+            percent = progress.value / progress.max_value
+        else:
+            percent = 0
+
+        num_chars = percent * width
+
+        marker = self.markers[-1] * int(num_chars)
+
+        marker_idx = int((num_chars % 1) * (len(self.markers) - 1))
+        if marker_idx:
+            marker += self.markers[marker_idx]
+
+        marker = converters.to_unicode(marker)
+
+        # Make sure we ignore invisible characters when filling
+        width += len(marker) - progress.custom_len(marker)
+        marker = marker.ljust(width, self.markers[0])
+
+        return left + marker + right
+
+
 class FormatLabelBar(FormatLabel, Bar):
     '''A bar which has a formatted label in the center.'''
     def __init__(self, format, **kwargs):
diff --git a/tests/test_monitor_progress.py b/tests/test_monitor_progress.py
@@ -206,6 +206,25 @@ def test_percentage_label_bar(testdir):
     ]
 
 
+def test_granular_bar(testdir):
+    result = testdir.runpython(testdir.makepyfile(_create_script(
+        widgets='[progressbar.GranularBar(markers=" .oO")]',
+        line_breaks=False,
+        items=list(range(5)),
+    )))
+    pprint.pprint(result.stderr.lines, width=70)
+    assert result.stderr.lines == [u'',
+        u'|                                                          |',
+        u'|OOOOOOOOOOO.                                              |',
+        u'|OOOOOOOOOOOOOOOOOOOOOOO                                   |',
+        u'|OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOo                       |',
+        u'|OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO.           |',
+        u'|OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO|',
+        u'',
+        u'|OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO|'
+    ]
+
+
 def test_colors(testdir):
     kwargs = dict(
         items=range(1),
