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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cs-progress
-Version: 20250306
+Version: 20250412
 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>
@@ -13,10 +13,11 @@ 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.logutils>=20250306
+Requires-Dist: cs.logutils>=20250323
 Requires-Dist: cs.py.func>=20240630
+Requires-Dist: cs.resources>=20250325
 Requires-Dist: cs.seq>=20250306
-Requires-Dist: cs.threads>=20250306
+Requires-Dist: cs.threads>=20250325
 Requires-Dist: cs.units
 Requires-Dist: cs.upd>=20240630
 Requires-Dist: icontract
@@ -29,26 +30,20 @@ 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 20250306*:
-* Progress: new .qbar() method to make a progress bar and return a queue on which to put items to track.
-* progressbar: return the iterable unchanged if upd is None or disabled.
-* BaseProgress.iterbar: new optional cancelled parameter for a cancellation test callable, passed through by progressbar etc.
-
-## <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`
+*Latest release 20250412*:
+Bugfix progressbar: fix early return if no active Upd.
 
-The base class for `Progress` and `OverProcess`
-with various common methods.
+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`
+  with various common methods.
 
-Note that durations are in seconds
-and that absolute time is in seconds since the UNIX epoch
-(the basis of `time.time()`).
+  Note that durations are in seconds
+  and that absolute time is in seconds since the UNIX epoch
+  (the basis of `time.time()`).
 
 *`BaseProgress.__init__(self, name=None, start_time=None, units_scale=None)`*:
 Initialise a progress instance.
@@ -83,7 +78,7 @@ 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 0x1057109a0>, **kw)`*:
+*`BaseProgress.bar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x10c191da0>, **kw)`*:
 A context manager to create and withdraw a progress bar.
 It returns the `UpdProxy` which displays the progress bar.
 
@@ -130,7 +125,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, **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 0x10c192200>, **bar_kw)`*:
 An iterable progress bar: a generator yielding values
 from the iterable `it` while updating a progress bar.
 
@@ -243,55 +238,52 @@ 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
 
 *`CheckPoint.position`*:
 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.
-
-AN OverProgress instance has an attribute ``notify_update`` which
-is a set of callables.
-Whenever the position of a subsidiary `Progress` is updated,
-each of these will be called with the `Progress` instance and `None`.
-
-Example:
-
-    >>> P = OverProgress(name="over")
-    >>> P1 = Progress(name="progress1", position=12)
-    >>> P1.total = 100
-    >>> P1.advance(7)
-    >>> P2 = Progress(name="progress2", position=20)
-    >>> P2.total = 50
-    >>> P2.advance(9)
-    >>> P.add(P1)
-    >>> P.add(P2)
-    >>> P1.total
-    100
-    >>> P2.total
-    50
-    >>> P.total
-    150
-    >>> P1.start
-    12
-    >>> P2.start
-    20
-    >>> P.start
-    0
-    >>> P1.position
-    19
-    >>> P2.position
-    29
-    >>> P.position
-    16
+- <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.
+  Whenever the position of a subsidiary `Progress` is updated,
+  each of these will be called with the `Progress` instance and `None`.
+
+  Example:
+
+      >>> P = OverProgress(name="over")
+      >>> P1 = Progress(name="progress1", position=12)
+      >>> P1.total = 100
+      >>> P1.advance(7)
+      >>> P2 = Progress(name="progress2", position=20)
+      >>> P2.total = 50
+      >>> P2.advance(9)
+      >>> P.add(P1)
+      >>> P.add(P2)
+      >>> P1.total
+      100
+      >>> P2.total
+      50
+      >>> P.total
+      150
+      >>> P1.start
+      12
+      >>> P2.start
+      20
+      >>> P.start
+      0
+      >>> P1.position
+      19
+      >>> P2.position
+      29
+      >>> P.position
+      16
 
 *`OverProgress.add(self, subprogress)`*:
 Add a subsidairy `Progress` to the contributing set.
@@ -317,46 +309,43 @@ 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.
-
-Example:
-
-    >>> P = Progress(name="example")
-    >>> P                         #doctest: +ELLIPSIS
-    Progress(name='example',start=0,position=0,start_time=...,throughput_window=None,total=None):[CheckPoint(time=..., position=0)]
-    >>> P.advance(5)
-    >>> P                         #doctest: +ELLIPSIS
-    Progress(name='example',start=0,position=5,start_time=...,throughput_window=None,total=None):[CheckPoint(time=..., position=0), CheckPoint(time=..., position=5)]
-    >>> P.total = 100
-    >>> P                         #doctest: +ELLIPSIS
-    Progress(name='example',start=0,position=5,start_time=...,throughput_window=None,total=100):[CheckPoint(time=..., position=0), CheckPoint(time=..., position=5)]
-
-A Progress instance has an attribute ``notify_update`` which
-is a set of callables. Whenever the position is updated, each
-of these will be called with the `Progress` instance and the
-latest `CheckPoint`.
-
-`Progress` objects also make a small pretense of being an integer.
-The expression `int(progress)` returns the current position,
-and `+=` and `-=` adjust the position.
-
-This is convenient for coding, but importantly it is also
-useful for discretionary use of a Progress with some other
-object.
-If you want to make a lightweight `Progress` capable class
-you can set a position attribute to an `int`
-and manipulate it carefully using `+=` and `-=` entirely.
-If you decide to incur the cost of maintaining a `Progress` object
-you can slot it in:
-
-    # initial setup with just an int
-    my_thing.amount = 0
-
-    # later, or on some option, use a Progress instance
-    my_thing.amount = Progress(my_thing.amount)
+- <a name="Progress"></a>`Class `Progress(BaseProgress)`: A progress counter to track task completion with various utility methods.
+
+  Example:
+
+      >>> P = Progress(name="example")
+      >>> P                         #doctest: +ELLIPSIS
+      Progress(name='example',start=0,position=0,start_time=...,throughput_window=None,total=None):[CheckPoint(time=..., position=0)]
+      >>> P.advance(5)
+      >>> P                         #doctest: +ELLIPSIS
+      Progress(name='example',start=0,position=5,start_time=...,throughput_window=None,total=None):[CheckPoint(time=..., position=0), CheckPoint(time=..., position=5)]
+      >>> P.total = 100
+      >>> P                         #doctest: +ELLIPSIS
+      Progress(name='example',start=0,position=5,start_time=...,throughput_window=None,total=100):[CheckPoint(time=..., position=0), CheckPoint(time=..., position=5)]
+
+  A Progress instance has an attribute ``notify_update`` which
+  is a set of callables. Whenever the position is updated, each
+  of these will be called with the `Progress` instance and the
+  latest `CheckPoint`.
+
+  `Progress` objects also make a small pretense of being an integer.
+  The expression `int(progress)` returns the current position,
+  and `+=` and `-=` adjust the position.
+
+  This is convenient for coding, but importantly it is also
+  useful for discretionary use of a Progress with some other
+  object.
+  If you want to make a lightweight `Progress` capable class
+  you can set a position attribute to an `int`
+  and manipulate it carefully using `+=` and `-=` entirely.
+  If you decide to incur the cost of maintaining a `Progress` object
+  you can slot it in:
+
+      # initial setup with just an int
+      my_thing.amount = 0
+
+      # later, or on some option, use a Progress instance
+      my_thing.amount = Progress(my_thing.amount)
 
 *`Progress.__init__(self, name: Optional[str] = None, *, position: Optional[float] = None, start: Optional[float] = None, start_time: Optional[float] = None, throughput_window: Optional[int] = None, total: Optional[float] = None, units_scale=None)`*:
 Initialise the Progesss object.
@@ -444,39 +433,39 @@ 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`
+  wrapping the iterable `it`,
+  issuing and withdrawing a progress bar during the iteration.
 
-## <a name="progressbar"></a>`progressbar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x105712660>, **kw)`
+  Parameters:
+  * `it`: the iterable to consume
+  * `label`: optional label, doubles as the `Progress.name`
+  * `position`: optional starting position
+  * `total`: optional value for `Progress.total`,
+    default from `len(it)` if supported.
+  * `units_scale`: optional units scale for `Progress`,
+    default `UNSCALED_SCALE`
 
-Convenience function to construct and run a `Progress.iterbar`
-wrapping the iterable `it`,
-issuing and withdrawing a progress bar during the iteration.
+  If `total` is `None` and `it` supports `len()`
+  then the `Progress.total` is set from it.
 
-Parameters:
-* `it`: the iterable to consume
-* `label`: optional label, doubles as the `Progress.name`
-* `position`: optional starting position
-* `total`: optional value for `Progress.total`,
-  default from `len(it)` if supported.
-* `units_scale`: optional units scale for `Progress`,
-  default `UNSCALED_SCALE`
-
-If `total` is `None` and `it` supports `len()`
-then the `Progress.total` is set from it.
-
-All arguments are passed through to `Progress.iterbar`.
+  All arguments are passed through to `Progress.iterbar`.
 
-Example use:
+  Example use:
 
-    for row in progressbar(rows):
-        ... do something with row ...
+      for row in progressbar(rows):
+          ... do something with row ...
+- <a name="selftest"></a>`selftest(argv)`: Exercise some of the functionality.
 
-## <a name="selftest"></a>`selftest(argv)`
+# Release Log
 
-Exercise some of the functionality.
 
-# Release Log
 
+*Release 20250412*:
+Bugfix progressbar: fix early return if no active Upd.
 
+*Release 20250325*:
+BaseProgress.iterbar: use @uses_runstate, accept a runstate parameter overridable by the cancelled param.
 
 *Release 20250306*:
 * Progress: new .qbar() method to make a progress bar and return a queue on which to put items to track.

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

@@ -10,10 +10,11 @@ keywords = [
 ]
 dependencies = [
     "cs.deco>=20250306",
-    "cs.logutils>=20250306",
+    "cs.logutils>=20250323",
     "cs.py.func>=20240630",
+    "cs.resources>=20250325",
     "cs.seq>=20250306",
-    "cs.threads>=20250306",
+    "cs.threads>=20250325",
     "cs.units",
     "cs.upd>=20240630",
     "icontract",
@@ -28,7 +29,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
 ]
-version = "20250306"
+version = "20250412"
 
 [project.license]
 text = "GNU General Public License v3 or later (GPLv3+)"
@@ -44,26 +45,20 @@ text = """
 A progress tracker with methods for throughput, ETA and update notification;
 also a compound progress meter composed from other progress meters.
 
-*Latest release 20250306*:
-* Progress: new .qbar() method to make a progress bar and return a queue on which to put items to track.
-* progressbar: return the iterable unchanged if upd is None or disabled.
-* BaseProgress.iterbar: new optional cancelled parameter for a cancellation test callable, passed through by progressbar etc.
-
-## <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`
+*Latest release 20250412*:
+Bugfix progressbar: fix early return if no active Upd.
 
-The base class for `Progress` and `OverProcess`
-with various common methods.
+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`
+  with various common methods.
 
-Note that durations are in seconds
-and that absolute time is in seconds since the UNIX epoch
-(the basis of `time.time()`).
+  Note that durations are in seconds
+  and that absolute time is in seconds since the UNIX epoch
+  (the basis of `time.time()`).
 
 *`BaseProgress.__init__(self, name=None, start_time=None, units_scale=None)`*:
 Initialise a progress instance.
@@ -98,7 +93,7 @@ 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 0x1057109a0>, **kw)`*:
+*`BaseProgress.bar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x10c191da0>, **kw)`*:
 A context manager to create and withdraw a progress bar.
 It returns the `UpdProxy` which displays the progress bar.
 
@@ -145,7 +140,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, **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 0x10c192200>, **bar_kw)`*:
 An iterable progress bar: a generator yielding values
 from the iterable `it` while updating a progress bar.
 
@@ -258,55 +253,52 @@ 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
 
 *`CheckPoint.position`*:
 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.
-
-AN OverProgress instance has an attribute ``notify_update`` which
-is a set of callables.
-Whenever the position of a subsidiary `Progress` is updated,
-each of these will be called with the `Progress` instance and `None`.
-
-Example:
-
-    >>> P = OverProgress(name=\"over\")
-    >>> P1 = Progress(name=\"progress1\", position=12)
-    >>> P1.total = 100
-    >>> P1.advance(7)
-    >>> P2 = Progress(name=\"progress2\", position=20)
-    >>> P2.total = 50
-    >>> P2.advance(9)
-    >>> P.add(P1)
-    >>> P.add(P2)
-    >>> P1.total
-    100
-    >>> P2.total
-    50
-    >>> P.total
-    150
-    >>> P1.start
-    12
-    >>> P2.start
-    20
-    >>> P.start
-    0
-    >>> P1.position
-    19
-    >>> P2.position
-    29
-    >>> P.position
-    16
+- <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.
+  Whenever the position of a subsidiary `Progress` is updated,
+  each of these will be called with the `Progress` instance and `None`.
+
+  Example:
+
+      >>> P = OverProgress(name=\"over\")
+      >>> P1 = Progress(name=\"progress1\", position=12)
+      >>> P1.total = 100
+      >>> P1.advance(7)
+      >>> P2 = Progress(name=\"progress2\", position=20)
+      >>> P2.total = 50
+      >>> P2.advance(9)
+      >>> P.add(P1)
+      >>> P.add(P2)
+      >>> P1.total
+      100
+      >>> P2.total
+      50
+      >>> P.total
+      150
+      >>> P1.start
+      12
+      >>> P2.start
+      20
+      >>> P.start
+      0
+      >>> P1.position
+      19
+      >>> P2.position
+      29
+      >>> P.position
+      16
 
 *`OverProgress.add(self, subprogress)`*:
 Add a subsidairy `Progress` to the contributing set.
@@ -332,46 +324,43 @@ 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.
-
-Example:
-
-    >>> P = Progress(name=\"example\")
-    >>> P                         #doctest: +ELLIPSIS
-    Progress(name='example',start=0,position=0,start_time=...,throughput_window=None,total=None):[CheckPoint(time=..., position=0)]
-    >>> P.advance(5)
-    >>> P                         #doctest: +ELLIPSIS
-    Progress(name='example',start=0,position=5,start_time=...,throughput_window=None,total=None):[CheckPoint(time=..., position=0), CheckPoint(time=..., position=5)]
-    >>> P.total = 100
-    >>> P                         #doctest: +ELLIPSIS
-    Progress(name='example',start=0,position=5,start_time=...,throughput_window=None,total=100):[CheckPoint(time=..., position=0), CheckPoint(time=..., position=5)]
-
-A Progress instance has an attribute ``notify_update`` which
-is a set of callables. Whenever the position is updated, each
-of these will be called with the `Progress` instance and the
-latest `CheckPoint`.
-
-`Progress` objects also make a small pretense of being an integer.
-The expression `int(progress)` returns the current position,
-and `+=` and `-=` adjust the position.
-
-This is convenient for coding, but importantly it is also
-useful for discretionary use of a Progress with some other
-object.
-If you want to make a lightweight `Progress` capable class
-you can set a position attribute to an `int`
-and manipulate it carefully using `+=` and `-=` entirely.
-If you decide to incur the cost of maintaining a `Progress` object
-you can slot it in:
-
-    # initial setup with just an int
-    my_thing.amount = 0
-
-    # later, or on some option, use a Progress instance
-    my_thing.amount = Progress(my_thing.amount)
+- <a name=\"Progress\"></a>`Class `Progress(BaseProgress)`: A progress counter to track task completion with various utility methods.
+
+  Example:
+
+      >>> P = Progress(name=\"example\")
+      >>> P                         #doctest: +ELLIPSIS
+      Progress(name='example',start=0,position=0,start_time=...,throughput_window=None,total=None):[CheckPoint(time=..., position=0)]
+      >>> P.advance(5)
+      >>> P                         #doctest: +ELLIPSIS
+      Progress(name='example',start=0,position=5,start_time=...,throughput_window=None,total=None):[CheckPoint(time=..., position=0), CheckPoint(time=..., position=5)]
+      >>> P.total = 100
+      >>> P                         #doctest: +ELLIPSIS
+      Progress(name='example',start=0,position=5,start_time=...,throughput_window=None,total=100):[CheckPoint(time=..., position=0), CheckPoint(time=..., position=5)]
+
+  A Progress instance has an attribute ``notify_update`` which
+  is a set of callables. Whenever the position is updated, each
+  of these will be called with the `Progress` instance and the
+  latest `CheckPoint`.
+
+  `Progress` objects also make a small pretense of being an integer.
+  The expression `int(progress)` returns the current position,
+  and `+=` and `-=` adjust the position.
+
+  This is convenient for coding, but importantly it is also
+  useful for discretionary use of a Progress with some other
+  object.
+  If you want to make a lightweight `Progress` capable class
+  you can set a position attribute to an `int`
+  and manipulate it carefully using `+=` and `-=` entirely.
+  If you decide to incur the cost of maintaining a `Progress` object
+  you can slot it in:
+
+      # initial setup with just an int
+      my_thing.amount = 0
+
+      # later, or on some option, use a Progress instance
+      my_thing.amount = Progress(my_thing.amount)
 
 *`Progress.__init__(self, name: Optional[str] = None, *, position: Optional[float] = None, start: Optional[float] = None, start_time: Optional[float] = None, throughput_window: Optional[int] = None, total: Optional[float] = None, units_scale=None)`*:
 Initialise the Progesss object.
@@ -459,39 +448,39 @@ 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`
+  wrapping the iterable `it`,
+  issuing and withdrawing a progress bar during the iteration.
 
-## <a name=\"progressbar\"></a>`progressbar(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x105712660>, **kw)`
+  Parameters:
+  * `it`: the iterable to consume
+  * `label`: optional label, doubles as the `Progress.name`
+  * `position`: optional starting position
+  * `total`: optional value for `Progress.total`,
+    default from `len(it)` if supported.
+  * `units_scale`: optional units scale for `Progress`,
+    default `UNSCALED_SCALE`
 
-Convenience function to construct and run a `Progress.iterbar`
-wrapping the iterable `it`,
-issuing and withdrawing a progress bar during the iteration.
+  If `total` is `None` and `it` supports `len()`
+  then the `Progress.total` is set from it.
 
-Parameters:
-* `it`: the iterable to consume
-* `label`: optional label, doubles as the `Progress.name`
-* `position`: optional starting position
-* `total`: optional value for `Progress.total`,
-  default from `len(it)` if supported.
-* `units_scale`: optional units scale for `Progress`,
-  default `UNSCALED_SCALE`
-
-If `total` is `None` and `it` supports `len()`
-then the `Progress.total` is set from it.
-
-All arguments are passed through to `Progress.iterbar`.
+  All arguments are passed through to `Progress.iterbar`.
 
-Example use:
+  Example use:
 
-    for row in progressbar(rows):
-        ... do something with row ...
+      for row in progressbar(rows):
+          ... do something with row ...
+- <a name=\"selftest\"></a>`selftest(argv)`: Exercise some of the functionality.
 
-## <a name=\"selftest\"></a>`selftest(argv)`
+# Release Log
 
-Exercise some of the functionality.
 
-# Release Log
 
+*Release 20250412*:
+Bugfix progressbar: fix early return if no active Upd.
 
+*Release 20250325*:
+BaseProgress.iterbar: use @uses_runstate, accept a runstate parameter overridable by the cancelled param.
 
 *Release 20250306*:
 * Progress: new .qbar() method to make a progress bar and return a queue on which to put items to track.

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

@@ -25,6 +25,7 @@ from cs.deco import decorator, 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 (
@@ -37,7 +38,7 @@ from cs.units import (
 )
 from cs.upd import Upd, uses_upd, print  # pylint: disable=redefined-builtin
 
-__version__ = '20250306'
+__version__ = '20250412'
 
 DISTINFO = {
     'keywords': ["python2", "python3"],
@@ -49,6 +50,7 @@ DISTINFO = {
         'cs.deco',
         'cs.logutils',
         'cs.py.func',
+        'cs.resources',
         'cs.seq',
         'cs.threads',
         'cs.units',
@@ -493,6 +495,7 @@ class BaseProgress(object):
         )
 
   # pylint: disable=too-many-arguments,too-many-branches,too-many-locals
+  @uses_runstate
   def iterbar(
       self,
       it,
@@ -502,6 +505,7 @@ class BaseProgress(object):
       incfirst=False,
       update_period=DEFAULT_UPDATE_PERIOD,
       cancelled=None,
+      runstate: RunState,
       **bar_kw,
   ):
     ''' An iterable progress bar: a generator yielding values
@@ -547,6 +551,8 @@ class BaseProgress(object):
             for bs in P.iterbar(readfrom(f), itemlenfunc=len):
                 ... process the file data in bs ...
     '''
+    if cancelled is None:
+      cancelled = lambda: runstate.cancelled
     with self.bar(label, update_period=update_period, **bar_kw) as proxy:
       for item in it:
         if cancelled and cancelled():
@@ -1065,15 +1071,16 @@ def progressbar(
               ... do something with row ...
   '''
   if upd is None or upd.disabled:
-    return it
-  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)
+    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)
 
 @decorator
 def auto_progressbar(func, label=None, report_print=False):