Introducing ProgressBarCounter.stopped

Include a distinction for counters that have stopped (time_elapsed
no longer increments and Bar formatter stops running in the case
of unknown totals). This allows bars to better handle cases where
a counter doesn't complete properly and terminates in some error
state the developer cares about.

Added breaking task to a-lot-of-parallel-tasks.py example.

Author: Ken Odegard

examples/progress-bar/a-lot-of-parallel-tasks.py

@@ -17,9 +17,24 @@ def main():
     ) as pb:
 
         def run_task(label, total, sleep_time):
+            """Complete a normal run."""
             for i in pb(range(total), label=label):
                 time.sleep(sleep_time)
 
+        def stop_task(label, total, sleep_time):
+            """Stop at some random index.
+
+            Breaking out of iteration at some stop index mimics how progress
+            bars behave in cases where errors are raised.
+            """
+            stop_i = random.randrange(total)
+            bar = pb(range(total), label=label)
+            for i in bar:
+                if stop_i == i:
+                    bar.label = f"{label} BREAK"
+                    break
+                time.sleep(sleep_time)
+
         threads = []
 
         for i in range(160):
@@ -28,7 +43,10 @@ def run_task(label, total, sleep_time):
             sleep_time = random.randrange(5, 20) / 100.0
 
             threads.append(
-                threading.Thread(target=run_task, args=(label, total, sleep_time))
+                threading.Thread(
+                    target=random.choice((run_task, stop_task)),
+                    args=(label, total, sleep_time),
+                )
             )
 
         for t in threads:

prompt_toolkit/shortcuts/progress_bar/base.py

@@ -56,12 +56,12 @@
 try:
     import contextvars
 except ImportError:
-    from prompt_toolkit.eventloop import dummy_contextvars as contextvars  # type: ignore
+    from prompt_toolkit.eventloop import (  # type: ignore
+        dummy_contextvars as contextvars,
+    )
 
 
-__all__ = [
-    "ProgressBar",
-]
+__all__ = ["ProgressBar"]
 
 E = KeyPressEvent
 
@@ -342,13 +342,20 @@ def __init__(
             self.total = total
 
     def __iter__(self) -> Iterable[_CounterItem]:
-        try:
-            if self.data is not None:
+        if self.data is not None:
+            try:
                 for item in self.data:
                     yield item
                     self.item_completed()
-        finally:
-            self.done = True
+
+                # Only done if we iterate to the very end.
+                self.done = True
+            finally:
+                # Ensure counter has stopped even if we did not iterate to the
+                # end (e.g. break or exceptions).
+                self.stopped = True
+        else:
+            raise NotImplementedError("No data defined to iterate over.")
 
     def item_completed(self) -> None:
         """
@@ -361,18 +368,52 @@ def item_completed(self) -> None:
 
     @property
     def done(self) -> bool:
+        """Whether a counter has been completed.
+
+        Done counter have been stopped (see stopped) and removed depending on
+        remove_when_done value.
+
+        Contrast this with stopped. A stopped counter may be terminated before
+        100% completion. A done counter has reached its 100% completion.
+        """
         return self._done
 
     @done.setter
     def done(self, value: bool) -> None:
         self._done = value
-
-        # If done then store the stop_time, otherwise clear.
-        self.stop_time = datetime.datetime.now() if value else None
+        self.stopped = value
 
         if value and self.remove_when_done:
             self.progress_bar.counters.remove(self)
 
+    @property
+    def stopped(self) -> bool:
+        """Whether a counter has been stopped.
+
+        Stopped counters no longer have increasing time_elapsed. This distinction is
+        also used to prevent the Bar formatter with unknown totals from continuing to run.
+
+        A stopped counter (but not done) can be used to signal that a given counter has
+        encountered an error but allows other counters to continue
+        (e.g. download X of Y failed). Given how only done counters are removed
+        (see remove_when_done) this can help aggregate failures from a large number of
+        successes.
+
+        Contrast this with done. A done counter has reached its 100% completion.
+        A stopped counter may be terminated before 100% completion.
+        """
+        return self.stop_time is not None
+
+    @stopped.setter
+    def stopped(self, value: bool):
+        if value:
+            # This counter has not already been stopped.
+            if not self.stop_time:
+                self.stop_time = datetime.datetime.now()
+        else:
+            # Clearing any previously set stop_time.
+            self.stop_time = None
+
     @property
     def percentage(self) -> float:
         if self.total is None:

prompt_toolkit/shortcuts/progress_bar/formatters.py

@@ -177,21 +177,31 @@ def format(
         progress: "ProgressBarCounter[object]",
         width: int,
     ) -> AnyFormattedText:
+        if progress.done or progress.total or progress.stopped:
+            sym_a, sym_b, sym_c = self.sym_a, self.sym_b, self.sym_c
+
+            # Compute pb_a based on done, total, or stopped states.
+            if progress.done:
+                # 100% completed irrelevant of how much was actually marked as completed.
+                percent = 1.0
+            else:
+                # Show percentage completed.
+                percent = progress.percentage / 100
+        else:
+            # Total is unknown and bar is still running.
+            sym_a, sym_b, sym_c = self.sym_c, self.unknown, self.sym_c
 
-        # Subtract left, bar_b and right.
-        width -= get_cwidth(self.start + self.sym_b + self.end)
+            # Compute percent based on the time.
+            percent = time.time() * 20 % 100 / 100
 
-        if progress.total:
-            pb_a = int(progress.percentage * width / 100)
-            bar_a = self.sym_a * pb_a
-            bar_b = self.sym_b
-            bar_c = self.sym_c * (width - pb_a)
-        else:
-            # Total is unknown.
-            pb_a = int(time.time() * 20 % 100 * width / 100)
-            bar_a = self.sym_c * pb_a
-            bar_b = self.unknown
-            bar_c = self.sym_c * (width - pb_a)
+        # Subtract left, sym_b, and right.
+        width -= get_cwidth(self.start + sym_b + self.end)
+
+        # Scale percent by width
+        pb_a = int(percent * width)
+        bar_a = sym_a * pb_a
+        bar_b = sym_b
+        bar_c = sym_c * (width - pb_a)
 
         return HTML(self.template).format(
             start=self.start, end=self.end, bar_a=bar_a, bar_b=bar_b, bar_c=bar_c