diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d121708f..78421ba0b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,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.3 (2026-11-16) diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 374d62f40..de5a256db 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -662,6 +662,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" @@ -2015,18 +2019,21 @@ 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. - 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 - 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. @@ -2048,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 @@ -2070,8 +2084,14 @@ def ppaged( soft_wrap=pager_soft_wrap, **(rich_print_kwargs if rich_print_kwargs is not None else {}), ) + output = capture.get() + + 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. - 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. @@ -2190,8 +2210,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..d43f69751 100644 --- a/cmd2/command_toolbar.py +++ b/cmd2/command_toolbar.py @@ -12,18 +12,24 @@ 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 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 +from .pager import Pager, output_fits + if TYPE_CHECKING: from .cmd2 import Cmd @@ -31,7 +37,13 @@ # 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") def suspend_process_group(suspend_group: bool = True) -> None: @@ -72,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. @@ -341,6 +379,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 +437,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 +592,110 @@ 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 + # 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 + self.app.full_screen = self.app.renderer.full_screen = True + self.app.invalidate() + + def leave() -> None: + nonlocal entered + if not entered: + return + entered = False + 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() + 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. + 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 + @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..36da6b98b --- /dev/null +++ b/cmd2/pager.py @@ -0,0 +1,306 @@ +"""A pager view hosted by the main prompt-toolkit application.""" + +import re +import threading +from array import array +from collections.abc import Callable +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, to_formatted_text +from prompt_toolkit.formatted_text.base import StyleAndTextTuples +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\\)") +# 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. + 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: + """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. + """ + 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 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. + + 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, 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._parsed(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 + styled, plain = _styled_and_plain(text) + self.search = SearchToolbar() + self.text = TextArea( + text=plain, + lexer=_AnsiLexer(styled), + 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 5c2329218..c377f5e22 100644 --- a/docs/features/os.md +++ b/docs/features/os.md @@ -46,14 +46,51 @@ 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. - -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. +### 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. + +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: @@ -62,7 +99,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 20c0ed897..886a4a203 100644 --- a/docs/features/prompt.md +++ b/docs/features/prompt.md @@ -157,8 +157,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..aeddbe8d1 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,125 @@ 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_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 monkeypatch.setattr(app, "stdin", Terminal()) monkeypatch.setenv("TERM", "xterm") @@ -1073,3 +1290,97 @@ 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_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()) + monkeypatch.setenv("TERM", "xterm") + 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 + + 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..32f52db24 --- /dev/null +++ b/tests/test_pager.py @@ -0,0 +1,437 @@ +"""Tests for the built-in pager view.""" + +import random +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.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 + + +@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) + + +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 + 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 0cf69d562..ef5705d39 100644 --- a/tests/test_pipeline_job_control.py +++ b/tests/test_pipeline_job_control.py @@ -635,6 +635,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.