Widen README progress animations

Author: wolph

docs/_static/progressbar-ergonomics.svg

@@ -18,8 +18,9 @@
 PERCENT_RE = re.compile(r'\b\d{1,3}%')
 POSTFIX_RE = re.compile(r'\b[A-Za-z_][\w-]*=[^\s,]+')
 LABEL_RE = re.compile(r'[A-Za-z][\w-]*:?')
-ANIMATION_FRAME_SECONDS = 0.12
-MAX_ANIMATION_FRAMES = 16
+ANIMATION_FRAME_SECONDS = 0.08
+MAX_ANIMATION_FRAMES = 24
+SVG_WIDTH = 1080
 
 
 @dataclass(frozen=True)
@@ -39,16 +40,16 @@ class Demo:
 import progressbar
 
 with progressbar.ProgressBar(
-    total=12,
+    total=24,
     desc='Build',
     fd=sys.stdout,
     redirect_stdout=True,
     line_breaks=False,
     is_terminal=True,
-    term_width=64,
+    term_width=112,
 ) as bar:
-    for step in range(12):
-        if step in {0, 4, 8}:
+    for step in range(24):
+        if step in {8, 16}:
             print(f'log: completed step {step}')
         bar.update(step + 1, force=True)
         time.sleep(0.005)
@@ -65,32 +66,35 @@ class Demo:
 fd = io.StringIO()
 multibar = progressbar.MultiBar(
     fd=fd,
-    total=12,
+    total=24,
     initial_format=None,
     finished_format=None,
     remove_finished=None,
     sort_reverse=False,
-    term_width=64,
+    term_width=112,
 )
 build = multibar['build']
 test = multibar['test']
-multibar.render(force=True, flush=True)
-fd.seek(0)
-fd.truncate(0)
 terminal_control_re = re.compile(r'\\x1b\\[[0-9;]*[A-Za-z]')
 
-for step in range(12):
-    build.update(step + 1, force=True)
-    test.update(step + 1, force=True)
-    fd.seek(0)
-    fd.truncate(0)
-    multibar.render(force=True, flush=True)
+def emit_frame():
     output = terminal_control_re.sub('', fd.getvalue())
     for line in output.split('\\r'):
         line = line.strip()
         if line:
             print(line)
     print('\f', end='')
+    fd.seek(0)
+    fd.truncate(0)
+
+multibar.render(force=True, flush=True)
+emit_frame()
+
+for step in range(24):
+    build.update(step + 1, force=True)
+    test.update(step + 1, force=True)
+    multibar.render(force=True, flush=True)
+    emit_frame()
 """,
     ),
     Demo(
@@ -105,9 +109,22 @@ class Demo:
     fd=sys.stdout,
     line_breaks=False,
     is_terminal=True,
-    term_width=64,
+    term_width=112,
 ) as bar:
-    for value in (3, 7, 12, 18, 25, 31, 40, 52):
+    for value in (
+        3,
+        7,
+        12,
+        18,
+        25,
+        31,
+        40,
+        52,
+        67,
+        83,
+        101,
+        124,
+    ):
         bar.update(value, force=True)
 """,
     ),
@@ -119,26 +136,19 @@ class Demo:
 import progressbar
 
 with progressbar.ProgressBar(
-    total=4096,
+    total=8192,
     desc='Items',
     unit='B',
     unit_scale=True,
     postfix={'loss': '1.0'},
     fd=sys.stdout,
     line_breaks=False,
     is_terminal=True,
-    term_width=72,
+    term_width=112,
 ) as bar:
-    for value, loss in (
-        (256, '0.9'),
-        (512, '0.8'),
-        (768, '0.7'),
-        (1024, '0.6'),
-        (1536, '0.5'),
-        (2048, '0.4'),
-        (3072, '0.2'),
-        (4096, '0.1'),
-    ):
+    for step in range(24):
+        value = int(8192 * (step + 1) / 24)
+        loss = f'{1 - ((step + 1) / 24):.2f}'
         bar.update(value, postfix={'loss': loss}, force=True)
 """,
     ),
@@ -186,14 +196,26 @@ def frames_from_output(output: str) -> list[list[str]]:
             ]
             if lines:
                 frames.append(lines)
-        return frames[-MAX_ANIMATION_FRAMES:] or [['No output captured']]
+        return limit_animation_frames(frames) or [['No output captured']]
 
     for raw_frame in output.splitlines():
         for part in raw_frame.split('\r'):
             line = part.strip()
             if line:
                 frames.append([normalize_terminal_line(line)])
-    return frames[-MAX_ANIMATION_FRAMES:] or [['No output captured']]
+    return limit_animation_frames(frames) or [['No output captured']]
+
+
+def limit_animation_frames(frames: list[list[str]]) -> list[list[str]]:
+    if len(frames) <= MAX_ANIMATION_FRAMES:
+        return frames
+
+    last_index = len(frames) - 1
+    selected = [
+        round(index * last_index / (MAX_ANIMATION_FRAMES - 1))
+        for index in range(MAX_ANIMATION_FRAMES)
+    ]
+    return [frames[index] for index in selected]
 
 
 def tspan(text: str, class_name: str | None = None) -> str:
@@ -272,7 +294,7 @@ def styled_terminal_line(line: str) -> str:
 
 
 def svg_document(title: str, frames: list[list[str]]) -> str:
-    width = 760
+    width = SVG_WIDTH
     line_height = 24
     max_lines = max(len(frame) for frame in frames)
     height = 72 + max_lines * line_height

docs/_static/progressbar-hero.svg

@@ -7,6 +7,15 @@
 import scripts.render_readme_demos as demos  # noqa: E402
 
 
+def _bar_widths(frames: list[list[str]]) -> list[int]:
+    return [
+        len(match.group('inner'))
+        for frame in frames
+        for line in frame
+        if (match := demos.BAR_RE.search(line))
+    ]
+
+
 def test_render_svg_escapes_terminal_text(tmp_path: Path) -> None:
     output = tmp_path / 'demo.svg'
     demos.render_svg(
@@ -104,11 +113,22 @@ def test_render_svg_uses_fast_readme_animation_pacing(
     demos.render_svg(output, title='Demo', frames=[['a'], ['b'], ['c']])
 
     text = output.read_text(encoding='utf-8')
-    assert 'dur="0.36s"' in text
+    assert 'dur="0.24s"' in text
     assert 'dur="3.6s"' not in text
     assert '3.599999999' not in text
 
 
+def test_render_svg_uses_wide_canvas_for_readable_bars(
+    tmp_path: Path,
+) -> None:
+    output = tmp_path / 'demo.svg'
+    demos.render_svg(output, title='Demo', frames=[['a']])
+
+    text = output.read_text(encoding='utf-8')
+    assert 'width="1080"' in text
+    assert 'viewBox="0 0 1080 96"' in text
+
+
 def test_multibar_demo_captures_rendered_progressbar_output() -> None:
     demo = next(demo for demo in demos.DEMOS if demo.name == 'multibar')
     frames = demos.capture_demo(demo)
@@ -121,7 +141,9 @@ def test_multibar_demo_captures_rendered_progressbar_output() -> None:
     assert 'test' in text
     assert 'Elapsed Time:' in text
     assert 'ETA:' in text
-    assert '(1 of 12)' in text or '(2 of 12)' in text
+    assert '(0 of 24)' in text
+    assert '(1 of 24)' in text or '(2 of 24)' in text
+    assert '(24 of 24)' in text
 
 
 def test_capture_demo_timeout_raises_clear_error(
@@ -146,23 +168,41 @@ def test_capture_frames_splits_carriage_return_output() -> None:
 
 def test_capture_frames_keeps_more_animation_states() -> None:
     frames = demos.frames_from_output(
-        '\n'.join(f'frame {index}' for index in range(20))
+        '\n'.join(f'frame {index}' for index in range(30))
     )
 
-    assert len(frames) == 16
-    assert frames[0] == ['frame 4']
-    assert frames[-1] == ['frame 19']
+    assert len(frames) == 24
+    assert frames[0] == ['frame 0']
+    assert frames[-1] == ['frame 29']
 
 
 def test_readme_demos_emit_enough_frames_to_look_responsive() -> None:
     frame_counts = {
         demo.name: len(demos.capture_demo(demo)) for demo in demos.DEMOS
     }
 
-    assert frame_counts['hero'] >= 12
-    assert frame_counts['multibar'] >= 8
+    assert frame_counts['hero'] == 24
+    assert frame_counts['multibar'] == 24
     assert frame_counts['unknown-length'] >= 8
-    assert frame_counts['ergonomics'] >= 8
+    assert frame_counts['ergonomics'] == 24
+
+
+def test_readme_demos_show_wide_determinate_progress_bars() -> None:
+    frames_by_name = {
+        demo.name: demos.capture_demo(demo) for demo in demos.DEMOS
+    }
+
+    for name in ('hero', 'multibar', 'ergonomics'):
+        text = '\n'.join(
+            line for frame in frames_by_name[name] for line in frame
+        )
+        first_frame = '\n'.join(frames_by_name[name][0])
+        last_frame = '\n'.join(frames_by_name[name][-1])
+        assert '0%' in first_frame
+        assert '100%' in last_frame
+        assert '0%' in text
+        assert '100%' in text
+        assert max(_bar_widths(frames_by_name[name])) >= 32
 
 
 def test_capture_frames_normalizes_variable_timing_text() -> None: