Measure paged output before building a pager

page() constructed a full Pager -- a TextArea, a SearchToolbar, an ANSI
lexer and its key bindings -- and then threw it away whenever the output
fit on screen, which is a common case for ppaged(). Only the line
measurements were ever used on that path.

Move the size check into a module-level output_fits() that measures the
text directly, and build the Pager only once the output has to be
scrolled. A shared _fragments() helper does the one ANSI parse for both,
so the measurement cannot drift from what the view would render.

The fast path's size check drops from ~0.15ms to ~0.02ms per call, so it isn't a massive speedup or anything, but still cleaner.

Author: tleonhardt

cmd2/command_toolbar.py

@@ -24,7 +24,7 @@
 from prompt_toolkit.patch_stdout import StdoutProxy
 from prompt_toolkit.utils import suspend_to_background_supported
 
-from .pager import Pager
+from .pager import Pager, output_fits
 
 if TYPE_CHECKING:
     from .cmd2 import Cmd
@@ -389,20 +389,20 @@ def _check_running(self) -> None:
 
     def page(self, text: str, *, chop: bool) -> None:
         """Show a pager above the same toolbar without starting another input reader."""
-        pager = Pager(text, chop=chop)
-        pager.bindings.add(
-            "c-z",
-            filter=Condition(lambda: suspend_to_background_supported() and to_filter(self.cmd.main_session.enable_suspend)()),
-        )(self._suspend_binding)
         size = self.app.output.get_size()
         # Measuring the toolbar can invoke its callback; keep that work on the
         # UI thread along with rendering and layout changes.
         toolbar_height = self._call_in_ui(lambda: self.toolbar.preferred_height(size.columns, size.rows).preferred)
-        if pager.fits(size.columns, max(0, size.rows - toolbar_height)):
+        if output_fits(text, size.columns, max(0, size.rows - toolbar_height), chop=chop):
             self.cmd.stdout.write(text)
             self.cmd.stdout.flush()
             return
 
+        pager = Pager(text, chop=chop)
+        pager.bindings.add(
+            "c-z",
+            filter=Condition(lambda: suspend_to_background_supported() and to_filter(self.cmd.main_session.enable_suspend)()),
+        )(self._suspend_binding)
         layout = Layout(HSplit([pager.container, self.toolbar]), focused_element=pager.text)
         previous = (self.app.layout, self.app.key_bindings, self.app.editing_mode, self.app.full_screen)
         entered = False

cmd2/pager.py

@@ -21,6 +21,33 @@
 from prompt_toolkit.widgets import SearchToolbar, TextArea
 
 
+def _fragments(text: str) -> StyleAndTextTuples:
+    """Parse captured output, dropping the trailing newline that ends its last line."""
+    return to_formatted_text(ANSI(text.removesuffix("\n")))
+
+
+def output_fits(text: str, columns: int, rows: int, *, chop: bool) -> bool:
+    """Check rendered line heights, including wrapping and wide Unicode characters.
+
+    Measuring the text itself keeps output that needs no scrolling from paying for a
+    Pager's widgets and key bindings, which would only be built to be thrown away.
+    """
+    lines = fragment_list_to_text(_fragments(text)).split("\n")
+    if chop:
+        # Even one wide line needs a pager so its hidden columns remain
+        # accessible through horizontal scrolling.
+        return len(lines) <= rows and all(get_cwidth(line) <= columns for line in lines)
+    # Reuse prompt-toolkit's own wrapping arithmetic so this matches what a Pager
+    # would render, without building a control to ask on the UI thread.
+    content = UIContent(get_line=lambda number: [("", lines[number])], line_count=len(lines))
+    height = 0
+    for line in range(content.line_count):
+        height += content.get_height_for_line(line, columns, None)
+        if height > rows:
+            return False
+    return True
+
+
 class _AnsiLexer(Lexer):
     """Preserve captured Rich styles while searching and scrolling plain text."""
 
@@ -42,7 +69,7 @@ def __init__(self, text: str, *, chop: bool) -> None:
         self.closed = threading.Event()
         self.on_close: Callable[[], None] = self.closed.set
         self.chop = chop
-        fragments = to_formatted_text(ANSI(text.removesuffix("\n")))
+        fragments = _fragments(text)
         self.search = SearchToolbar()
         self.text = TextArea(
             text=fragment_list_to_text(fragments),
@@ -190,20 +217,3 @@ def _scroll_horizontal(self, event: KeyPressEvent, direction: int) -> None:
         column = self._column_at_width(document.current_line, target)
         event.current_buffer.cursor_position = document.translate_row_col_to_index(document.cursor_position_row, column)
         self.text.window.horizontal_scroll = get_cwidth(document.current_line[:column])
-
-    def fits(self, columns: int, rows: int) -> bool:
-        """Check rendered line heights, including wrapping and wide Unicode characters."""
-        # Measuring must not ask BufferControl to create content: that starts
-        # history-loading tasks and is only safe on the application's event loop.
-        lines = self.text.document.lines
-        if self.chop:
-            # Even one wide line needs a pager so its hidden columns remain
-            # accessible through horizontal scrolling.
-            return len(lines) <= rows and all(get_cwidth(line) <= columns for line in lines)
-        content = UIContent(get_line=lambda number: [("", lines[number])], line_count=len(lines))
-        height = 0
-        for line in range(content.line_count):
-            height += content.get_height_for_line(line, columns, None)
-            if height > rows:
-                return False
-        return True

tests/test_command_toolbar.py

@@ -19,7 +19,7 @@
 from prompt_toolkit.shortcuts import PromptSession
 
 from cmd2 import Cmd
-from cmd2.pager import Pager
+from cmd2.pager import Pager, output_fits
 
 
 class Terminal(io.StringIO):
@@ -696,6 +696,18 @@ def test_builtin_pager_short_output(toolbar_app, monkeypatch) -> None:
     assert "short output\n" in output.getvalue()
 
 
+def test_builtin_pager_short_output_builds_no_pager(toolbar_app, monkeypatch) -> None:
+    app, _, output = toolbar_app
+    app.use_builtin_pager = True
+    monkeypatch.setattr(app, "stdin", Terminal())
+    monkeypatch.setenv("TERM", "xterm")
+    # Output that fits is written directly, so none of the pager's widgets are needed.
+    with mock.patch("cmd2.command_toolbar.Pager") as pager, app._command_toolbar_context():
+        app.ppaged("short output")
+        pager.assert_not_called()
+    assert "short output\n" in output.getvalue()
+
+
 def test_external_pager_suspends_shared_application(toolbar_app, monkeypatch) -> None:
     app, _, _ = toolbar_app
     app.use_builtin_pager = False
@@ -736,9 +748,17 @@ def test_pager_styles_and_wrapping(chop) -> None:
     assert pager.text.read_only
     lexer = pager.text.lexer.lex_document(pager.text.document)
     assert "ansired" in lexer(0)[0][0]
-    assert not pager.fits(20, 1)
-    assert pager.fits(20, 5) is (not chop)
-    assert pager.fits(100, 1)
+
+
+@pytest.mark.parametrize("chop", [False, True])
+def test_output_fits_measures_styled_and_wide_text(chop) -> None:
+    # Forty double-width characters occupy eighty columns, and styling them adds
+    # escape sequences that must not count towards the measurement.
+    text = "\x1b[31m" + "界" * 40 + "\x1b[0m\n"
+    assert not output_fits(text, 20, 1, chop=chop)
+    # Wrapping the line onto four rows fits; chopping keeps it one wide row that does not.
+    assert output_fits(text, 20, 5, chop=chop) is (not chop)
+    assert output_fits(text, 100, 1, chop=chop)
 
 
 @pytest.mark.parametrize("chop", [False, True])