fix: address PR review (gemini + CodeQL)

wolph · wolph · commit 7a0e2d265c7d · 2026-06-22T03:42:53.000+02:00
- Restore public previous_value semantics (value before the last update()
  call); the gate now uses a separate private _last_drawn_value for its
  pixel check (gemini: backward compatibility).
- Only back off _gate_step once calibrated, preventing exponential growth
  of the step before calibration (gemini: performance).
- Update gate-step tests for the calibrated back-off + add an uncalibrated
  no-growth test.
- Avoid mixed import of progressbar in tests; comment bench.py teardown
  excepts (CodeQL).
diff --git a/benchmarks/bench.py b/benchmarks/bench.py
@@ -75,11 +75,13 @@ def close(self) -> None:
             self.file.flush()
             self.file.close()
         except Exception:
+            # Teardown only: the slave fd may already be gone; nothing to do.
             pass
         self._stop.set()
         try:
             os.close(self._master)
         except OSError:
+            # Master already closed once the drain thread hit EOF; ignore.
             pass
         self._thread.join(timeout=1)
 
diff --git a/progressbar/bar.py b/progressbar/bar.py
@@ -86,6 +86,9 @@ class ProgressBarMixinBase(abc.ABC):
     value: NumberT
     #: Previous progress value
     previous_value: types.Optional[NumberT]
+    #: Value at the last actual redraw (internal; used by the update gate's
+    #: pixel check, kept separate from the public `previous_value`)
+    _last_drawn_value: types.Optional[NumberT]
     #: The minimum/start value for the progress bar
     min_value: NumberT
     #: Maximum (and final) value. Beyond this value an error will be raised
@@ -746,6 +749,9 @@ def init(self):
         used (again).
         """
         self.previous_value = None
+        # Value at the last actual redraw; used internally by the update gate's
+        # pixel check (distinct from the public `previous_value`).
+        self._last_drawn_value = None
         self.last_update_time = None
         self.start_time = None
         self.updates = 0
@@ -945,27 +951,26 @@ def __iter__(self):
                 return
             yield item  # first item at value == min_value (matches old code)
             value = self.value
-            # Prime `next_update` so the first item after the initial yield
-            # always calls `update()`. Time may have advanced during that body
-            # before the gate is calibrated, and we need the first call to
-            # set `_last_update_timer` and calibrate. Subsequent iterations
-            # use the back-off / calibrated gate from `self._next_update`.
             next_update = value
             update = self.update
             for item in iterator:
                 value += 1
-                self.value = value  # keep bar.value live (== current index)
                 # Before calibration, call `update()` every iteration and let
                 # `_needs_update()` make the real redraw decision (exactly as
                 # the manual path does: `gated_out` is False until calibrated).
                 # Consulting `_next_update` pre-calibration could skip redraws
-                # the ungated bar renders, because `_recompute_gate`'s back-off
-                # grows `_gate_step` geometrically before any real timing
-                # measurement exists. After calibration the measured step is
-                # bounded to one min_poll_interval window and is safe to skip.
+                # the ungated bar renders. After calibration the measured step
+                # is bounded to one min_poll_interval window and is safe to
+                # skip. Calling `update()` (rather than pre-setting
+                # `self.value`) lets it record the prior value in the public
+                # `previous_value`, preserving its original semantics.
                 if not self._gate_calibrated or value >= next_update:
                     update(value)
                     next_update = self._next_update
+                else:
+                    # Gated out: keep bar.value live without entering the
+                    # redraw machinery (no `previous_value`/redraw change).
+                    self.value = value
                 yield item
             self.finish()
         except GeneratorExit:
@@ -1026,15 +1031,15 @@ def _needs_update(self):
             # There's no terminal-width threshold to compute for an unknown
             # length, so redraw whenever the value advanced (still rate
             # limited by the min_poll_interval check above)
-            return self.value != self.previous_value
+            return self.value != self._last_drawn_value
 
         # Update if value increment is not large enough to
         # add more bars to progressbar (according to current
         # terminal width)
         with contextlib.suppress(Exception):
             divisor: float = self.max_value / self.term_width  # type: ignore
             value_divisor = self.value // divisor  # type: ignore
-            pvalue_divisor = self.previous_value // divisor  # type: ignore
+            pvalue_divisor = self._last_drawn_value // divisor  # type: ignore
             if value_divisor != pvalue_divisor:
                 return True
         # No need to redraw yet
@@ -1069,14 +1074,15 @@ def _recompute_gate(self, value: NumberT) -> None:
             self._gate_last_value = value
             # A real timing measurement: the gate can now safely skip calls.
             self._gate_calibrated = True
-        else:
-            # No redraw happened: we checked too early, so back off (double
-            # the step). We deliberately do NOT calibrate here. Activating the
-            # gate without a real timing measurement can overshoot
-            # `_next_update` and permanently drop redraws the baseline would
-            # render. The gate is therefore only ever calibrated by the redraw
-            # branch above, which sizes the step from a measured rate bounded
-            # to one `min_poll_interval` window.
+        elif self._gate_calibrated:
+            # No redraw happened: we checked too early, so back off (double the
+            # step). Only do this once calibrated — before calibration the
+            # gate is inactive and `update()` runs every iteration, so doubling
+            # here would grow `_gate_step` exponentially with the iteration
+            # count for no benefit (the value is never consulted). We also
+            # never calibrate in this branch: activating the gate without a
+            # real timing measurement can overshoot `_next_update` and drop
+            # redraws the baseline would render.
             self._gate_step = max(1, self._gate_step * 2)
             self._gate_last_value = value
         self._next_update = value + self._gate_step
@@ -1110,6 +1116,10 @@ def update(
                 else:
                     value = typing.cast(NumberT, self.max_value)
 
+            # `previous_value` keeps its original public meaning: the value
+            # before this update() call. The gate uses a separate private
+            # `_last_drawn_value` (set on redraw) for its pixel check.
+            self.previous_value = self.value
             self.value = value
 
         # Save the updated values for dynamic messages (skip the call and the
@@ -1131,12 +1141,12 @@ def update(
             try:
                 self._update_parents(value)
             finally:
-                # `previous_value` is the value at the last *redraw*, so the
+                # `_last_drawn_value` is the value at the last *redraw*, so the
                 # pixel check in `_needs_update` still detects boundary
                 # crossings even when the gate skipped intermediate updates.
                 # Setting it in finally ensures _needs_update() never re-fires
-                # due to a stale previous_value after a failed draw attempt.
-                self.previous_value = self.value
+                # due to a stale value after a failed draw attempt.
+                self._last_drawn_value = self.value
         if self._gate_enabled:
             self._recompute_gate(self.value)
 
diff --git a/tests/test_fastpath.py b/tests/test_fastpath.py
@@ -205,6 +205,7 @@ def test_gate_state_initialized():
 
 def test_recompute_gate_grows_step_when_no_redraw():
     bar = progressbar.ProgressBar(max_value=10**9)
+    bar._gate_calibrated = True  # back-off only applies once calibrated
     bar._gate_step = 4
     bar._gate_last_value = 0
     bar._gate_last_timer = 100.0
@@ -214,6 +215,19 @@ def test_recompute_gate_grows_step_when_no_redraw():
     assert bar._next_update == 50 + 8
 
 
+def test_recompute_gate_no_backoff_before_calibration():
+    # Before calibration the gate is inactive and update() runs every
+    # iteration; doubling here would grow _gate_step exponentially with the
+    # iteration count, so the back-off must NOT fire while uncalibrated.
+    bar = progressbar.ProgressBar(max_value=10**9)
+    assert bar._gate_calibrated is False
+    bar._gate_step = 4
+    bar._gate_last_timer = 100.0
+    bar._last_update_timer = 100.0  # no redraw happened
+    bar._recompute_gate(50)
+    assert bar._gate_step == 4  # unchanged (no exponential growth)
+
+
 def test_recompute_gate_targets_min_poll_interval():
     bar = progressbar.ProgressBar(max_value=10**9)
     bar.min_poll_interval = 0.05
@@ -257,34 +271,23 @@ def spy(value):
     assert bar.previous_value in drawn
 
 
-def test_previous_value_not_set_on_skipped_update(monkeypatch):
-    """previous_value must only advance when a redraw actually happens.
+def test_last_drawn_value_pinned_on_skipped_update(monkeypatch):
+    """The gate's pixel reference advances only when a redraw happens.
 
-    Old code sequence for update(v):
-        self.previous_value = self.value   # always
-        self.value = v
-        if _needs_update(): draw           # maybe
+    `_last_drawn_value` (the private pixel reference used by `_needs_update`)
+    must stay pinned to the value at the last actual draw, even as later
+    `update()` calls advance `self.value` without redrawing. The public
+    `previous_value` keeps its original meaning: the value before the most
+    recent `update()` call.
 
-    New code sequence:
-        self.value = v
-        if _needs_update():
-            draw
-            self.previous_value = self.value   # only on draw
-
-    After a draw at value=3 (starting from 0) and two consecutive skips
-    at value=4 then value=5:
-        Old: previous_value == 4  (set at the start of update(5))
-        New: previous_value == 3  (pinned to the drawn value)
-
-    The new semantics are required so that _needs_update()'s pixel-threshold
-    check measures "pixels since last *draw*" rather than "pixels since last
-    *call*".
+    After a draw at value=3 (from 0) and two rate-limited skips at 4 then 5:
+        _last_drawn_value == 3  (pinned to the drawn value, for pixel check)
+        previous_value     == 4  (value before the update(5) call)
     """
     from progressbar import bar as bar_module
 
-    # Advance the timer a lot during start and first update so it draws,
-    # then freeze it so subsequent updates are skipped.
-    # Start is called once; _needs_update reads timer once per update call.
+    # Freeze-then-advance clock: start at 0, jump to 1.0 so update(3) draws,
+    # then keep it at 1.0 so subsequent updates are rate-limited (skipped).
     _time: list[float] = [0.0]
 
     def timer() -> float:
@@ -295,25 +298,24 @@ def timer() -> float:
     bar = progressbar.ProgressBar(max_value=100, fd=RecordingTTY())
     bar.start()  # _last_update_timer = 0.0
 
-    # Advance time far past min_poll_interval (0.05 s) => update(3) will draw.
+    # Advance time far past min_poll_interval (0.05 s) => update(3) draws.
     _time[0] = 1.0
     bar.update(3)
-    # Redraw happened; _last_update_timer is now 1.0.
-    # Old code: previous_value was 0 (self.value before assignment) pre-draw.
-    # New code: previous_value set to 3 (self.value after draw).
-
-    # Freeze time: delta = 0 => _needs_update() returns False for next calls.
-    # (No need to touch _last_update_timer; next timer() read returns 1.0.)
-
-    bar.update(4)  # skipped: old sets prev=3, val=4; new: val=4, prev stays
-    bar.update(5)  # skipped: old sets prev=4, val=5; new: val=5, prev stays
-
-    # New semantics: previous_value == 3 (the value at the last actual draw).
-    # Old semantics: previous_value == 4 (set at the start of update(5)).
-    assert bar.previous_value == 3, (
-        f'previous_value should be pinned to last-drawn value (3), '
-        f'got {bar.previous_value!r}'
+    assert bar._last_drawn_value == 3  # a redraw happened at value 3
+
+    # Time frozen at 1.0: delta == 0 => _needs_update() returns False, so the
+    # next updates advance self.value but do not redraw.
+    bar.update(4)
+    bar.update(5)
+
+    # Pixel reference stays at the last drawn value; public previous_value
+    # tracks the value before the most recent update() call.
+    assert bar._last_drawn_value == 3, (
+        f'_last_drawn_value should stay at last-drawn (3), '
+        f'got {bar._last_drawn_value!r}'
     )
+    assert bar.value == 5  # liveness preserved on the manual path
+    assert bar.previous_value == 4  # value before update(5)
 
 
 def test_gate_disabled_skips_recompute():
@@ -572,13 +574,13 @@ def test_iterator_overhead_is_low():
 def test_no_color_fast_path_and_ansi():
     # Render-cost optimization adds a no-ESC fast path to no_color/len_color.
     # It must be identical to the regex path for both plain and ANSI input.
-    from progressbar import utils
+    utils = progressbar.utils
 
-    # Fast path (no ESC byte) — returned unchanged, str and bytes.
+    # Fast path (no ESC byte): returned unchanged, str and bytes.
     assert utils.no_color('plain text') == 'plain text'
     assert utils.no_color(b'plain bytes') == b'plain bytes'
     assert utils.len_color('plain') == 5
-    # Regex path (ANSI present) — escape sequences stripped, str and bytes.
+    # Regex path (ANSI present): escape sequences stripped, str and bytes.
     assert utils.no_color('\x1b[31mred\x1b[0m') == 'red'
     assert utils.no_color(b'\x1b[31mred\x1b[0m') == b'red'
     assert utils.len_color('\x1b[1mbold\x1b[0m') == 4
