cs-progress 20250412__tar.gz → 20250528__tar.gz

{cs_progress-20250412 → cs_progress-20250528}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cs-progress
-Version: 20250412
+Version: 20250528
 Summary: A progress tracker with methods for throughput, ETA and update notification; also a compound progress meter composed from other progress meters.
 Keywords: python2,python3
 Author-email: Cameron Simpson <cs@cskk.id.au>
@@ -12,14 +12,14 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
-Requires-Dist: cs.deco>=20250306
+Requires-Dist: cs.deco>=20250513
 Requires-Dist: cs.logutils>=20250323
 Requires-Dist: cs.py.func>=20240630
+Requires-Dist: cs.queues>=20250426
 Requires-Dist: cs.resources>=20250325
 Requires-Dist: cs.seq>=20250306
-Requires-Dist: cs.threads>=20250325
-Requires-Dist: cs.units
-Requires-Dist: cs.upd>=20240630
+Requires-Dist: cs.units>=20250528
+Requires-Dist: cs.upd>=20250426
 Requires-Dist: icontract
 Requires-Dist: typeguard
 Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
@@ -30,15 +30,36 @@ Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python
 A progress tracker with methods for throughput, ETA and update notification;
 also a compound progress meter composed from other progress meters.
 
-*Latest release 20250412*:
-Bugfix progressbar: fix early return if no active Upd.
+*Latest release 20250528*:
+progressbar: also run the progress bar if report_print is true in order to get the report (was optimised out when the Upd was disabled).
+
+This contains the follow main items:
+* `progressbar`: a wrapper for an iterable presenting a progress
+  bar in the terminal
+* `Progress`: a progress tracking class
+* `OverProgress`: a progress tracking class which tracks the
+  aggregate of multiple `Progress` instances
+
+Example:
+
+    for item in progressbar(items, "task name"):
+        ....
+
+Short summary:
+* `auto_progressbar`: Decorator for a function accepting an optional `progress` keyword parameter. If `progress` is not `None` and the default `Upd` is not disabled, run the function with a progress bar.
+* `BaseProgress`: The base class for `Progress` and `OverProcess` with various common methods.
+* `CheckPoint`: CheckPoint(time, position).
+* `OverProgress`: A `Progress`-like class computed from a set of subsidiary `Progress`es.
+* `Progress`: A progress counter to track task completion with various utility methods.
+* `progressbar`: Convenience function to construct and run a `Progress.iterbar` wrapping the iterable `it`, issuing and withdrawing a progress bar during the iteration. If there is no current `Upd` instance or it is disabled, this returns `it` directly.
+* `selftest`: Exercise some of the functionality.
 
 Module contents:
 - <a name="auto_progressbar"></a>`auto_progressbar(*da, **dkw)`: Decorator for a function accepting an optional `progress`
   keyword parameter.
   If `progress` is not `None` and the default `Upd` is not disabled,
   run the function with a progress bar.
-- <a name="BaseProgress"></a>`Class `BaseProgress`: The base class for `Progress` and `OverProcess`
+- <a name="BaseProgress"></a>`Class `BaseProgress``: The base class for `Progress` and `OverProcess`
   with various common methods.
 
   Note that durations are in seconds
@@ -78,18 +99,19 @@ if its position is less than `int(other)`.
 Construct a progress arrow representing completion
 to fit in the specified `width`.
 
-*`BaseProgress.bar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x10c191da0>, **kw)`*:
+*`BaseProgress.bar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1070dcea0>, **kw)`*:
 A context manager to create and withdraw a progress bar.
 It returns the `UpdProxy` which displays the progress bar.
 
 Parameters:
-* `label`: a label for the progress bar,
+* `label`: an optional label for the progress bar,
   default from `self.name`.
-* `statusfunc`: an optional function to compute the progress bar text
-  accepting `(self,label,width)`.
-* `width`: an optional width expressing how wide the progress bar
-  text may be.
-  The default comes from the `proxy.width` property.
+* `insert_pos`: where to insert the progress bar within the `cs.Upd`,
+  default `1`
+* `poll`: an optional callable which will receive `self`,
+  which can be used to update the progress state before
+  updating the progress bar display; useful if the progress
+  should be updates from some other programme state
 * `recent_window`: optional timeframe to define "recent" in seconds;
   if the default `statusfunc` (`Progress.status`) is used
   this is passed to it
@@ -98,11 +120,15 @@ Parameters:
   this may also be a `bool`, which if true will use `Upd.print`
   in order to interoperate with `Upd`.
 * `stalled`: optional string to replace the word `'stalled'`
-  in the status line; for a worked this might be betteer as `'idle'`
-* `insert_pos`: where to insert the progress bar, default `1`
-* `poll`: an optional callable accepting a `BaseProgress`
-  which can be used to update the progress state before
-  updating the progress bar display
+  in the status line; for a worker this might be better as `'idle'`
+* `statusfunc`: an optional function to compute the progress bar text
+  accepting `(self,label,width)`; default `Progress.status`
+* `update_period`: an optional frequency with which to update the display,
+  default from `DEFAULT_UPDATE_PERIOD` (0.3s);
+  if set to `0` then the display is updated whenever `self` is updated
+* `width`: an optional width expressing how wide the progress bar
+  text may be.
+  The default comes from the `proxy.width` property.
 
 Example use:
 
@@ -125,7 +151,7 @@ If `remaining_time` is `None`, this is also `None`.
 Format `value` accoridng to `scale` and `max_parts`
 using `cs.units.transcribe`.
 
-*`BaseProgress.iterbar(self, it, label=None, *, itemlenfunc=None, incfirst=False, update_period=0.3, cancelled=None, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x10c192200>, **bar_kw)`*:
+*`BaseProgress.iterbar(self, it, label=None, *, itemlenfunc=None, incfirst=False, update_period=0.3, cancelled=None, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x1070dd300>, **bar_kw)`*:
 An iterable progress bar: a generator yielding values
 from the iterable `it` while updating a progress bar.
 
@@ -149,7 +175,7 @@ Parameters:
 * `cancelled`: an optional callable to test for iteration cancellation
 Other parameters are passed to `Progress.bar`.
 
-Example use:
+Example uses:
 
     from cs.units import DECIMAL_SCALE
     rows = [some list of data]
@@ -157,23 +183,30 @@ Example use:
     for row in P.iterbar(rows, incfirst=True):
         ... do something with each row ...
 
-    f = open(data_filename, 'rb')
-    datalen = os.stat(f).st_size
-    def readfrom(f):
-        while True:
-            bs = f.read(65536)
-            if not bs:
-                break
-            yield bs
-    P = Progress(total=datalen)
-    for bs in P.iterbar(readfrom(f), itemlenfunc=len):
-        ... process the file data in bs ...
+    with open(data_filename, 'rb') as f:
+        datalen = os.stat(f).st_size
+        def readfrom(f):
+            while True:
+                bs = f.read(65536)
+                if not bs:
+                    break
+                yield bs
+        P = Progress(total=datalen)
+        for bs in P.iterbar(readfrom(f), itemlenfunc=len):
+            ... process the file data in bs ...
 
 *`BaseProgress.qbar(self, label=None, **iterbar_kw) -> cs.queues.QueueIterator`*:
-Set up a progress bar, return a `QueueIterator` for receiving items.
-This is a shim for `Progress.iterbar` which dispatches a
-worker to iterate a queue which received items placed on
-the queue.
+Set up a progress bar, return a closeable `Queue`-like object
+for receiving items. This is a shim for `Progress.iterbar`
+which dispatches a worker to iterate items put onto a queue.
+
+Example:
+
+    Q = Progress.qbar("label")
+    try:
+        ... do work, calling Q.put(item) ...
+    finally:
+        Q.close()
 
 *`BaseProgress.ratio`*:
 The fraction of progress completed: `(position-start)/(total-start)`.
@@ -238,7 +271,7 @@ during `elapsed_time`.
 
 *`BaseProgress.throughput_recent(self, time_window)`*:
 The recent throughput. Implemented by subclasses.
-- <a name="CheckPoint"></a>`Class `CheckPoint(builtins.tuple)`: CheckPoint(time, position)
+- <a name="CheckPoint"></a>`Class `CheckPoint(builtins.tuple)``: CheckPoint(time, position)
 
 *`CheckPoint.__replace__(self, /, **kwds)`*:
 Return a new CheckPoint object replacing specified fields with new values
@@ -248,7 +281,7 @@ Alias for field number 1
 
 *`CheckPoint.time`*:
 Alias for field number 0
-- <a name="OverProgress"></a>`Class `OverProgress(BaseProgress)`: A `Progress`-like class computed from a set of subsidiary `Progress`es.
+- <a name="OverProgress"></a>`Class `OverProgress(BaseProgress)``: A `Progress`-like class computed from a set of subsidiary `Progress`es.
 
   AN OverProgress instance has an attribute ``notify_update`` which
   is a set of callables.
@@ -309,7 +342,7 @@ The `throughput_recent` is the sum of the subsidiary throughput_recentss.
 
 *`OverProgress.total`*:
 The `total` is the sum of the subsidiary totals.
-- <a name="Progress"></a>`Class `Progress(BaseProgress)`: A progress counter to track task completion with various utility methods.
+- <a name="Progress"></a>`Class `Progress(BaseProgress)``: A progress counter to track task completion with various utility methods.
 
   Example:
 
@@ -433,9 +466,11 @@ Record more progress.
 >>> P.update(12)
 >>> P.position
 12
-- <a name="progressbar"></a>`progressbar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x10c193c40>, **kw)`: Convenience function to construct and run a `Progress.iterbar`
+- <a name="progressbar"></a>`progressbar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1070ded40>, **kw)`: Convenience function to construct and run a `Progress.iterbar`
   wrapping the iterable `it`,
   issuing and withdrawing a progress bar during the iteration.
+  If there is no current `Upd` instance or it is disabled, this
+  returns `it` directly.
 
   Parameters:
   * `it`: the iterable to consume
@@ -461,6 +496,9 @@ Record more progress.
 
 
 
+*Release 20250528*:
+progressbar: also run the progress bar if report_print is true in order to get the report (was optimised out when the Upd was disabled).
+
 *Release 20250412*:
 Bugfix progressbar: fix early return if no active Upd.
 

{cs_progress-20250412 → cs_progress-20250528}/pyproject.toml

@@ -9,14 +9,14 @@ keywords = [
     "python3",
 ]
 dependencies = [
-    "cs.deco>=20250306",
+    "cs.deco>=20250513",
     "cs.logutils>=20250323",
     "cs.py.func>=20240630",
+    "cs.queues>=20250426",
     "cs.resources>=20250325",
     "cs.seq>=20250306",
-    "cs.threads>=20250325",
-    "cs.units",
-    "cs.upd>=20240630",
+    "cs.units>=20250528",
+    "cs.upd>=20250426",
     "icontract",
     "typeguard",
 ]
@@ -29,7 +29,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
 ]
-version = "20250412"
+version = "20250528"
 
 [project.license]
 text = "GNU General Public License v3 or later (GPLv3+)"
@@ -45,15 +45,36 @@ text = """
 A progress tracker with methods for throughput, ETA and update notification;
 also a compound progress meter composed from other progress meters.
 
-*Latest release 20250412*:
-Bugfix progressbar: fix early return if no active Upd.
+*Latest release 20250528*:
+progressbar: also run the progress bar if report_print is true in order to get the report (was optimised out when the Upd was disabled).
+
+This contains the follow main items:
+* `progressbar`: a wrapper for an iterable presenting a progress
+  bar in the terminal
+* `Progress`: a progress tracking class
+* `OverProgress`: a progress tracking class which tracks the
+  aggregate of multiple `Progress` instances
+
+Example:
+
+    for item in progressbar(items, \"task name\"):
+        ....
+
+Short summary:
+* `auto_progressbar`: Decorator for a function accepting an optional `progress` keyword parameter. If `progress` is not `None` and the default `Upd` is not disabled, run the function with a progress bar.
+* `BaseProgress`: The base class for `Progress` and `OverProcess` with various common methods.
+* `CheckPoint`: CheckPoint(time, position).
+* `OverProgress`: A `Progress`-like class computed from a set of subsidiary `Progress`es.
+* `Progress`: A progress counter to track task completion with various utility methods.
+* `progressbar`: Convenience function to construct and run a `Progress.iterbar` wrapping the iterable `it`, issuing and withdrawing a progress bar during the iteration. If there is no current `Upd` instance or it is disabled, this returns `it` directly.
+* `selftest`: Exercise some of the functionality.
 
 Module contents:
 - <a name=\"auto_progressbar\"></a>`auto_progressbar(*da, **dkw)`: Decorator for a function accepting an optional `progress`
   keyword parameter.
   If `progress` is not `None` and the default `Upd` is not disabled,
   run the function with a progress bar.
-- <a name=\"BaseProgress\"></a>`Class `BaseProgress`: The base class for `Progress` and `OverProcess`
+- <a name=\"BaseProgress\"></a>`Class `BaseProgress``: The base class for `Progress` and `OverProcess`
   with various common methods.
 
   Note that durations are in seconds
@@ -93,18 +114,19 @@ if its position is less than `int(other)`.
 Construct a progress arrow representing completion
 to fit in the specified `width`.
 
-*`BaseProgress.bar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x10c191da0>, **kw)`*:
+*`BaseProgress.bar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1070dcea0>, **kw)`*:
 A context manager to create and withdraw a progress bar.
 It returns the `UpdProxy` which displays the progress bar.
 
 Parameters:
-* `label`: a label for the progress bar,
+* `label`: an optional label for the progress bar,
   default from `self.name`.
-* `statusfunc`: an optional function to compute the progress bar text
-  accepting `(self,label,width)`.
-* `width`: an optional width expressing how wide the progress bar
-  text may be.
-  The default comes from the `proxy.width` property.
+* `insert_pos`: where to insert the progress bar within the `cs.Upd`,
+  default `1`
+* `poll`: an optional callable which will receive `self`,
+  which can be used to update the progress state before
+  updating the progress bar display; useful if the progress
+  should be updates from some other programme state
 * `recent_window`: optional timeframe to define \"recent\" in seconds;
   if the default `statusfunc` (`Progress.status`) is used
   this is passed to it
@@ -113,11 +135,15 @@ Parameters:
   this may also be a `bool`, which if true will use `Upd.print`
   in order to interoperate with `Upd`.
 * `stalled`: optional string to replace the word `'stalled'`
-  in the status line; for a worked this might be betteer as `'idle'`
-* `insert_pos`: where to insert the progress bar, default `1`
-* `poll`: an optional callable accepting a `BaseProgress`
-  which can be used to update the progress state before
-  updating the progress bar display
+  in the status line; for a worker this might be better as `'idle'`
+* `statusfunc`: an optional function to compute the progress bar text
+  accepting `(self,label,width)`; default `Progress.status`
+* `update_period`: an optional frequency with which to update the display,
+  default from `DEFAULT_UPDATE_PERIOD` (0.3s);
+  if set to `0` then the display is updated whenever `self` is updated
+* `width`: an optional width expressing how wide the progress bar
+  text may be.
+  The default comes from the `proxy.width` property.
 
 Example use:
 
@@ -140,7 +166,7 @@ If `remaining_time` is `None`, this is also `None`.
 Format `value` accoridng to `scale` and `max_parts`
 using `cs.units.transcribe`.
 
-*`BaseProgress.iterbar(self, it, label=None, *, itemlenfunc=None, incfirst=False, update_period=0.3, cancelled=None, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x10c192200>, **bar_kw)`*:
+*`BaseProgress.iterbar(self, it, label=None, *, itemlenfunc=None, incfirst=False, update_period=0.3, cancelled=None, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x1070dd300>, **bar_kw)`*:
 An iterable progress bar: a generator yielding values
 from the iterable `it` while updating a progress bar.
 
@@ -164,7 +190,7 @@ Parameters:
 * `cancelled`: an optional callable to test for iteration cancellation
 Other parameters are passed to `Progress.bar`.
 
-Example use:
+Example uses:
 
     from cs.units import DECIMAL_SCALE
     rows = [some list of data]
@@ -172,23 +198,30 @@ Example use:
     for row in P.iterbar(rows, incfirst=True):
         ... do something with each row ...
 
-    f = open(data_filename, 'rb')
-    datalen = os.stat(f).st_size
-    def readfrom(f):
-        while True:
-            bs = f.read(65536)
-            if not bs:
-                break
-            yield bs
-    P = Progress(total=datalen)
-    for bs in P.iterbar(readfrom(f), itemlenfunc=len):
-        ... process the file data in bs ...
+    with open(data_filename, 'rb') as f:
+        datalen = os.stat(f).st_size
+        def readfrom(f):
+            while True:
+                bs = f.read(65536)
+                if not bs:
+                    break
+                yield bs
+        P = Progress(total=datalen)
+        for bs in P.iterbar(readfrom(f), itemlenfunc=len):
+            ... process the file data in bs ...
 
 *`BaseProgress.qbar(self, label=None, **iterbar_kw) -> cs.queues.QueueIterator`*:
-Set up a progress bar, return a `QueueIterator` for receiving items.
-This is a shim for `Progress.iterbar` which dispatches a
-worker to iterate a queue which received items placed on
-the queue.
+Set up a progress bar, return a closeable `Queue`-like object
+for receiving items. This is a shim for `Progress.iterbar`
+which dispatches a worker to iterate items put onto a queue.
+
+Example:
+
+    Q = Progress.qbar(\"label\")
+    try:
+        ... do work, calling Q.put(item) ...
+    finally:
+        Q.close()
 
 *`BaseProgress.ratio`*:
 The fraction of progress completed: `(position-start)/(total-start)`.
@@ -253,7 +286,7 @@ during `elapsed_time`.
 
 *`BaseProgress.throughput_recent(self, time_window)`*:
 The recent throughput. Implemented by subclasses.
-- <a name=\"CheckPoint\"></a>`Class `CheckPoint(builtins.tuple)`: CheckPoint(time, position)
+- <a name=\"CheckPoint\"></a>`Class `CheckPoint(builtins.tuple)``: CheckPoint(time, position)
 
 *`CheckPoint.__replace__(self, /, **kwds)`*:
 Return a new CheckPoint object replacing specified fields with new values
@@ -263,7 +296,7 @@ Alias for field number 1
 
 *`CheckPoint.time`*:
 Alias for field number 0
-- <a name=\"OverProgress\"></a>`Class `OverProgress(BaseProgress)`: A `Progress`-like class computed from a set of subsidiary `Progress`es.
+- <a name=\"OverProgress\"></a>`Class `OverProgress(BaseProgress)``: A `Progress`-like class computed from a set of subsidiary `Progress`es.
 
   AN OverProgress instance has an attribute ``notify_update`` which
   is a set of callables.
@@ -324,7 +357,7 @@ The `throughput_recent` is the sum of the subsidiary throughput_recentss.
 
 *`OverProgress.total`*:
 The `total` is the sum of the subsidiary totals.
-- <a name=\"Progress\"></a>`Class `Progress(BaseProgress)`: A progress counter to track task completion with various utility methods.
+- <a name=\"Progress\"></a>`Class `Progress(BaseProgress)``: A progress counter to track task completion with various utility methods.
 
   Example:
 
@@ -448,9 +481,11 @@ Record more progress.
 >>> P.update(12)
 >>> P.position
 12
-- <a name=\"progressbar\"></a>`progressbar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x10c193c40>, **kw)`: Convenience function to construct and run a `Progress.iterbar`
+- <a name=\"progressbar\"></a>`progressbar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x1070ded40>, **kw)`: Convenience function to construct and run a `Progress.iterbar`
   wrapping the iterable `it`,
   issuing and withdrawing a progress bar during the iteration.
+  If there is no current `Upd` instance or it is disabled, this
+  returns `it` directly.
 
   Parameters:
   * `it`: the iterable to consume
@@ -476,6 +511,9 @@ Record more progress.
 
 
 
+*Release 20250528*:
+progressbar: also run the progress bar if report_print is true in order to get the report (was optimised out when the Upd was disabled).
+
 *Release 20250412*:
 Bugfix progressbar: fix early return if no active Upd.
 

{cs_progress-20250412 → cs_progress-20250528}/src/cs/progress.py

@@ -8,6 +8,18 @@
 
 ''' A progress tracker with methods for throughput, ETA and update notification;
     also a compound progress meter composed from other progress meters.
+
+    This contains the follow main items:
+    * `progressbar`: a wrapper for an iterable presenting a progress
+      bar in the terminal
+    * `Progress`: a progress tracking class
+    * `OverProgress`: a progress tracking class which tracks the
+      aggregate of multiple `Progress` instances
+
+    Example:
+
+        for item in progressbar(items, "task name"):
+            ....
 '''
 
 from collections import namedtuple
@@ -21,13 +33,12 @@ from typing import Callable, Optional
 from icontract import ensure
 from typeguard import typechecked
 
-from cs.deco import decorator, uses_quiet
+from cs.deco import decorator, fmtdoc, uses_quiet
 from cs.logutils import debug, exception
 from cs.py.func import funcname
 from cs.queues import IterableQueue, QueueIterator
 from cs.resources import RunState, uses_runstate
 from cs.seq import seq
-from cs.threads import bg
 from cs.units import (
     transcribe_time,
     transcribe as transcribe_units,
@@ -38,7 +49,7 @@ from cs.units import (
 )
 from cs.upd import Upd, uses_upd, print  # pylint: disable=redefined-builtin
 
-__version__ = '20250412'
+__version__ = '20250528'
 
 DISTINFO = {
     'keywords': ["python2", "python3"],
@@ -50,9 +61,9 @@ DISTINFO = {
         'cs.deco',
         'cs.logutils',
         'cs.py.func',
+        'cs.queues',
         'cs.resources',
         'cs.seq',
-        'cs.threads',
         'cs.units',
         'cs.upd',
         'icontract',
@@ -67,7 +78,7 @@ DEFAULT_THROUGHPUT_WINDOW = 5
 DEFAULT_UPDATE_PERIOD = 0.3
 
 @functools.total_ordering
-class BaseProgress(object):
+class BaseProgress:
   ''' The base class for `Progress` and `OverProcess`
       with various common methods.
 
@@ -378,6 +389,7 @@ class BaseProgress(object):
   @contextmanager
   @uses_quiet
   @uses_upd
+  @fmtdoc
   def bar(
       self,
       label=None,
@@ -397,13 +409,14 @@ class BaseProgress(object):
         It returns the `UpdProxy` which displays the progress bar.
 
         Parameters:
-        * `label`: a label for the progress bar,
+        * `label`: an optional label for the progress bar,
           default from `self.name`.
-        * `statusfunc`: an optional function to compute the progress bar text
-          accepting `(self,label,width)`.
-        * `width`: an optional width expressing how wide the progress bar
-          text may be.
-          The default comes from the `proxy.width` property.
+        * `insert_pos`: where to insert the progress bar within the `cs.Upd`,
+          default `1`
+        * `poll`: an optional callable which will receive `self`,
+          which can be used to update the progress state before
+          updating the progress bar display; useful if the progress
+          should be updates from some other programme state
         * `recent_window`: optional timeframe to define "recent" in seconds;
           if the default `statusfunc` (`Progress.status`) is used
           this is passed to it
@@ -412,11 +425,15 @@ class BaseProgress(object):
           this may also be a `bool`, which if true will use `Upd.print`
           in order to interoperate with `Upd`.
         * `stalled`: optional string to replace the word `'stalled'`
-          in the status line; for a worked this might be betteer as `'idle'`
-        * `insert_pos`: where to insert the progress bar, default `1`
-        * `poll`: an optional callable accepting a `BaseProgress`
-          which can be used to update the progress state before
-          updating the progress bar display
+          in the status line; for a worker this might be better as `'idle'`
+        * `statusfunc`: an optional function to compute the progress bar text
+          accepting `(self,label,width)`; default `Progress.status`
+        * `update_period`: an optional frequency with which to update the display,
+          default from `DEFAULT_UPDATE_PERIOD` ({DEFAULT_UPDATE_PERIOD}s);
+          if set to `0` then the display is updated whenever `self` is updated
+        * `width`: an optional width expressing how wide the progress bar
+          text may be.
+          The default comes from the `proxy.width` property.
 
         Example use:
 
@@ -459,7 +476,7 @@ class BaseProgress(object):
 
     cancel_ticker = False
 
-    def ticker():
+    def _ticker():
       ''' Worker to update the progress bar every `update_period` seconds.
       '''
       time.sleep(update_period)
@@ -467,8 +484,6 @@ class BaseProgress(object):
         update(self, None)
         time.sleep(update_period)
 
-    if update_period == 0:
-      self.notify_update.add(update)
     try:
       start_pos = self.position
       with upd.insert(
@@ -477,8 +492,12 @@ class BaseProgress(object):
           text_auto=text_auto,
       ) as proxy:
         update(self, None)
-        if update_period > 0:
-          bg(ticker, daemon=True)
+        if update_period == 0:
+          # update every time the Progress is updated
+          self.notify_update.add(update)
+        elif update_period > 0:
+          # update every update_period seconds
+          Thread(target=_ticker, name=f'{label}-ticker', daemon=True).start()
         yield proxy
     finally:
       cancel_ticker = True
@@ -531,7 +550,7 @@ class BaseProgress(object):
         * `cancelled`: an optional callable to test for iteration cancellation
         Other parameters are passed to `Progress.bar`.
 
-        Example use:
+        Example uses:
 
             from cs.units import DECIMAL_SCALE
             rows = [some list of data]
@@ -539,17 +558,17 @@ class BaseProgress(object):
             for row in P.iterbar(rows, incfirst=True):
                 ... do something with each row ...
 
-            f = open(data_filename, 'rb')
-            datalen = os.stat(f).st_size
-            def readfrom(f):
-                while True:
-                    bs = f.read(65536)
-                    if not bs:
-                        break
-                    yield bs
-            P = Progress(total=datalen)
-            for bs in P.iterbar(readfrom(f), itemlenfunc=len):
-                ... process the file data in bs ...
+            with open(data_filename, 'rb') as f:
+                datalen = os.stat(f).st_size
+                def readfrom(f):
+                    while True:
+                        bs = f.read(65536)
+                        if not bs:
+                            break
+                        yield bs
+                P = Progress(total=datalen)
+                for bs in P.iterbar(readfrom(f), itemlenfunc=len):
+                    ... process the file data in bs ...
     '''
     if cancelled is None:
       cancelled = lambda: runstate.cancelled
@@ -570,14 +589,23 @@ class BaseProgress(object):
             proxy.text = None
 
   def qbar(self, label=None, **iterbar_kw) -> QueueIterator:
-    ''' Set up a progress bar, return a `QueueIterator` for receiving items.
-        This is a shim for `Progress.iterbar` which dispatches a
-        worker to iterate a queue which received items placed on
-        the queue.
+    ''' Set up a progress bar, return a closeable `Queue`-like object
+        for receiving items. This is a shim for `Progress.iterbar`
+        which dispatches a worker to iterate items put onto a queue.
+
+        Example:
+
+            Q = Progress.qbar("label")
+            try:
+                ... do work, calling Q.put(item) ...
+            finally:
+                Q.close()
     '''
     Q = IterableQueue(name=label)
 
     def qbar_worker():
+      ''' Consume the items from `Q`, updating the progress bar.
+      '''
       for _ in self.iterbar(Q, label=label, **iterbar_kw):
         pass
 
@@ -808,7 +836,7 @@ class Progress(BaseProgress):
     positions = self._positions
     # scan for first item still in time window,
     # never discard the last 2 positions
-    for ndx in range(0, len(positions) - 1):
+    for ndx in range(len(positions) - 1):
       posn = positions[ndx]
       if posn.time >= oldest:
         # this is the first element to keep, discard preceeding (if any)
@@ -849,8 +877,7 @@ class Progress(BaseProgress):
       return None
     now = time.time()
     time0 = now - time_window
-    if time0 < self.start_time:
-      time0 = self.start_time
+    time0 = max(time0, self.start_time)
     # lowest time and position
     # low_time will be time0
     # low_pos will be the matching position, probably interpolated
@@ -1045,11 +1072,14 @@ def progressbar(
     total=None,
     units_scale=UNSCALED_SCALE,
     upd: Upd,
+    report_print=None,
     **iterbar_kw
 ):
   ''' Convenience function to construct and run a `Progress.iterbar`
       wrapping the iterable `it`,
       issuing and withdrawing a progress bar during the iteration.
+      If there is no current `Upd` instance or it is disabled, this
+      returns `it` directly.
 
       Parameters:
       * `it`: the iterable to consume
@@ -1070,17 +1100,18 @@ def progressbar(
           for row in progressbar(rows):
               ... do something with row ...
   '''
-  if upd is None or upd.disabled:
-    yield from it
-  else:
-    if total is None:
-      try:
-        total = len(it)
-      except TypeError:
-        total = None
-    yield from Progress(
-        name=label, position=position, total=total, units_scale=units_scale
-    ).iterbar(it, **iterbar_kw)
+  if not report_print and (upd is None or upd.disabled):
+    return it
+  if total is None:
+    try:
+      total = len(it)
+    except TypeError:
+      total = None
+  return Progress(
+      name=label, position=position, total=total, units_scale=units_scale
+  ).iterbar(
+      it, report_print=report_print, **iterbar_kw
+  )
 
 @decorator
 def auto_progressbar(func, label=None, report_print=False):