From 66cffb22c3056e33306481dbce23b1597343759c Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sat, 14 Nov 2026 22:47:10 -0500 Subject: [PATCH 1/5] Add a built-in pager which keeps the bottom toolbar visible This restores what "Take the built-in pager out, to be proposed on its own" removed from the persistent toolbar's branch, unchanged: cmd2/pager.py, CommandToolbar.page() and its helpers, the use_builtin_pager attribute, their tests and their documentation. While the bottom toolbar is running, ppaged() shows its output in a pager which is a layout of the toolbar's own prompt-toolkit application, so the toolbar stays on screen and keeps refreshing while the user reads. An external pager has to be given the whole terminal, and hides it. --- CHANGELOG.md | 6 + cmd2/cmd2.py | 27 ++- cmd2/command_toolbar.py | 106 +++++++++- cmd2/pager.py | 229 ++++++++++++++++++++ docs/features/initialization.md | 1 + docs/features/os.md | 42 +++- docs/features/prompt.md | 10 +- tests/test_command_toolbar.py | 239 ++++++++++++++++++++- tests/test_pager.py | 323 +++++++++++++++++++++++++++++ tests/test_pipeline_job_control.py | 12 ++ 10 files changed, 978 insertions(+), 17 deletions(-) create mode 100644 cmd2/pager.py create mode 100644 tests/test_pager.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 24ce1cba5..bc89d83f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,12 @@ for input, refreshing at the same `refresh_interval` as the main prompt, instead of the toolbar disappearing for the duration of the nested prompt. `Cmd.select()` is unchanged, since prompt-toolkit's `choice()` offers no way to configure a refresh interval + - Added an embedded pager which `Cmd.ppaged()` uses while the bottom toolbar is running, so the + toolbar stays visible and refreshing instead of the terminal being handed to an external + pager. It supports vertical and horizontal scrolling, incremental search, and chopped lines on + every platform, including Windows where the default external pager (`more`) always wraps. + Output which already fits on the screen is printed directly rather than paged. Set + `self.use_builtin_pager = False` to keep using the external `pager`/`pager_chop` commands. ## 4.4.2 (November 11, 2026) diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 8dce5df43..b99ea79e3 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -661,6 +661,10 @@ def __init__( if callargs: self._startup_commands.extend(callargs) + # The embedded pager shares the main toolbar. Applications can opt back + # into their configured external pager by setting this to False. + self.use_builtin_pager = enable_bottom_toolbar + # Set the pager(s) for use when displaying output using a pager if sys.platform.startswith("win"): self.pager = self.pager_chop = "more" @@ -1952,15 +1956,17 @@ def ppaged( fits on the screen. A pager is not used inside a script (Python or text) or when output is redirected or piped, and in these cases, output is sent to `poutput`. - The pager takes over the terminal, so the bottom toolbar is hidden while it is open and - comes back when it exits. + While the bottom toolbar is running, the built-in pager keeps it visible and refreshing. + Set ``use_builtin_pager=False`` to use the configured external ``pager`` or ``pager_chop`` + command instead; external pagers temporarily hide the toolbar. Where no toolbar is + running, such as outside the command loop, the external pager is used regardless. :param chop: True -> causes lines longer than the screen width to be chopped (truncated) rather than wrapped - truncated text is still accessible by scrolling with the right & left arrow keys - chopping is ideal for displaying wide tabular data as is done in utilities like pgcli False -> causes lines longer than the screen width to wrap to the next line - wrapping is ideal when you want to keep users from having to use horizontal scrolling - WARNING: On Windows, the text always wraps regardless of what the chop argument is set to + WARNING: The default external pager on Windows always wraps; the built-in pager supports chopping. :param soft_wrap: Enable soft wrap mode. If True, lines of text will not be word-wrapped or cropped to fit the terminal width. Defaults to True. @@ -2003,8 +2009,17 @@ def ppaged( soft_wrap=soft_wrap, **(rich_print_kwargs if rich_print_kwargs is not None else {}), ) + output = capture.get() + + # Page inside the toolbar's display only when the command loop is already + # running one. Starting one here would seize the terminal for commands run + # outside that loop, which the toolbar is documented not to do. + if self.use_builtin_pager and self._command_toolbar is not None and self._command_toolbar.is_active: + self._command_toolbar.page(output, chop=chop) + return + # As for a pipe: the pager gets UTF-8, and on Windows the console is UTF-8 while it runs. - output_bytes = capture.get().encode("utf-8", "replace") + output_bytes = output.encode("utf-8", "replace") # Prevent KeyboardInterrupts while in the pager. The pager application will # still receive the SIGINT since it is in the same process group as us. @@ -2116,8 +2131,8 @@ def get_bottom_toolbar(self) -> AnyFormattedText: During command execution this callback runs in a background UI thread. Protect shared state with a lock when necessary, but never hold that lock in a command while it prompts for input, pages output, runs a shell command, or otherwise pauses the toolbar: pausing - waits for this callback to return. The toolbar is suspended while another prompt, a - pager, or an interactive shell owns the terminal. + waits for this callback to return. The built-in pager shares this toolbar. It is suspended + while another prompt, external pager, or interactive shell owns the terminal. If this callback raises an exception during a command, the error is reported once and the command carries on without the toolbar. diff --git a/cmd2/command_toolbar.py b/cmd2/command_toolbar.py index dc709f1e3..0d59e3e9e 100644 --- a/cmd2/command_toolbar.py +++ b/cmd2/command_toolbar.py @@ -12,9 +12,12 @@ import threading import time from collections.abc import Callable, Generator +from concurrent.futures import Future +from concurrent.futures import TimeoutError as FutureTimeoutError from typing import TYPE_CHECKING, Any, TextIO, TypeVar, cast from prompt_toolkit.application import Application, create_app_session, run_in_terminal +from prompt_toolkit.enums import EditingMode from prompt_toolkit.filters import Condition, to_filter from prompt_toolkit.input.typeahead import get_typeahead, store_typeahead from prompt_toolkit.key_binding import KeyBindings @@ -24,6 +27,8 @@ from prompt_toolkit.patch_stdout import StdoutProxy from prompt_toolkit.utils import get_cwidth, suspend_to_background_supported +from .pager import Pager, output_fits + if TYPE_CHECKING: from .cmd2 import Cmd @@ -32,6 +37,7 @@ _ESCAPE_RE = re.compile(r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])") _F = TypeVar("_F", bound=Callable[..., Any]) +_R = TypeVar("_R") def suspend_process_group(suspend_group: bool = True) -> None: @@ -341,6 +347,7 @@ def suspend(event: KeyPressEvent) -> None: event.app.suspend_to_background() self._bindings = bindings + self._suspend_binding = suspend @staticmethod def _suspend_to_background(suspend_group: bool = True) -> None: @@ -398,7 +405,7 @@ def _resume(self) -> None: # has not seen with other bindings. It caches the bindings it merges for each focused # window, application bindings included, and does not notice this attribute being # reassigned, so reusing a window with different bindings would keep the old ones. - # This layout and the main prompt's have windows of their own. + # This layout, the main prompt's, and each pager's all have windows of their own. for name, value in (("layout", self._layout), ("key_bindings", self._bindings), ("erase_when_done", True)): stack.callback(setattr, self.app, name, getattr(self.app, name)) setattr(self.app, name, value) @@ -553,6 +560,103 @@ def is_active(self) -> bool: """Whether the display currently owns the terminal.""" return self._proxy is not None and self.app.is_running + def _call_in_ui(self, func: Callable[[], _R]) -> _R: + """Change UI state on its event loop, propagating failures to the command.""" + result: Future[_R] = Future() + + def call() -> None: + try: + value = func() + except BaseException as exc: # noqa: BLE001 + result.set_exception(exc) + else: + result.set_result(value) + + if self.app.loop is None: + raise RuntimeError("Toolbar is not running") + self.app.loop.call_soon_threadsafe(call) + while True: + try: + value = result.result(timeout=0.1) + except FutureTimeoutError: + if result.done(): + # The callback finished while this poll was expiring, or raised a + # TimeoutError of its own -- indistinguishable here, because + # concurrent.futures.TimeoutError is TimeoutError on Python 3.11+. + # Ask the future for its outcome rather than re-raising this poll's + # timeout, which would report a failure for a call that succeeded. + return result.result() + self._check_running() + else: + return value + + def _check_running(self) -> None: + if self._thread is None or not self._thread.is_alive(): + if self._error is not None: + raise self._error + raise EOFError + + def page(self, text: str, *, chop: bool) -> None: + """Show a pager above the same toolbar without starting another input reader.""" + 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 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 + + def enter() -> None: + nonlocal entered + entered = True + self.app.renderer.erase() + self.app.layout = layout + self.app.key_bindings = pager.bindings + self.app.editing_mode = EditingMode.EMACS + self.app.full_screen = self.app.renderer.full_screen = True + self.app.invalidate() + + def leave() -> None: + nonlocal entered + if not entered: + return + entered = False + self.app.renderer.erase() + self.app.layout, self.app.key_bindings, self.app.editing_mode, self.app.full_screen = previous + self.app.renderer.full_screen = self.app.full_screen + self.app.renderer.request_absolute_cursor_position() + self.app.invalidate() + + def close() -> None: + # Switch bindings before the next key is processed, preserving + # typeahead sent in the same terminal read as the pager's quit key. + leave() + pager.closed.set() + + pager.on_close = close + + try: + self._call_in_ui(enter) + while not pager.closed.wait(0.1): + self._check_running() + finally: + if self._thread is not None and self._thread.is_alive(): + self._call_in_ui(leave) + else: + # The application's shutdown already reset the renderer. + self.app.layout, self.app.key_bindings, self.app.editing_mode, self.app.full_screen = previous + self.app.renderer.full_screen = self.app.full_screen + @contextlib.contextmanager def suspend(self) -> Generator[None]: """Temporarily restore ordinary terminal access, including nested suspensions.""" diff --git a/cmd2/pager.py b/cmd2/pager.py new file mode 100644 index 000000000..438dd4e48 --- /dev/null +++ b/cmd2/pager.py @@ -0,0 +1,229 @@ +"""A pager view hosted by the main prompt-toolkit application.""" + +import re +import threading +from collections.abc import Callable +from functools import partial + +from prompt_toolkit.document import Document +from prompt_toolkit.filters import has_focus, is_searching, to_filter +from prompt_toolkit.formatted_text import ANSI, fragment_list_to_text, to_formatted_text +from prompt_toolkit.formatted_text.base import StyleAndTextTuples +from prompt_toolkit.formatted_text.utils import split_lines +from prompt_toolkit.key_binding import KeyBindings +from prompt_toolkit.key_binding.bindings import search +from prompt_toolkit.key_binding.key_processor import KeyPressEvent +from prompt_toolkit.layout import HSplit, Window +from prompt_toolkit.layout.containers import ConditionalContainer +from prompt_toolkit.layout.controls import FormattedTextControl, UIContent +from prompt_toolkit.lexers import Lexer +from prompt_toolkit.search import SearchDirection, start_search +from prompt_toolkit.utils import get_cwidth +from prompt_toolkit.widgets import SearchToolbar, TextArea + +_OSC_RE = re.compile(r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)") + + +def _fragments(text: str) -> StyleAndTextTuples: + """Parse captured output, dropping the trailing newline that ends its last line.""" + # prompt-toolkit's ANSI parser does not handle OSC sequences, including Rich + # hyperlinks. Remove their metadata while retaining visible text and SGR styles. + text = _OSC_RE.sub("", text) + 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.""" + + def __init__(self, fragments: StyleAndTextTuples) -> None: + self.lines = list(split_lines(fragments)) + + def lex_document(self, document: Document) -> Callable[[int], StyleAndTextTuples]: # noqa: ARG002 + def get_line(number: int) -> StyleAndTextTuples: + return self.lines[number] if number < len(self.lines) else [] + + return get_line + + +class Pager: + """Scrollable, searchable output; the host supplies the persistent toolbar.""" + + def __init__(self, text: str, *, chop: bool) -> None: + """Build an independent view without creating an application or input reader.""" + self.closed = threading.Event() + self.on_close: Callable[[], None] = self.closed.set + self.chop = chop + fragments = _fragments(text) + self.search = SearchToolbar() + self.text = TextArea( + text=fragment_list_to_text(fragments), + lexer=_AnsiLexer(fragments), + read_only=True, + wrap_lines=not chop, + search_field=self.search, + ) + self.text.window.always_hide_cursor = to_filter(True) + self.container = HSplit( + [ + self.text, + self.search, + ConditionalContainer( + Window( + FormattedTextControl(" Space/PgDn: next b/PgUp: back /: search n: next match q: quit"), + height=1, + style="class:bottom-toolbar", + ), + filter=~is_searching, + ), + ] + ) + self.bindings = bindings = KeyBindings() + focused = has_focus(self.text) + + @bindings.add("", filter=focused) + def ignore(event: KeyPressEvent) -> None: + # Pager keystrokes must not become commands at the next prompt. + pass + + @bindings.add("q", filter=focused) + @bindings.add("escape", filter=focused, eager=True) + @bindings.add("c-c", filter=focused) + def close(event: KeyPressEvent) -> None: # noqa: ARG001 + self.on_close() + + for keys, pages in ( + ((" ", "pagedown", "f", "c-f"), 1.0), + (("b", "pageup", "c-b"), -1.0), + (("d", "c-d"), 0.5), + (("u", "c-u"), -0.5), + ): + for key in keys: + bindings.add(key, filter=focused)(partial(self._scroll_page, pages=pages)) + + @bindings.add("j", filter=focused) + @bindings.add("down", filter=focused) + @bindings.add("enter", filter=focused) + def down(event: KeyPressEvent) -> None: + self._scroll(event, 1) + + @bindings.add("k", filter=focused) + @bindings.add("up", filter=focused) + def up(event: KeyPressEvent) -> None: + self._scroll(event, -1) + + @bindings.add("right", filter=focused) + @bindings.add("l", filter=focused) + def right(event: KeyPressEvent) -> None: + self._scroll_horizontal(event, 1) + + @bindings.add("left", filter=focused) + @bindings.add("h", filter=focused) + def left(event: KeyPressEvent) -> None: + self._scroll_horizontal(event, -1) + + @bindings.add("g", filter=focused) + @bindings.add("home", filter=focused) + def first(event: KeyPressEvent) -> None: + event.current_buffer.cursor_position = 0 + + @bindings.add("G", filter=focused) + @bindings.add("end", filter=focused) + def last(event: KeyPressEvent) -> None: + event.current_buffer.cursor_position = len(event.current_buffer.text) + + @bindings.add("/", filter=focused) + def find(event: KeyPressEvent) -> None: # noqa: ARG001 + start_search(direction=SearchDirection.FORWARD) + + @bindings.add("?", filter=focused) + def find_backwards(event: KeyPressEvent) -> None: # noqa: ARG001 + start_search(direction=SearchDirection.BACKWARD) + + @bindings.add("n", filter=focused) + def next_match(event: KeyPressEvent) -> None: + event.current_buffer.apply_search(event.app.current_search_state, include_current_position=False) + + @bindings.add("N", filter=focused) + def previous_match(event: KeyPressEvent) -> None: + event.current_buffer.apply_search(~event.app.current_search_state, include_current_position=False) + + # Explicit search bindings also work when the main prompt uses Vi mode. + bindings.add("enter", filter=is_searching)(search.accept_search) + bindings.add("escape", filter=is_searching, eager=True)(search.abort_search) + bindings.add("c-c", filter=is_searching)(search.abort_search) + + @staticmethod + def _column_at_width(line: str, width: int) -> int: + used = 0 + for column, char in enumerate(line): + if used >= width: + return column + used += get_cwidth(char) + return len(line) + + def _scroll_page(self, event: KeyPressEvent, *, pages: float) -> None: + info = self.text.window.render_info + if info is not None: + amount = max(1, int(max(1, info.window_height - 1) * abs(pages))) + self._scroll(event, amount if pages > 0 else -amount) + + def _scroll(self, event: KeyPressEvent, rows: int) -> None: + """Move by display rows, including within lines taller than the viewport.""" + info = self.text.window.render_info + if info is None or info.window_width == 0: + return + document = event.current_buffer.document + line = document.cursor_position_row + wrapped_row = 0 if self.chop else get_cwidth(document.current_line_before_cursor) // info.window_width + target = wrapped_row + rows + + def height(number: int) -> int: + return 1 if self.chop else info.get_height_for_line(number) + + while target < 0 and line > 0: + line -= 1 + target += height(line) + while target >= height(line) and line < document.line_count - 1: + target -= height(line) + line += 1 + target = max(0, min(target, height(line) - 1)) + # Chopped lines never wrap, so leave the cursor at the column the reader + # scrolled to. Moving it to the start of the line would drag the view back + # with it, since the window scrolls horizontally to keep the cursor visible. + width = self.text.window.horizontal_scroll if self.chop else target * info.window_width + column = self._column_at_width(document.lines[line], width) + event.current_buffer.cursor_position = document.translate_row_col_to_index(line, column) + self.text.window.vertical_scroll = line + self.text.window.vertical_scroll_2 = target if height(line) > info.window_height else 0 + + def _scroll_horizontal(self, event: KeyPressEvent, direction: int) -> None: + info = self.text.window.render_info + if info is None or not self.chop: + return + document = event.current_buffer.document + target = max(0, self.text.window.horizontal_scroll + direction * max(1, info.window_width // 2)) + 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]) diff --git a/docs/features/initialization.md b/docs/features/initialization.md index fc084ff3d..88e6d79d7 100644 --- a/docs/features/initialization.md +++ b/docs/features/initialization.md @@ -52,6 +52,7 @@ Here are instance attributes of `cmd2.Cmd` which developers might wish to overri - **max_completion_table_items**: The maximum number of completion results allowed for a completion table to appear (Default: 50) - **pager**: sets the pager command used by the `Cmd.ppaged()` method for displaying wrapped output using a pager - **pager_chop**: sets the pager command used by the `Cmd.ppaged()` method for displaying chopped/truncated output using a pager +- **use_builtin_pager**: defaults to `enable_bottom_toolbar`. While the command toolbar is running, `Cmd.ppaged()` uses an embedded pager that keeps that toolbar visible. Set to `False` to always use the external `pager`/`pager_chop` commands. This is an opt-*out* only: setting it to `True` does nothing unless `enable_bottom_toolbar` is also set, because the embedded pager shares the toolbar's display. - **py_bridge_name**: name by which embedded Python environments and scripts refer to the `cmd2` application by in order to call commands (Default: `app`) - **py_locals**: dictionary that defines specific variables/functions available in Python shells and scripts (provides more fine-grained control than making everything available with **self_in_py**) - **quiet**: if `True`, then completely suppress nonessential output (Default: `False`) diff --git a/docs/features/os.md b/docs/features/os.md index f4d399598..0706c7a69 100644 --- a/docs/features/os.md +++ b/docs/features/os.md @@ -46,8 +46,44 @@ Output of any command can be displayed one page at a time using the [cmd2.Cmd.pp pager is only used when the terminal is interactive. Inside a script, or when the command's output is redirected or piped, `ppaged()` falls back to `poutput()`. -While the [bottom toolbar](./prompt.md#bottom-toolbar) is running, a pager temporarily hides it, -because the pager takes over the terminal. The toolbar comes back when the pager exits. +### Embedded pager + +While the [bottom toolbar](./prompt.md#bottom-toolbar) is running, `ppaged()` displays its output in +an embedded pager rather than handing the terminal to an external program. The toolbar stays visible +and keeps refreshing beneath the paged output, and `cmd2` never gives up control of the terminal. + +Output which already fits in the space above the toolbar is printed directly, so there is no pager +to dismiss. + +| Keys | Action | +| ---------------------------------- | ------------------------------------------------- | +| `Space`, `PageDown`, `f`, `Ctrl-F` | Forward one page | +| `b`, `PageUp`, `Ctrl-B` | Back one page | +| `d` / `u`, `Ctrl-D` / `Ctrl-U` | Forward / back half a page | +| `j` / `k`, `Down` / `Up`, `Enter` | Down / up one line | +| `h` / `l`, `Left` / `Right` | Scroll left / right (chopped output only) | +| `g` / `G`, `Home` / `End` | Jump to the beginning / end | +| `/` / `?` | Search forward / backward | +| `n` / `N` | Jump to the next / previous match | +| `q`, `Escape`, `Ctrl-C` | Close the pager and return to the running command | +| `Ctrl-Z` | Suspend to the background, where supported | + +Passing `chop=True` truncates lines longer than the screen width instead of wrapping them, and the +hidden columns remain reachable with the left and right arrow keys. Unlike the default external +pager on Windows (`more`), the embedded pager supports chopping on every platform. + +Rich styles in the paged output are preserved: colors are rendered while scrolling and searching, +and the visible text of a hyperlink is shown without its escape sequence metadata. + +### External pagers + +Set `self.use_builtin_pager = False` to always use the external commands configured in `self.pager` +and `self.pager_chop`. This is the opt-out for applications which need `less` features the embedded +pager does not provide. External pagers temporarily hide the toolbar and restore it on exit. + +The setting only ever turns the embedded pager off. Because the embedded pager shares the toolbar's +display, it is unavailable anywhere a toolbar is not running, such as a command invoked outside the +command loop, and `ppaged()` uses the external pager there regardless of this setting. Alternatively, a terminal pager can be invoked directly using the ability to run shell commands with the `!` shortcut like so: @@ -56,7 +92,7 @@ the `!` shortcut like so: !!! warning - Once you are in a terminal pager, that program temporarily has control of your terminal, + Once you are in an external terminal pager, that program temporarily has control of your terminal, **NOT** `cmd2`. Typically you can use either the arrow keys or ``/`` keys to scroll around or type `q` to quit the pager and return control to your `cmd2` application. diff --git a/docs/features/prompt.md b/docs/features/prompt.md index 698d1ff53..318e37138 100644 --- a/docs/features/prompt.md +++ b/docs/features/prompt.md @@ -153,8 +153,14 @@ once and the command carries on without the toolbar. ### Commands That Take Over the Terminal -cmd2 temporarily hides the toolbar for pagers, Python environments, and shell commands. It also -hides it while a command's output is piped to another process, since that process may be +While the toolbar is running, `ppaged()` uses an embedded pager which keeps the same toolbar visible +and refreshing instead of handing the terminal to an external pager. Short output is printed +directly above the toolbar, and longer output becomes a scrollable, searchable view. Set +`self.use_builtin_pager = False` to opt out and use your configured external `pager`/`pager_chop` +commands. See [Embedded pager](./os.md#embedded-pager) for the key bindings and full details. + +cmd2 temporarily hides the toolbar for external pagers, Python environments, and shell commands. It +also hides it while a command's output is piped to another process, since that process may be interactive, as `less` and `fzf` are. It restores the toolbar when those operations finish. [cmd2.Cmd.read_input][] and [cmd2.Cmd.read_secret][] keep the toolbar visible, and it continues to diff --git a/tests/test_command_toolbar.py b/tests/test_command_toolbar.py index 18b1ffe9b..ab2531c4c 100644 --- a/tests/test_command_toolbar.py +++ b/tests/test_command_toolbar.py @@ -3,6 +3,8 @@ import sys import threading import time +from concurrent.futures import Future, ThreadPoolExecutor +from concurrent.futures import TimeoutError as FutureTimeoutError from types import SimpleNamespace from unittest import mock @@ -108,8 +110,10 @@ def __getattr__(self, name): return getattr(self.file, name) -def test_command_toolbar_pipe_process_inherits_terminal(toolbar_app, tmp_path) -> None: +@pytest.mark.parametrize("builtin_pager", [False, True]) +def test_command_toolbar_pipe_process_inherits_terminal(toolbar_app, tmp_path, builtin_pager) -> None: app, _, _ = toolbar_app + app.use_builtin_pager = builtin_pager destination = tmp_path / "terminal.txt" running = [] readers = [] @@ -774,7 +778,6 @@ def failing_stop() -> None: def test_command_toolbar_exit_after_result_is_set(toolbar_app) -> None: app, _, _ = toolbar_app - exited_twice = threading.Event() with app._command_toolbar_context(): toolbar = app._command_toolbar @@ -783,13 +786,110 @@ def already_exiting(): # The result is set before run_async() has finished its cleanup. assert toolbar.app.is_running toolbar._exit() - exited_twice.set() - toolbar.app.loop.call_soon_threadsafe(already_exiting) - assert exited_twice.wait(2) + toolbar._call_in_ui(already_exiting) assert app.main_session.app.layout is app.main_session.layout +def test_command_toolbar_ui_call_propagates_failures(toolbar_app) -> None: + app, _, _ = toolbar_app + + def fail(exception: BaseException) -> None: + raise exception + + with app._command_toolbar_context(): + toolbar = app._command_toolbar + + # A UI callback runs on the display's loop, so its failure has to be carried + # back to the command thread rather than reaching the loop's error handler. + with pytest.raises(ValueError, match="broken ui call"): + toolbar._call_in_ui(lambda: fail(ValueError("broken ui call"))) + + # A TimeoutError raised by the callback is the same class the pending future + # reports itself with, and must not be mistaken for one. + with pytest.raises(TimeoutError, match="slow ui call"): + toolbar._call_in_ui(lambda: fail(TimeoutError("slow ui call"))) + + # A callback that outlives the poll interval keeps waiting instead of giving up. + assert toolbar._call_in_ui(lambda: time.sleep(0.2) or "finished") == "finished" + + +def test_command_toolbar_ui_call_returns_a_result_that_lands_during_the_poll(toolbar_app, monkeypatch) -> None: + """A callback finishing while the poll expires must return its value, not a timeout. + + `concurrent.futures.TimeoutError` is `TimeoutError` on Python 3.11+, so the poll + expiring and the callback raising a timeout of its own are indistinguishable by type. + Re-raising the caught exception once the future is done therefore reports a timeout for + a call that actually succeeded. + """ + app, _, _ = toolbar_app + + class RacyFuture(Future): + """Completes, and only then reports the poll as having expired.""" + + def __init__(self) -> None: + super().__init__() + self._polled = False + + def result(self, timeout=None): # type: ignore[no-untyped-def] + if timeout is not None and not self._polled: + self._polled = True + super().result(timeout=5) # let the callback finish first + raise FutureTimeoutError # then act as though the poll had expired + return super().result(timeout) + + monkeypatch.setattr(command_toolbar, "Future", RacyFuture) + with app._command_toolbar_context(): + toolbar = app._command_toolbar + assert toolbar._call_in_ui(lambda: "finished") == "finished" + + +def test_command_toolbar_ui_call_after_display_stopped(toolbar_app) -> None: + app, pipe, _ = toolbar_app + with app._command_toolbar_context(): + toolbar = app._command_toolbar + pipe.close() + toolbar._thread.join(timeout=2) + assert not toolbar._thread.is_alive() + + # There is no loop left to run UI work on, so asking must fail rather than + # queue a callback onto a closed loop. + assert toolbar.app.loop is None + with pytest.raises(RuntimeError, match="Toolbar is not running"): + toolbar._call_in_ui(lambda: None) + + +def test_command_toolbar_ui_call_reports_display_failure(toolbar_app, capsys) -> None: + app, _, _ = toolbar_app + with app._command_toolbar_context(): + toolbar = app._command_toolbar + loop = toolbar.app.loop + schedule = loop.call_soon_threadsafe + failed = threading.Event() + + def die(*args, **kwargs): + # The display dies instead of running the queued callback, so the future + # the command is waiting on never resolves. Only drop that one request, + # made here on the command thread. asyncio uses call_soon_threadsafe from + # its own threads, and on Windows the default executor's join is reported + # through it while asyncio.run() shuts the loop down. Swallowing that + # report strands the toolbar thread for 300 seconds, or forever before + # Python 3.12, where shutdown_default_executor() has no timeout. + if not failed.is_set() and threading.current_thread() is threading.main_thread(): + failed.set() + schedule(lambda: toolbar.app.exit(exception=ValueError("broken display"))) + return None + return schedule(*args, **kwargs) + + with ( + mock.patch.object(loop, "call_soon_threadsafe", side_effect=die), + pytest.raises(ValueError, match="broken display"), + ): + toolbar._call_in_ui(lambda: None) + + assert "broken display" in capsys.readouterr().err + + def test_command_toolbar_failure_after_startup_is_reported(toolbar_app, capsys) -> None: app, _, output = toolbar_app @@ -1060,8 +1160,107 @@ def test_command_toolbar_reuses_prompt_application(toolbar_app) -> None: assert app._read_raw_input("Next: ", session, pre_run=lambda: pipe.send_text("answer\n")) == "answer" +@pytest.mark.parametrize("quit_key", ["q", "\x03"]) +def test_builtin_pager_keeps_toolbar_live(toolbar_app, monkeypatch, quit_key) -> None: + app, pipe, _ = toolbar_app + app.use_builtin_pager = True + monkeypatch.setattr(app, "stdin", Terminal()) + monkeypatch.setenv("TERM", "xterm") + entered, refreshed, moved, found = (threading.Event() for _ in range(4)) + state = ["BEFORE"] + + def toolbar_text(): + assert threading.current_thread() is not threading.main_thread() + if app.main_session.app.full_screen and state[0] == "AFTER": + refreshed.set() + return state[0] + + app.main_session.bottom_toolbar = toolbar_text + prompt_layout = app.main_session.app.layout + + def observe(ui): + if not ui.full_screen: + return + assert ui.layout.container.children[-1] is app._command_toolbar.toolbar + entered.set() + row = ui.layout.current_buffer.document.cursor_position_row + if row > 0: + moved.set() + if row == 80: + found.set() + + def interact(): + try: + assert entered.wait(2) + state[0] = "AFTER" + assert refreshed.wait(2) + pipe.send_text(" ") + assert moved.wait(2) + pipe.send_text("/row 080\n") + assert found.wait(2) + finally: + pipe.send_text(quit_key) + + app.main_session.app.after_render += observe + with mock.patch("subprocess.Popen") as external, ThreadPoolExecutor() as executor: + interaction = executor.submit(interact) + with app._command_toolbar_context(): + thread = app._command_toolbar._thread + app.ppaged("\n".join(f"row {i:03d}" for i in range(100))) + assert app._command_toolbar._thread is thread + assert app._command_toolbar.is_active + assert not app.main_session.app.full_screen + assert not app.main_session.app.renderer.full_screen + interaction.result(timeout=2) + external.assert_not_called() + assert app.main_session.app.layout is prompt_layout + assert refreshed.is_set() + assert get_typeahead(pipe) == [] + + +def test_builtin_pager_short_output(toolbar_app, monkeypatch) -> None: + app, _, output = toolbar_app + app.use_builtin_pager = True + monkeypatch.setattr(app, "stdin", Terminal()) + monkeypatch.setenv("TERM", "xterm") + with mock.patch("subprocess.Popen") as external, app._command_toolbar_context(): + app.ppaged("short output") + assert app._command_toolbar.is_active + external.assert_not_called() + 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_builtin_pager_needs_an_already_running_toolbar(toolbar_app, monkeypatch) -> None: + app, _, _ = toolbar_app + app.use_builtin_pager = True + monkeypatch.setattr(app, "stdin", Terminal()) + monkeypatch.setenv("TERM", "xterm") + # Outside the command loop there is no toolbar to page inside. Starting one here + # would wrap the terminal streams and enter raw mode where the docs promise not to. + with ( + mock.patch.object(command_toolbar.CommandToolbar, "start") as start, + mock.patch("subprocess.Popen") as external, + ): + app.ppaged("row\n" * 200) + start.assert_not_called() + external.assert_called_once() + + def test_external_pager_suspends_shared_application(toolbar_app, monkeypatch) -> None: app, _, _ = toolbar_app + app.use_builtin_pager = False monkeypatch.setattr(app, "stdin", Terminal()) monkeypatch.setenv("TERM", "xterm") @@ -1073,3 +1272,33 @@ def external(*args, **kwargs): with mock.patch("subprocess.Popen", side_effect=external), app._command_toolbar_context(): app.ppaged("external pager") assert app._command_toolbar.is_active + + +def test_builtin_pager_eof_restores_prompt(toolbar_app) -> None: + app, pipe, output = toolbar_app + layout = app.main_session.app.layout + + def close_input(ui): + if ui.full_screen: + pipe.close() + + app.main_session.app.after_render += close_input + with pytest.raises(EOFError), app._command_toolbar_context(): + app._command_toolbar.page("line\n" * 100, chop=False) + assert app.main_session.app.layout is layout + assert not app.main_session.app.full_screen + assert not app.main_session.app.renderer.full_screen + assert app.stdout is output + + +def test_builtin_pager_does_not_capture_redirected_output(toolbar_app, monkeypatch, tmp_path) -> None: + app, _, output = toolbar_app + app.use_builtin_pager = True + monkeypatch.setattr(app, "stdin", Terminal()) + monkeypatch.setenv("TERM", "xterm") + target = tmp_path / "help.txt" + with mock.patch("cmd2.command_toolbar.Pager") as pager, app._command_toolbar_context(): + app.onecmd_plus_hooks(f'help > "{target}"') + pager.assert_not_called() + assert "Cmd2 Commands" in target.read_text(encoding="utf-8") + assert "Cmd2 Commands" not in output.getvalue() diff --git a/tests/test_pager.py b/tests/test_pager.py new file mode 100644 index 000000000..b53aff4de --- /dev/null +++ b/tests/test_pager.py @@ -0,0 +1,323 @@ +"""Tests for the built-in pager view.""" + +import threading +import time +from concurrent.futures import ThreadPoolExecutor +from types import SimpleNamespace +from unittest import mock + +import pytest +from prompt_toolkit.data_structures import Size +from prompt_toolkit.input.typeahead import get_typeahead +from rich.console import Console + +from cmd2.pager import Pager, output_fits + + +@pytest.mark.parametrize("chop", [False, True]) +def test_pager_styles_and_wrapping(chop) -> None: + pager = Pager("\x1b[31m" + "界" * 40 + "\x1b[0m\n", chop=chop) + assert pager.text.text == "界" * 40 + assert pager.text.read_only + lexer = pager.text.lexer.lex_document(pager.text.document) + assert "ansired" in lexer(0)[0][0] + + +@pytest.mark.parametrize("chop", [False, True]) +@pytest.mark.parametrize("terminator", ["\x1b\\", "\x07"], ids=["ST", "BEL"]) +def test_pager_rich_hyperlinks(chop, terminator) -> None: + # legacy_windows=False keeps rich from suppressing OSC 8 hyperlinks when the + # tests run against a legacy Windows console. + console = Console(force_terminal=True, color_system="standard", no_color=False, legacy_windows=False) + with console.capture() as capture: + console.print("[link=https://example.com][red]click here[/red][/link] after") + captured = capture.get() + assert "\x1b]8;" in captured + captured = captured.replace("\x1b\\", terminator) + + pager = Pager(captured, chop=chop) + assert pager.text.text == "click here after" + lexer = pager.text.lexer.lex_document(pager.text.document) + assert "ansired" in lexer(0)[0][0] + assert output_fits(captured, len("click here after"), 1, chop=chop) + assert not output_fits(captured, len("click here after") - 1, 1, chop=chop) + + +@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]) +def test_pager_long_line_navigation_resize_and_typeahead(toolbar_app, chop) -> None: + app, pipe, _ = toolbar_app + app.main_session.bottom_toolbar = "STATUS ONE\nSTATUS TWO" + entered, scrolled, resized = (threading.Event() for _ in range(3)) + + def observe(ui): + if not ui.full_screen: + return + # Check the rendered frame, not the stream of incremental terminal + # writes, to verify both toolbar rows survive navigation and resizing. + screen = ui.renderer._last_screen + # Use the size this frame was drawn at. The terminal may have been resized since, + # and an error raised here stops the display. + size = ui.renderer._last_size + bottom = "".join(screen.data_buffer[size.rows - 1][x].char for x in range(size.columns)) + assert bottom.startswith("STATUS TWO") + entered.set() + if ui.current_buffer.cursor_position > 0: + scrolled.set() + if size.columns == 60: + resized.set() + + def interact(): + try: + assert entered.wait(2) + pipe.send_text("\x1b[C" if chop else " ") + assert scrolled.wait(2) + app.main_session.output.size = Size(rows=20, columns=60) + app.main_session.app.invalidate() + assert resized.wait(2) + finally: + pipe.send_text("qnext\n") + + app.main_session.app.after_render += observe + with ThreadPoolExecutor() as executor: + interaction = executor.submit(interact) + with app._command_toolbar_context(): + app._command_toolbar.page("界" * 4000, chop=chop) + interaction.result(timeout=2) + assert app._read_raw_input("Next: ", app.main_session) == "next" + + +class PagerKeys: + """Send keys to the built-in pager and wait for the frame that reflects them.""" + + def __init__(self, app, pipe, pager) -> None: + self.pipe = pipe + self.pager = pager + self.presses = 0 + self.states = [] + self.updated = threading.Condition() + ui = app.main_session.app + ui.key_processor.after_key_press += self._count + ui.after_render += self._record + + def _count(self, _) -> None: + with self.updated: + self.presses += 1 + + def _record(self, _) -> None: + # Read the pager's own buffer, not the focused one, which is the search field + # while a search is being typed. Read it after rendering, because + # prompt-toolkit settles the window's scroll offsets while it draws. + with self.updated: + self.states.append( + ( + self.presses, + self.pager.text.buffer.document.cursor_position_row, + self.pager.text.window.horizontal_scroll, + ) + ) + self.updated.notify_all() + + def press(self, keys, row, column=0) -> None: + """Send keys and wait for a drawn frame that shows the expected position.""" + with self.updated: + handled = self.presses + self.pipe.send_text(keys) + deadline = time.monotonic() + 5 + index = 0 + with self.updated: + while True: + while index < len(self.states): + presses, *position = self.states[index] + index += 1 + if presses > handled and position == [row, column]: + return + remaining = deadline - time.monotonic() + notified = remaining > 0 and self.updated.wait(remaining) + assert notified, f"pager ignored {keys!r}: wanted {(row, column)}, saw {self.states[-3:]}" + + +def drive_pager(app, pipe, text, *, chop, script) -> None: + """Page text and run script against its keys while the pager is displayed.""" + created = [] + entered = threading.Event() + + def make_pager(*args, **kwargs): + pager = Pager(*args, **kwargs) + created.append(pager) + return pager + + def observe(ui): + if created and ui.full_screen and ui.layout.current_buffer is created[0].text.buffer: + entered.set() + + def interact(): + try: + assert entered.wait(5) + script(PagerKeys(app, pipe, created[0])) + finally: + pipe.send_text("q") + + app.main_session.app.after_render += observe + with mock.patch("cmd2.command_toolbar.Pager", side_effect=make_pager), ThreadPoolExecutor() as executor: + interaction = executor.submit(interact) + with app._command_toolbar_context(): + app._command_toolbar.page(text, chop=chop) + interaction.result(timeout=10) + assert get_typeahead(pipe) == [] + + +def test_pager_vertical_scrolling_keeps_horizontal_position(toolbar_app) -> None: + app, pipe, _ = toolbar_app + # Wide rows are what chopped output is for. Scrolling right to read a column and + # then moving down a row must not throw that column away. + text = "\n".join(f"row {index:03d} " + "col " * 40 for index in range(100)) + + def script(keys) -> None: + keys.press("\x1b[C", row=0, column=40) + keys.press("j", row=1, column=40) + keys.press("k", row=0, column=40) + + drive_pager(app, pipe, text, chop=True, script=script) + + +@pytest.mark.parametrize("chop", [False, True]) +def test_pager_navigation_keys(toolbar_app, chop) -> None: + app, pipe, _ = toolbar_app + lines = [f"row {index:03d}" for index in range(100)] + lines[3] = "" # A line with no columns for a scroll target to be clamped against. + + def script(keys) -> None: + keys.press("\x1b[B", row=1) # Down arrow. + keys.press("\x1b[A", row=0) # Up arrow. + page_rows = keys.pager.text.window.render_info.window_height - 1 + keys.press("\x1b[6~", row=page_rows) # Page Down. + keys.press("\x1b[5~", row=0) # Page Up. + keys.press("\r", row=1) + keys.press("\x1b[A", row=0) + keys.press("j", row=1) + keys.press("j", row=2) + keys.press("j", row=3) # Land on the empty line. + keys.press("k", row=2) # Moving up off it re-enters the line above. + keys.press("G", row=99) + keys.press("g", row=0) + keys.press("/row 05\n", row=50) + keys.press("n", row=51) + keys.press("N", row=50) + keys.press("?row 01\n", row=19) + keys.press("x", row=19) # Unbound keys are swallowed, not queued for the prompt. + # Horizontal scrolling applies only to chopped output, and stops at the + # end of a line shorter than the requested column. + keys.press("\x1b[C", row=19, column=len("row 019") if chop else 0) + keys.press("\x1b[D", row=19, column=0) + + drive_pager(app, pipe, "\n".join(lines), chop=chop, script=script) + + +@pytest.mark.parametrize("chop", [False, True]) +def test_pager_scrolling_before_first_render(chop) -> None: + pager = Pager("row\n" * 100, chop=chop) + # Keys can arrive before the first frame is drawn, when the window still has no + # rendered geometry to scroll against. + assert pager.text.window.render_info is None + event = SimpleNamespace(current_buffer=pager.text.buffer) + pager._scroll_page(event, pages=1.0) + pager._scroll(event, 1) + pager._scroll_horizontal(event, 1) + assert pager.text.buffer.cursor_position == 0 + assert pager.text.window.horizontal_scroll == 0 + + +@pytest.mark.parametrize("chop", [False, True]) +def test_pager_half_page_scrolling(toolbar_app, chop) -> None: + """Half-page keys move half of what the full-page keys move, and never zero rows.""" + app, pipe, _ = toolbar_app + lines = [f"row {index:03d}" for index in range(200)] + + def script(keys) -> None: + page_rows = max(1, keys.pager.text.window.render_info.window_height - 1) + half_rows = max(1, int(page_rows * 0.5)) + # A half page has to be a distinct, smaller step for this test to mean + # anything. The pager's own arithmetic is what decides the row it lands on. + assert 0 < half_rows < page_rows + keys.press("d", row=half_rows) + keys.press("d", row=2 * half_rows) + keys.press("u", row=half_rows) + keys.press("\x04", row=2 * half_rows) # Ctrl-D. + keys.press("\x15", row=half_rows) # Ctrl-U. + # Half-page steps stay half a page next to a full one taken from the same row. + keys.press("g", row=0) + keys.press("\x1b[6~", row=page_rows) # Page Down. + + drive_pager(app, pipe, "\n".join(lines), chop=chop, script=script) + + +@pytest.mark.parametrize("key", ["\x1b", "\x03"], ids=["escape", "ctrl-c"]) +def test_pager_search_abort_keys(toolbar_app, key) -> None: + """Escape and Ctrl-C abort a search rather than closing the pager. + + While the search field has focus the pager's own close bindings are filtered out, + so these keys have to reach prompt-toolkit's search bindings instead. Those are + registered explicitly so that they still work when the main prompt uses Vi mode. + """ + app, pipe, _ = toolbar_app + lines = [f"row {index:03d}" for index in range(100)] + + def script(keys) -> None: + keys.press("j", row=1) + # Typing a search previews it without moving the pager's own cursor. + keys.press("/row 05", row=1) + # Aborting restores the row the search started from instead of quitting. + keys.press(key, row=1) + # Focus is back on the pager, so ordinary navigation works again. + keys.press("j", row=2) + + drive_pager(app, pipe, "\n".join(lines), chop=False, script=script) + + +@pytest.mark.parametrize("key", ["\x1b", "\x03", "q"], ids=["escape", "ctrl-c", "q"]) +def test_pager_close_keys(toolbar_app, key) -> None: + """Each close key ends the pager without leaving the keystroke for the next prompt. + + Escape is bound eagerly, and it is also the first byte of every arrow and page + key. Closing on a bare Escape must therefore not come at the cost of the escape + sequences that arrive with more bytes behind them. + """ + app, pipe, _ = toolbar_app + entered = threading.Event() + closed = threading.Event() + + def observe(ui) -> None: + if ui.full_screen: + entered.set() + + def interact() -> None: + assert entered.wait(5), "pager never opened" + # Scroll first, so the pager is known to be reading keys before the close key. + pipe.send_text("j") + pipe.send_text(key) + if not closed.wait(5): + # Rescue the blocked main thread so this fails as an assertion, not a hang. + pipe.send_text("q") + raise AssertionError(f"{key!r} did not close the pager") + + app.main_session.app.after_render += observe + with ThreadPoolExecutor() as executor: + interaction = executor.submit(interact) + try: + with app._command_toolbar_context(): + app._command_toolbar.page("\n".join(f"row {index:03d}" for index in range(200)), chop=False) + finally: + closed.set() + interaction.result(timeout=10) + assert get_typeahead(pipe) == [] diff --git a/tests/test_pipeline_job_control.py b/tests/test_pipeline_job_control.py index 2d2df6a05..64dcfe890 100644 --- a/tests/test_pipeline_job_control.py +++ b/tests/test_pipeline_job_control.py @@ -631,6 +631,18 @@ def printing(screen): ) +def test_pager_resumes_with_raw_terminal_after_suspend(tmp_path) -> None: + """Ctrl-Z in the built-in pager, then fg, must bring the pager back, not echoed cursor reports.""" + suspend_and_resume( + tmp_path, + " def do_page(self, statement):\n self.ppaged('\\n'.join(f'line {n:04d}' for n in range(400)))\n", + "page", + lambda screen: any("q: quit" in line for line in screen.display), + # A cooked terminal would hold the key back until Enter: the pager must quit on q alone. + lambda send: send("q"), + ) + + @pytest.mark.parametrize("parent_delay", [False, True]) def test_pipeline_pager_can_set_terminal_modes_at_startup(tmp_path, parent_delay) -> None: """A pager such as less puts the terminal in raw mode as it starts, before reading its pipe. From 0fac70a437389ddbd3c09f2337c8975222e2bcfb Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sat, 14 Nov 2026 23:06:06 -0500 Subject: [PATCH 2/5] Parse paged output a line at a time, when the line is shown The pager parsed the whole text with prompt-toolkit's ANSI parser before showing any of it, and did so twice: once to decide whether the text fits on the screen, once to build the view. That parser makes a fragment of every character. For 100,000 lines the first page took 1.9 seconds and the process grew by 900 MB; for a million lines, 21 seconds and 9 GB. An external pager shows its first page in 0.02 seconds whatever the size. Keep the text and parse a line when the lexer is asked for it, which is when it is about to be shown. The searchable plain text is made by removing the style sequences with a regular expression. A text with more lines than the screen has rows cannot fit, so it is no longer measured to find that out. The first page now takes 0.03 seconds for 100,000 lines and 0.17 for a million, with no memory beyond the text itself. Parsing a line by itself has to give what parsing everything gave: - A style still in effect when a line starts is put in front of it: the style sequences since the text was last reset. Rich resets after every piece of text it styles, so in its output there are none. - Everything else the parser takes out of the text, which could have swallowed a newline, is taken out beforehand the same way: other control sequences, escapes which begin none, and cursor-forward, which the parser writes as spaces. The tests compare the two on a list of awkward texts and on 3,000 random ones; a one-off run of 200,000 random texts found no difference. The one intended difference is readline's zero-width markers, which the parser passed through to the terminal and the pager now leaves out. --- cmd2/pager.py | 113 ++++++++++++++++++++++++++++++++++++------- tests/test_pager.py | 114 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 209 insertions(+), 18 deletions(-) diff --git a/cmd2/pager.py b/cmd2/pager.py index 438dd4e48..36da6b98b 100644 --- a/cmd2/pager.py +++ b/cmd2/pager.py @@ -2,14 +2,15 @@ import re import threading +from array import array from collections.abc import Callable -from functools import partial +from functools import lru_cache, partial +from itertools import accumulate from prompt_toolkit.document import Document from prompt_toolkit.filters import has_focus, is_searching, to_filter -from prompt_toolkit.formatted_text import ANSI, fragment_list_to_text, to_formatted_text +from prompt_toolkit.formatted_text import ANSI, to_formatted_text from prompt_toolkit.formatted_text.base import StyleAndTextTuples -from prompt_toolkit.formatted_text.utils import split_lines from prompt_toolkit.key_binding import KeyBindings from prompt_toolkit.key_binding.bindings import search from prompt_toolkit.key_binding.key_processor import KeyPressEvent @@ -22,14 +23,51 @@ from prompt_toolkit.widgets import SearchToolbar, TextArea _OSC_RE = re.compile(r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)") - - -def _fragments(text: str) -> StyleAndTextTuples: - """Parse captured output, dropping the trailing newline that ends its last line.""" +# A sequence which sets the style of the text after it. It begins with characters which can +# be searched for quickly, which matters in a text with one or more of these on every line. +_SGR_RE = re.compile(r"\x1b\[[0-9;]*m") +# Everything else prompt-toolkit's ANSI parser takes out of the text, in the order it reads. +_OTHER_ESCAPE_RE = re.compile( + # A style sequence which begins with the one-character introducer. + r"\x9b[0-9;]*m" + # Any other control sequence, or one the text ends in the middle of. + r"|(?:\x1b\[|\x9b)[0-9;]*(?:[^0-9;m]|\Z)" + # An escape which begins no control sequence, and the character after it. + r"|\x1b(?:[^\[]|\Z)" + # Readline's zero-width markers and what is between them. + r"|\x01[^\x02]*(?:\x02|\Z)" +) +_RESETS = ("\x1b[0m", "\x1b[m") +# How many lines keep their fragments. A screen shows far fewer. +_PARSED_LINES = 1024 + + +def _other_escape(match: re.Match[str]) -> str: + """Return what prompt-toolkit's parser leaves in the text for an escape which sets no style.""" + sequence = match.group() + if sequence[0] == "\x9b" and sequence[-1] == "m": + return "\x1b[" + sequence[1:] + if sequence[0] != "\x01" and sequence[-1] == "C": + # Cursor forward is written as that many spaces. + count = sequence[2:-1] if sequence[0] == "\x1b" else sequence[1:-1] + return " " * min(int(count.split(";")[0] or 0), 9999) + return "" + + +def _styled_and_plain(text: str) -> tuple[str, str]: + """Return captured output with no escapes but those which set styles, and with none at all. + + Both drop the trailing newline which ends the last line. + """ # prompt-toolkit's ANSI parser does not handle OSC sequences, including Rich # hyperlinks. Remove their metadata while retaining visible text and SGR styles. - text = _OSC_RE.sub("", text) - return to_formatted_text(ANSI(text.removesuffix("\n"))) + styled = _OSC_RE.sub("", text).removesuffix("\n") + plain = _SGR_RE.sub("", styled) + if "\x1b" in plain or "\x9b" in plain or "\x01" in plain: + # Rare, and slow to look for, so not looked for until there is one. + styled = _OTHER_ESCAPE_RE.sub(_other_escape, styled) + plain = _SGR_RE.sub("", styled) + return styled, plain def output_fits(text: str, columns: int, rows: int, *, chop: bool) -> bool: @@ -38,11 +76,15 @@ def output_fits(text: str, columns: int, rows: int, *, chop: bool) -> bool: 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") + plain = _styled_and_plain(text)[1] + if plain.count("\n") >= rows: + # Every line takes a row at least, so no line needs to be measured. + return False + lines = plain.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) + return 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)) @@ -55,14 +97,49 @@ def output_fits(text: str, columns: int, rows: int, *, chop: bool) -> bool: class _AnsiLexer(Lexer): - """Preserve captured Rich styles while searching and scrolling plain text.""" + """Preserve captured Rich styles while searching and scrolling plain text. + + prompt-toolkit's ANSI parser makes a fragment of every character, which for a long text + takes seconds and hundreds of bytes for each character. So a line is parsed when it is + asked for, which is when it is about to be shown. + """ - def __init__(self, fragments: StyleAndTextTuples) -> None: - self.lines = list(split_lines(fragments)) + def __init__(self, styled: str) -> None: + """Keep the text to parse lines of. + + :param styled: the text, with no escape sequences except those which set styles + """ + self._styled = styled + self._lines = styled.split("\n") + # Where each line starts in the text, to find the styles still in effect there. Left + # empty for a text with no styles. + self._starts = array("Q") + if "\x1b" in styled: + self._starts = array("Q", accumulate(map(len, self._lines), lambda start, length: start + length + 1, initial=0)) + self._parsed = lru_cache(maxsize=_PARSED_LINES)(self._parse) + + def _parse(self, number: int) -> StyleAndTextTuples: + return to_formatted_text(ANSI(self._styles_in_effect(number) + self._lines[number])) + + def _styles_in_effect(self, number: int) -> str: + """Return the sequences which set the style a line starts in. + + Those are the ones since the text was last reset to no style. Rich resets after each + piece of text it styles, so in its output nothing is in effect when a line starts. + """ + if not self._starts: + return "" + start = self._starts[number] + since = 0 + for reset in _RESETS: + found = self._styled.rfind(reset, since, start) + if found != -1: + since = found + len(reset) + return "".join(_SGR_RE.findall(self._styled, since, start)) def lex_document(self, document: Document) -> Callable[[int], StyleAndTextTuples]: # noqa: ARG002 def get_line(number: int) -> StyleAndTextTuples: - return self.lines[number] if number < len(self.lines) else [] + return self._parsed(number) if number < len(self._lines) else [] return get_line @@ -75,11 +152,11 @@ def __init__(self, text: str, *, chop: bool) -> None: self.closed = threading.Event() self.on_close: Callable[[], None] = self.closed.set self.chop = chop - fragments = _fragments(text) + styled, plain = _styled_and_plain(text) self.search = SearchToolbar() self.text = TextArea( - text=fragment_list_to_text(fragments), - lexer=_AnsiLexer(fragments), + text=plain, + lexer=_AnsiLexer(styled), read_only=True, wrap_lines=not chop, search_field=self.search, diff --git a/tests/test_pager.py b/tests/test_pager.py index b53aff4de..32f52db24 100644 --- a/tests/test_pager.py +++ b/tests/test_pager.py @@ -1,5 +1,6 @@ """Tests for the built-in pager view.""" +import random import threading import time from concurrent.futures import ThreadPoolExecutor @@ -8,9 +9,12 @@ import pytest from prompt_toolkit.data_structures import Size +from prompt_toolkit.formatted_text import ANSI, fragment_list_to_text, to_formatted_text +from prompt_toolkit.formatted_text.utils import split_lines from prompt_toolkit.input.typeahead import get_typeahead from rich.console import Console +from cmd2 import pager as pager_module from cmd2.pager import Pager, output_fits @@ -54,6 +58,116 @@ def test_output_fits_measures_styled_and_wide_text(chop) -> None: assert output_fits(text, 100, 1, chop=chop) +def parsed_whole(text: str) -> tuple[str, list[list[tuple[str, str]]]]: + """Return the text and styled lines prompt-toolkit makes of captured output parsed in one piece. + + This is what the pager showed when it parsed everything before showing anything. + """ + fragments = to_formatted_text(ANSI(pager_module._OSC_RE.sub("", text).removesuffix("\n"))) + lines = [[(style, char) for style, char, *_ in line if char] for line in split_lines(fragments)] + return fragment_list_to_text(fragments), lines + + +def shown_by_pager(text: str) -> tuple[str, list[list[tuple[str, str]]]]: + """Return the text of a pager's view, and each of its lines as the view styles it.""" + view = Pager(text, chop=False).text + get_line = view.lexer.lex_document(view.document) + lines = [[(style, char) for style, char, *_ in get_line(number) if char] for number in range(view.document.line_count)] + return view.text, lines + + +RICH = Console(force_terminal=True, color_system="truecolor", no_color=False, legacy_windows=False, width=60) + + +def rich_output(*renderables: object) -> str: + with RICH.capture() as capture: + for renderable in renderables: + RICH.print(renderable) + return capture.get() + + +@pytest.mark.parametrize( + "text", + [ + pytest.param("", id="nothing"), + pytest.param("\n", id="one empty line"), + pytest.param("plain\ntext\n\nwith a gap", id="plain text"), + pytest.param("\x1b[31mred\x1b[0m plain \x1b[1;32mbold green\x1b[0m\nnext", id="styles closed on their line"), + pytest.param("\x1b[31mred\nstill red\n\x1b[1mand bold\x1b[0m\nplain", id="a style left open across lines"), + pytest.param("\x1b[31mred\n\x1b[39mdefault\n\x1b[4munderlined\nstill\x1b[m\nplain", id="styles ended without a reset"), + pytest.param("\x1b[38;5;196mindexed\x1b[0m \x1b[38;2;1;2;3mtrue color\x1b[0m", id="indexed and true color"), + pytest.param("a\x1b[5Cb\x1b[Cc", id="cursor forward becomes spaces"), + pytest.param("a\x1b[2Kb\x1b[?25lc\x1b[Hd", id="other control sequences"), + pytest.param("a\x1bXb\x1b\nc", id="an escape which starts no control sequence"), + pytest.param("a\x1b[31\nb\x1b[0mc", id="a newline inside a control sequence"), + pytest.param("a\x1b[31", id="a control sequence cut short"), + pytest.param("a\x1b", id="an escape cut short"), + pytest.param("\x9b31mred\x9b0m plain \x9b2Cgap", id="one-character sequence introducer"), + pytest.param("\x1b\x1b[31mnot red", id="an escape before a control sequence"), + pytest.param("\u754c\x1b[31m\u754c\u754c\x1b[0m e\u0301 \U0001f600", id="wide and combining characters"), + pytest.param("line\r\nwith\tcontrols\x00", id="other control characters"), + pytest.param( + rich_output("[bold red]bold red[/bold red] plain [link=https://example.com]linked[/link]"), id="Rich markup" + ), + pytest.param(rich_output("[on blue]" + "word " * 40), id="a Rich style wrapped over several lines"), + ], +) +def test_pager_shows_what_parsing_the_whole_text_showed(text) -> None: + """Parsing a line when it is shown gives the text and styles that parsing everything first gave.""" + assert shown_by_pager(text) == parsed_whole(text) + + +def test_pager_shows_what_parsing_the_whole_text_showed_for_arbitrary_input() -> None: + """The same, for input nobody thought of: escapes and their parts in every order.""" + pieces = ["\x1b", "[", "0", "1", "3", "9", ";", "m", "C", "?", "\x9b", "\r", "a", "\u754c", " ", "\n", "\n"] + whole = ["\x1b[31m", "\x1b[1m", "\x1b[4;32m", "\x1b[39m", "\x1b[22m", "\x1b[0m", "\x1b[m", "\x1b[0;33m"] + randomizer = random.Random(1743) + for _ in range(3000): + text = "".join(randomizer.choices(pieces + whole, k=randomizer.randrange(24))) + assert shown_by_pager(text) == parsed_whole(text), repr(text) + + +def test_pager_leaves_out_zero_width_markers() -> None: + """Readline's markers, and what is between them, are for a prompt and never shown.""" + assert shown_by_pager("a\x01\x1b[31m\x02b\nc\x01unfinished\nd") == ("ab\nc", [[("", "a"), ("", "b")], [("", "c")]]) + + +def test_pager_parses_only_the_lines_it_is_asked_for(monkeypatch) -> None: + """Opening a pager on a long text costs no more than opening one on a short text. + + prompt-toolkit's parser makes a fragment of every character. Parsing 100,000 lines + before showing any took two seconds and a gigabyte. + """ + parsed = [] + + def counting(value: str) -> ANSI: + parsed.append(value) + return ANSI(value) + + monkeypatch.setattr(pager_module, "ANSI", counting) + text = "\n".join(f"\x1b[32mrow {number}\x1b[0m of output" for number in range(5000)) + + assert not output_fits(text, 80, 23, chop=False) + view = Pager(text, chop=False).text + assert parsed == [] + + get_line = view.lexer.lex_document(view.document) + assert [char for _, char, *_ in get_line(4999)] == list("row 4999 of output") + assert get_line(4999)[0][0] == "ansigreen" + assert get_line(4999) is get_line(4999) + assert parsed == ["\x1b[32mrow 4999\x1b[0m of output"] + + +@pytest.mark.parametrize("chop", [False, True]) +def test_output_fits_measures_only_text_short_enough_to_fit(monkeypatch, chop) -> None: + """Text with more lines than rows cannot fit, however narrow, so none of it is measured.""" + monkeypatch.setattr(pager_module, "get_cwidth", mock.Mock(side_effect=AssertionError("measured"))) + monkeypatch.setattr(pager_module, "UIContent", mock.Mock(side_effect=AssertionError("measured"))) + + assert not output_fits("\x1b[31mrow\x1b[0m\n" * 24, 80, 23, chop=chop) + assert not output_fits("", 80, 0, chop=chop) + + @pytest.mark.parametrize("chop", [False, True]) def test_pager_long_line_navigation_resize_and_typeahead(toolbar_app, chop) -> None: app, pipe, _ = toolbar_app From 242d9d963b9e2b85d06c711398907879d6a8a9fb Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 16:51:14 -0500 Subject: [PATCH 3/5] Keep the built-in pager's pages out of iTerm2's scrollback iTerm2, with its default settings, saves a screen which is erased from its top-left corner to the scrollback, and does so for the alternate screen as well. A prompt-toolkit renderer erases its screen from there whenever it is reset: when the pager closes, each time the terminal is resized while it is open, and when Ctrl-Z lends the terminal. Each left the pager's page, its key summary and a toolbar row in the scrollback of the screen the pager was started from, and growing the window brought them back into view. A plain prompt-toolkit full-screen application does the same; less does not. iTerm2 only does this for an erase which starts in the corner, and the renderer always erases from the first column of a row. While the pager has its screen, a VT100 output now erases the row, then from its second column to the end of the screen. The cells erased and the cursor afterwards are the same. In iTerm2 3.7.7, one pager session with three resizes and a Ctrl-Z left 226 paged rows, 11 key summaries and 11 toolbar rows in the scrollback before this change, and none after it. --- cmd2/command_toolbar.py | 41 ++++++++++++++++++++++- tests/test_command_toolbar.py | 63 +++++++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+), 1 deletion(-) diff --git a/cmd2/command_toolbar.py b/cmd2/command_toolbar.py index 0d59e3e9e..d43f69751 100644 --- a/cmd2/command_toolbar.py +++ b/cmd2/command_toolbar.py @@ -24,6 +24,7 @@ from prompt_toolkit.key_binding.key_processor import KeyPress, KeyPressEvent from prompt_toolkit.layout import HSplit, Layout, Window from prompt_toolkit.layout.containers import ConditionalContainer +from prompt_toolkit.output.vt100 import Vt100_Output from prompt_toolkit.patch_stdout import StdoutProxy from prompt_toolkit.utils import get_cwidth, suspend_to_background_supported @@ -36,6 +37,11 @@ # no room on the screen. _ESCAPE_RE = re.compile(r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])") +# Erases what "erase down" does when the cursor is in the first column of a row, without +# erasing from the top-left corner of the screen: the row itself, then from its second column +# to the end of the screen, and back. +ERASE_DOWN_FROM_FIRST_COLUMN = "\x1b[K\x1b[C\x1b[J\x1b[D" + _F = TypeVar("_F", bound=Callable[..., Any]) _R = TypeVar("_R") @@ -78,6 +84,32 @@ def wrapped(self: "Cmd", *args: Any, **kwargs: Any) -> Any: return cast(_F, wrapped) +@contextlib.contextmanager +def erasing_from_the_second_column(output: Any) -> Generator[None]: + """Have a terminal erase its screen without iTerm2 keeping what was on it. + + iTerm2 saves a screen which is erased from its top-left corner to its scrollback, as a + shell's ``clear`` expects, and the alternate screen is no exception. A renderer erases its + screen from there when it is reset, which a full-screen one is when it closes, when the + terminal is resized and when it lends the terminal. Each would leave a page in the + scrollback of the screen the pager was started from. + + The renderer always erases from the first column of a row, which is what lets the same + cells be erased starting from the second. Only an output which writes escape sequences + itself is changed, and it is put back afterwards. + + :param output: the output the pager is drawn on + """ + if not isinstance(output, Vt100_Output): + yield + return + vars(output)["erase_down"] = functools.partial(output.write_raw, ERASE_DOWN_FROM_FIRST_COLUMN) + try: + yield + finally: + vars(output).pop("erase_down", None) + + def pipe_target(stream: Any) -> Any: """Return the stream a pipe process can inherit, or ``None`` if its output must be captured. @@ -615,11 +647,14 @@ def page(self, text: str, *, chop: bool) -> None: 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 + # Open for as long as the pager has a screen of its own to erase. + own_screen = contextlib.ExitStack() def enter() -> None: nonlocal entered entered = True self.app.renderer.erase() + own_screen.enter_context(erasing_from_the_second_column(self.app.output)) self.app.layout = layout self.app.key_bindings = pager.bindings self.app.editing_mode = EditingMode.EMACS @@ -631,7 +666,10 @@ def leave() -> None: if not entered: return entered = False - self.app.renderer.erase() + try: + self.app.renderer.erase() + finally: + own_screen.close() self.app.layout, self.app.key_bindings, self.app.editing_mode, self.app.full_screen = previous self.app.renderer.full_screen = self.app.full_screen self.app.renderer.request_absolute_cursor_position() @@ -654,6 +692,7 @@ def close() -> None: self._call_in_ui(leave) else: # The application's shutdown already reset the renderer. + own_screen.close() self.app.layout, self.app.key_bindings, self.app.editing_mode, self.app.full_screen = previous self.app.renderer.full_screen = self.app.full_screen diff --git a/tests/test_command_toolbar.py b/tests/test_command_toolbar.py index ab2531c4c..81e9307fe 100644 --- a/tests/test_command_toolbar.py +++ b/tests/test_command_toolbar.py @@ -1274,6 +1274,69 @@ def external(*args, **kwargs): assert app._command_toolbar.is_active +def test_builtin_pager_never_erases_its_screen_from_the_corner(monkeypatch) -> None: + """iTerm2 keeps a screen which is erased from its top-left corner, and so each page so erased. + + A renderer erases its screen that way when it is reset, which it is when the pager closes + and each time the terminal is resized. + """ + stream = Terminal() + entered, resized = threading.Event(), threading.Event() + with create_pipe_input() as pipe: + terminal = Vt100_Output(stream, lambda: Size(rows=24, columns=80), enable_cpr=False) + with create_app_session(input=pipe, output=terminal): + app = Cmd(allow_cli_args=False) + app.stdout = stream + app.use_builtin_pager = True + monkeypatch.setattr(app, "stdin", Terminal()) + app.main_session = PromptSession(input=pipe, output=terminal, bottom_toolbar="STATUS", refresh_interval=0.01) + ui = app.main_session.app + + def resize() -> None: + ui._on_resize() + resized.set() + + def interact() -> None: + try: + assert entered.wait(2) + ui.loop.call_soon_threadsafe(resize) + assert resized.wait(2) + finally: + pipe.send_text("q") + + ui.after_render += lambda _: entered.set() if ui.full_screen else None + with ThreadPoolExecutor() as executor: + interaction = executor.submit(interact) + with app._command_toolbar_context(): + app.ppaged("\n".join(f"row {i:03d}" for i in range(100))) + interaction.result(timeout=2) + + written = stream.getvalue() + paged = written[written.index("\x1b[?1049h") : written.rindex("\x1b[?1049l")] + # Once for the pager's first frame, once for the resize, once for the frame after it, once to close. + assert paged.count("\x1b[J") >= 4 + assert paged.count("\x1b[J") == paged.count(command_toolbar.ERASE_DOWN_FROM_FIRST_COLUMN) + # The terminal's own way of erasing is back once the pager has closed. + assert "erase_down" not in vars(terminal) + + +@pytest.mark.parametrize("row", [0, 1, 11, 23]) +def test_erase_down_from_first_column_erases_what_erase_down_does(row) -> None: + """The longer way round leaves the same screen, and the cursor where it was.""" + import pyte + + def shown(erase: str) -> tuple[list[str], int, int]: + screen = pyte.Screen(20, 24) + stream = pyte.Stream(screen) + stream.feed("\r\n".join(f"row {number:02d} filled to the edge"[:20] for number in range(24))) + stream.feed(f"\x1b[{row + 1};1H{erase}") + return list(screen.display), screen.cursor.x, screen.cursor.y + + kept = [f"row {number:02d} filled to the edge"[:20] for number in range(row)] + assert shown(command_toolbar.ERASE_DOWN_FROM_FIRST_COLUMN) == shown("\x1b[J") + assert shown(command_toolbar.ERASE_DOWN_FROM_FIRST_COLUMN) == (kept + [" " * 20] * (24 - row), 0, row) + + def test_builtin_pager_eof_restores_prompt(toolbar_app) -> None: app, pipe, output = toolbar_app layout = app.main_session.app.layout From 9dc18808744772d09d3364637c7711b86b6f2cde Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 16:53:59 -0500 Subject: [PATCH 4/5] Set TERM in the test of the pager's erases, as the other pager test does ppaged() does not page without one, and a CI runner does not have one. --- tests/test_command_toolbar.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/test_command_toolbar.py b/tests/test_command_toolbar.py index 81e9307fe..2aba56708 100644 --- a/tests/test_command_toolbar.py +++ b/tests/test_command_toolbar.py @@ -1289,6 +1289,7 @@ def test_builtin_pager_never_erases_its_screen_from_the_corner(monkeypatch) -> N app.stdout = stream app.use_builtin_pager = True monkeypatch.setattr(app, "stdin", Terminal()) + monkeypatch.setenv("TERM", "xterm") app.main_session = PromptSession(input=pipe, output=terminal, bottom_toolbar="STATUS", refresh_interval=0.01) ui = app.main_session.app From a6e4c58772cb4f3351a90e6eed22c11c2207a379 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:02:22 -0500 Subject: [PATCH 5/5] Keep the built-in pager when the external one cannot be run Merging main brought in the check which stops ppaged() from trying again a pager command the shell could not run. It landed on the condition which guards both pagers, so once the external pager had failed, as it can for a command run outside the command loop, the built-in pager was skipped too and the output was printed without paging. Decide which pager will be used before that check and apply it only to the external one. --- cmd2/cmd2.py | 23 ++++++++++++++--------- docs/features/os.md | 11 ++++++----- tests/test_command_toolbar.py | 18 ++++++++++++++++++ 3 files changed, 38 insertions(+), 14 deletions(-) diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 6ee51177b..de5a256db 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -2024,8 +2024,9 @@ def ppaged( command instead; external pagers temporarily hide the toolbar. Where no toolbar is running, such as outside the command loop, the external pager is used regardless. - If the pager program cannot be run, for example because it is not installed, the output - is printed without one. That pager command is not tried again while the application runs. + If the external pager program cannot be run, for example because it is not installed, the + output is printed without one. That pager command is not tried again while the application + runs. The built-in pager is not affected. :param chop: True -> causes lines longer than the screen width to be chopped (truncated) rather than wrapped - truncated text is still accessible by scrolling with the right & left arrow keys @@ -2054,8 +2055,15 @@ def ppaged( pager = self.pager_chop if chop else self.pager - # Check if we are outputting to a pager. One which the shell could not run is not tried again. - if functional_terminal and can_block and pager not in self._unrunnable_pagers: + # Page inside the toolbar's display only when the command loop is already + # running one. Starting one here would seize the terminal for commands run + # outside that loop, which the toolbar is documented not to do. + toolbar = self._command_toolbar + builtin_pager = toolbar if self.use_builtin_pager and toolbar is not None and toolbar.is_active else None + + # Check if we are outputting to a pager. An external one which the shell could not run is not tried again, + # which is no reason to go without the built-in pager. + if functional_terminal and can_block and (builtin_pager is not None or pager not in self._unrunnable_pagers): # Chopping overrides soft_wrap, but only for what the pager is given pager_soft_wrap = soft_wrap or chop @@ -2078,11 +2086,8 @@ def ppaged( ) output = capture.get() - # Page inside the toolbar's display only when the command loop is already - # running one. Starting one here would seize the terminal for commands run - # outside that loop, which the toolbar is documented not to do. - if self.use_builtin_pager and self._command_toolbar is not None and self._command_toolbar.is_active: - self._command_toolbar.page(output, chop=chop) + if builtin_pager is not None: + builtin_pager.page(output, chop=chop) return # As for a pipe: the pager gets UTF-8, and on Windows the console is UTF-8 while it runs. diff --git a/docs/features/os.md b/docs/features/os.md index 12755ab74..c377f5e22 100644 --- a/docs/features/os.md +++ b/docs/features/os.md @@ -85,11 +85,12 @@ The setting only ever turns the embedded pager off. Because the embedded pager s display, it is unavailable anywhere a toolbar is not running, such as a command invoked outside the command loop, and `ppaged()` uses the external pager there regardless of this setting. -The pager is the command in `self.pager`, or `self.pager_chop` when chopping long lines: `less` on -POSIX systems and `more` on Windows by default. If that program cannot be run, for example because -it is not installed, the output is printed without paging. A pager command which could not be run is -not tried again while the application is running. `self.pager` and `self.pager_chop` are separate -commands, so the shell may report each of them once. +The external pager is the command in `self.pager`, or `self.pager_chop` when chopping long lines: +`less` on POSIX systems and `more` on Windows by default. If that program cannot be run, for example +because it is not installed, the output is printed without paging. A pager command which could not +be run is not tried again while the application is running. `self.pager` and `self.pager_chop` are +separate commands, so the shell may report each of them once. The embedded pager runs no program, so +none of this affects it. Alternatively, a terminal pager can be invoked directly using the ability to run shell commands with the `!` shortcut like so: diff --git a/tests/test_command_toolbar.py b/tests/test_command_toolbar.py index 2aba56708..aeddbe8d1 100644 --- a/tests/test_command_toolbar.py +++ b/tests/test_command_toolbar.py @@ -1258,6 +1258,24 @@ def test_builtin_pager_needs_an_already_running_toolbar(toolbar_app, monkeypatch external.assert_called_once() +def test_builtin_pager_is_used_after_the_external_pager_could_not_be_run(toolbar_app, monkeypatch) -> None: + app, _, _ = toolbar_app + app.use_builtin_pager = True + monkeypatch.setattr(app, "stdin", Terminal()) + monkeypatch.setenv("TERM", "xterm") + # The external pager is what pages outside the command loop, and one the shell could not run there is not + # tried again. That says nothing about the built-in pager, which runs no program. + app._unrunnable_pagers.add(app.pager) + with ( + mock.patch.object(command_toolbar.CommandToolbar, "page") as page, + mock.patch("subprocess.Popen") as external, + app._command_toolbar_context(), + ): + app.ppaged("row\n" * 200) + page.assert_called_once() + external.assert_not_called() + + def test_external_pager_suspends_shared_application(toolbar_app, monkeypatch) -> None: app, _, _ = toolbar_app app.use_builtin_pager = False