Merge branch 'release/4.2.0'

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2015, Rick van Hattem (Wolph)
+Copyright (c) 2022, Rick van Hattem (Wolph)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

docs/history.rst

@@ -0,0 +1,8 @@
+.. _history:
+
+=======
+History
+=======
+
+.. include:: ../CHANGES.rst
+    :start-line: 5

docs/index.rst

@@ -5,6 +5,7 @@ Welcome to Progress Bar's documentation!
 .. toctree::
    :maxdepth: 4
 
+   usage
    examples
    contributing
    installation
@@ -13,6 +14,7 @@ Welcome to Progress Bar's documentation!
    progressbar.base
    progressbar.utils
    progressbar.widgets
+   history
 
 .. include:: ../README.rst
 

docs/progressbar.bar.rst

@@ -5,3 +5,4 @@ progressbar.bar module
     :members:
     :undoc-members:
     :show-inheritance:
+    :member-order: bysource

docs/usage.rst

@@ -0,0 +1,70 @@
+========
+Usage
+========
+
+There are many ways to use Python Progressbar, you can see a few basic examples
+here but there are many more in the :doc:`examples` file.
+
+Wrapping an iterable
+------------------------------------------------------------------------------
+::
+
+   import time
+   import progressbar
+
+   bar = progressbar.ProgressBar()
+   for i in bar(range(100)):
+       time.sleep(0.02)
+
+Context wrapper
+------------------------------------------------------------------------------
+::
+
+   import time
+   import progressbar
+
+   with progressbar.ProgressBar(max_value=10) as bar:
+       for i in range(10):
+           time.sleep(0.1)
+           bar.update(i)
+
+Combining progressbars with print output
+------------------------------------------------------------------------------
+::
+
+    import time
+    import progressbar
+
+    bar = progressbar.ProgressBar(redirect_stdout=True)
+    for i in range(100):
+        print 'Some text', i
+        time.sleep(0.1)
+        bar.update(i)
+
+Progressbar with unknown length
+------------------------------------------------------------------------------
+::
+
+    import time
+    import progressbar
+
+    bar = progressbar.ProgressBar(max_value=progressbar.UnknownLength)
+    for i in range(20):
+        time.sleep(0.1)
+        bar.update(i)
+
+Bar with custom widgets
+------------------------------------------------------------------------------
+::
+
+    import time
+    import progressbar
+
+    bar = progressbar.ProgressBar(widgets=[
+        ' [', progressbar.Timer(), '] ',
+        progressbar.Bar(),
+        ' (', progressbar.ETA(), ') ',
+    ])
+    for i in bar(range(20)):
+        time.sleep(0.1)
+

progressbar/__about__.py

@@ -19,7 +19,7 @@
 long running operations.
 '''.strip().split())
 __email__ = 'wolph@wol.ph'
-__version__ = '4.1.1'
+__version__ = '4.2.0'
 __license__ = 'BSD'
 __copyright__ = 'Copyright 2015 Rick van Hattem (Wolph)'
 __url__ = 'https://github.com/WoLpH/python-progressbar'

progressbar/bar.py

@@ -27,6 +27,9 @@
 logger = logging.getLogger(__name__)
 
 
+T = types.TypeVar('T')
+
+
 class ProgressBarMixinBase(object):
 
     def __init__(self, **kwargs):
@@ -265,16 +268,21 @@ class ProgressBar(StdRedirectMixin, ResizableMixin, ProgressBarBase):
     the current progress bar. As a result, you have access to the
     ProgressBar's methods and attributes. Although there is nothing preventing
     you from changing the ProgressBar you should treat it as read only.
-
-    Useful methods and attributes include (Public API):
-     - value: current progress (min_value <= value <= max_value)
-     - max_value: maximum (and final) value
-     - end_time: not None if the bar has finished (reached 100%)
-     - start_time: the time when start() method of ProgressBar was called
-     - seconds_elapsed: seconds elapsed since start_time and last call to
-                        update
     '''
 
+    #: Current progress (min_value <= value <= max_value)
+    value: T
+    #: Maximum (and final) value. Beyond this value an error will be raised
+    #: unless the `max_error` parameter is `False`.
+    max_value: T
+    #: The time the progressbar reached `max_value` or when `finish()` was
+    #: called.
+    end_time: datetime
+    #: The time `start()` was called or iteration started.
+    start_time: datetime
+    #: Seconds between `start_time` and last call to `update()`
+    seconds_elapsed: float
+
     _DEFAULT_MAXVAL = base.UnknownLength
     # update every 50 milliseconds (up to a 20 times per second)
     _MINIMUM_UPDATE_INTERVAL = 0.050
@@ -568,7 +576,10 @@ def __enter__(self):
 
     def __iadd__(self, value):
         'Updates the ProgressBar by adding a new value.'
-        self.update(self.value + value)
+        return self.increment(value)
+
+    def increment(self, value=1, *args, **kwargs):
+        self.update(self.value + value, *args, **kwargs)
         return self
 
     def _format_widgets(self):
@@ -788,6 +799,16 @@ def finish(self, end='\n', dirty=False):
         ResizableMixin.finish(self)
         ProgressBarBase.finish(self)
 
+    @property
+    def currval(self):
+        '''
+        Legacy method to make progressbar-2 compatible with the original
+        progressbar package
+        '''
+        warnings.warn('The usage of `currval` is deprecated, please use '
+                      '`value` instead', DeprecationWarning)
+        return self.value
+
 
 class DataTransferBar(ProgressBar):
     '''A progress bar with sensible defaults for downloads etc.

tests/test_failure.py

@@ -99,6 +99,13 @@ def test_deprecated_poll():
         progressbar.ProgressBar(poll=5)
 
 
+def test_deprecated_currval():
+    with pytest.warns(DeprecationWarning):
+        bar = progressbar.ProgressBar(max_value=5)
+        bar.update(2)
+        assert bar.currval == 2
+
+
 def test_unexpected_update_keyword_arg():
     p = progressbar.ProgressBar(max_value=10)
     with pytest.raises(TypeError):

tests/test_iterators.py

@@ -51,7 +51,8 @@ def test_adding_value():
     p = progressbar.ProgressBar(max_value=10)
     p.start()
     p.update(5)
-    p += 5
+    p += 2
+    p.increment(2)
     with pytest.raises(ValueError):
         p += 5