[shellutil] add argument to ``ProgressBar.update`` to tune cursor progression (closes #88981)

3 files changed, 41 insertions, 3 deletions

diff --git a/ChangeLog b/ChangeLog
index 108f346..61de712 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -4,6 +4,7 @@ ChangeLog for logilab.common
 	--
     * new `registry` module containing a backport of CubicWeb selectable objects registry (closes #84654)
     * testlib: DocTestCase fix builtins pollution after doctest execution.
+    * shellutil: add argument to ``ProgressBar.update`` to tune cursor progression (closes #88981)
 
 2011-10-28  --  0.57.1
     * daemon: change $HOME after dropping privileges (closes #81297)
diff --git a/shellutils.py b/shellutils.py
index c713913..749cbac 100644
--- a/shellutils.py
+++ b/shellutils.py
@@ -315,9 +315,22 @@ class ProgressBar(object):
 
     text = property(_get_text, _set_text, _del_text)
 
-    def update(self):
-        """Update the progression bar."""
-        self._current += 1
+    def update(self, offset=1, exact=False):
+        """Move FORWARD to new cursor position (cursor will never go backward).
+
+        :offset: fraction of ``size``
+
+        :exact:
+
+          - False: offset relative to current cursor position if True
+          - True: offset as an asbsolute position
+
+        """
+        if exact:
+            self._current = offset
+        else:
+            self._current += offset
+
         progress = int((float(self._current)/float(self._total))*self._size)
         if progress > self._progress:
             self._progress = progress
diff --git a/test/unittest_shellutils.py b/test/unittest_shellutils.py
index 81c4397..fb9e1ca 100644
--- a/test/unittest_shellutils.py
+++ b/test/unittest_shellutils.py
@@ -144,6 +144,30 @@ class ProgressBarTC(TestCase):
     def test_overflow(self):
         self._update_test(5, (8, 16, 25, 33, 42, (42, True)), size=42)
 
+    def test_update_exact(self):
+        pgb_stream = StringIO()
+        expected_stream = StringIO()
+        size=20
+        pgb = ProgressBar(100, size, stream=pgb_stream)
+        last = 0
+        for dots in xrange(10, 105, 15):
+            pgb.update(dots, exact=True)
+            dots /= 5
+            expected_stream.write("\r["+('.'*dots)+(' '*(size-dots))+"]")
+            self.assertEqual(pgb_stream.getvalue(), expected_stream.getvalue())
+        
+    def test_update_relative(self):
+        pgb_stream = StringIO()
+        expected_stream = StringIO()
+        size=20
+        pgb = ProgressBar(100, size, stream=pgb_stream)
+        last = 0
+        for dots in xrange(5, 105, 5):
+            pgb.update(5, exact=False)
+            dots /= 5
+            expected_stream.write("\r["+('.'*dots)+(' '*(size-dots))+"]")
+            self.assertEqual(pgb_stream.getvalue(), expected_stream.getvalue())
+
 
 class AcquireLockTC(TestCase):