diff --git a/CHANGELOG.md b/CHANGELOG.md index bf18cca73..d53fce745 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,27 @@ appear until a key was pressed. - A line of command output left unfinished before `Cmd.ppaged()` opens the built-in pager is no longer deleted in reserved toolbar mode. + - The built-in pager now uses the terminal's alternate screen in reserved toolbar mode, as it + does in legacy mode. It was drawn over the main screen, and left a page of paged rows, its key + summary and a second toolbar row in the scrollback. + - Command output wider than the terminal wraps in reserved toolbar mode on Windows, as it does + in legacy mode. Everything past the last column of such a line was lost. + - In reserved toolbar mode, output written while a frame of the built-in pager or a prompt is + being prepared no longer leaves that frame, which is never shown, as the one the next frame is + compared with. The next frame could draw nothing and leave the screen as it was. + - In reserved toolbar mode, output written after such a frame is prepared and before it is shown + no longer leaves the cursor recorded where that frame would have put it. The next frame could + be drawn in the wrong rows. + - The reserved bottom toolbar is drawn as a reverse-video bar, as the toolbar is in legacy mode. + It was drawn as plain text. Theme rules for `bottom-toolbar` and `bottom-toolbar.text` now + apply to its text as well as to the rest of the row. + - Resizing the terminal while a command is printing damages its output far less often in + reserved toolbar mode. In iTerm2, a line was printed over the old toolbar and the rest of the + toolbar left in the output, and growing the window erased a line of output. A resize during a + command is now acted on at once where there is a window-change signal, instead of within half + a second, and the old toolbar is cleared from wherever the terminal has moved it. A line can + still be printed over the old toolbar when a command is printing hundreds of lines a second as + the window is resized. - Background output printed above an active reserved prompt through `run_in_terminal()` or `patch_stdout()` is preserved when the prompt redraws. - Reserved rendering preserves unfinished command output when the main prompt returns by diff --git a/cmd2/command_toolbar.py b/cmd2/command_toolbar.py index 5146ab55f..a9009ae4a 100644 --- a/cmd2/command_toolbar.py +++ b/cmd2/command_toolbar.py @@ -548,6 +548,42 @@ def _restore_stream(obj: Any, name: str, stream: ToolbarStream) -> None: if getattr(obj, name) is stream: setattr(obj, name, stream.original) + def _watch_for_resizes(self, stack: contextlib.ExitStack) -> None: + """Have the display hear of a resize at once, for as long as it holds a reservation. + + A terminal sets its scroll region back to the whole screen when it is resized. From + then until the region is installed again, a line of command output written on the last + row above the toolbar moves on to the toolbar's row, and the next is written over it. + prompt-toolkit only looks at the size of the terminal twice a second from a thread + other than the main one, which is where the display runs. The signal comes to the + main thread, where the command is, and is passed on from there. + + :param stack: what is undone when the display stops + """ + sigwinch = getattr(signal, "SIGWINCH", None) + if sigwinch is None or threading.current_thread() is not threading.main_thread(): + return + previous = signal.getsignal(sigwinch) + if previous is None: + # Installed by something other than Python, which could not be put back. + return + + def resized(signum: int, frame: Any) -> None: + # Rendering is where the bridge looks at the size, and asking for it is safe from + # a signal handler. This runs in the middle of whatever the command is doing, so + # a loop which has just closed must not become the command's exception. + with contextlib.suppress(RuntimeError): + self.app.invalidate() + if callable(previous): + previous(signum, frame) + + def restore() -> None: + if threading.current_thread() is threading.main_thread() and signal.getsignal(sigwinch) is resized: + signal.signal(sigwinch, previous) + + signal.signal(sigwinch, resized) + stack.callback(restore) + def _resume(self) -> None: if self._failed: return @@ -582,6 +618,7 @@ def _resume(self) -> None: # question -- the display is up either way -- so it hangs on the attempt instead. bridge.set_render_attempted_handler(self._display_started_without_app) stack.callback(bridge.set_render_attempted_handler, None) + self._watch_for_resizes(stack) context = contextvars.copy_context() def run() -> None: diff --git a/cmd2/managed_output.py b/cmd2/managed_output.py index 812b2aa38..0220f118c 100644 --- a/cmd2/managed_output.py +++ b/cmd2/managed_output.py @@ -49,6 +49,12 @@ def __init__(self, stream: "TextIO", lock: TerminalLock, bridge: Any = None, *, self._lock = lock self.bridge = bridge self._output = output + # prompt-toolkit's Windows backend sets the console mode around every flush, and the + # mode it sets does not wrap at the end of a row: what is written past the last column + # is written over it. Upstream's stdout proxy turns autowrap on before each write for + # that reason, and this writer takes that proxy's place. That backend is the one which + # holds a VT writer of its own; any other is sent exactly what it was given. + self._flush_resets_autowrap = hasattr(output, "vt100_output") @property def stream(self) -> "TextIO": @@ -69,6 +75,8 @@ def write(self, data: str) -> int: if self._output is None: written = self._stream.write(data) else: + if self._flush_resets_autowrap: + self._output.enable_autowrap() self._output.write_raw(data) written = len(data) # Flushed before the lock is given up. Left buffered, this output would reach diff --git a/cmd2/output_recorder.py b/cmd2/output_recorder.py index f68a68080..9d761e9f9 100644 --- a/cmd2/output_recorder.py +++ b/cmd2/output_recorder.py @@ -42,10 +42,14 @@ class UnrecordableOperationError(RuntimeError): """Raised for an operation that cannot be deferred to commit time. - Screen-buffer transitions and viewport moves change what every later coordinate means. - They are ownership boundaries, taken explicitly before a frame is prepared for the new - screen, so meeting one during preparation means a frame is being prepared against a + Leaving the alternate screen and moving the viewport change what every later coordinate + means. They are ownership boundaries, taken explicitly before a frame is prepared for the + new screen, so meeting one during preparation means a frame is being prepared against a terminal that is no longer the one it was measured on. + + Entering the alternate screen is the exception, and is recorded. A renderer does it as + the first thing in a full-screen frame, having laid that frame out for the whole + terminal, so the switch and the frame belong together: both are emitted or neither is. """ @@ -239,13 +243,13 @@ def fileno(self) -> int: # -- ownership boundaries, which cannot be deferred ------------------------------------ def enter_alternate_screen(self) -> None: - """Refuse to record a switch to the alternate screen. + """Record a switch to the alternate screen, which the rest of the frame is drawn on. - :raises UnrecordableOperationError: always + A renderer marks itself as switched before it calls this. Whoever drops the frame + instead of replaying it has to undo that mark, or the next frame is prepared for a + screen the terminal is not showing. """ - raise UnrecordableOperationError( - "entering the alternate screen is an ownership transition and cannot be recorded in a frame" - ) + self._record("enter_alternate_screen") def quit_alternate_screen(self) -> None: """Refuse to record a return to the main screen. diff --git a/cmd2/prompt_toolkit_bridge.py b/cmd2/prompt_toolkit_bridge.py index 91e750bf2..8ad423c4f 100644 --- a/cmd2/prompt_toolkit_bridge.py +++ b/cmd2/prompt_toolkit_bridge.py @@ -44,9 +44,8 @@ from .terminal_display import TerminalDisplay -#: How many frames in a row may fail to prepare and still be retried at once. One is -#: expected: a full-screen layout's first frame enters the alternate screen, which cannot be -#: recorded in a frame. +#: How many frames in a row may fail to prepare and still be retried at once. A layout +#: callback which raises once is given another chance; one which always raises is not. _MAX_PREPARATION_RETRIES = 2 #: Trailing control that moves nothing the user can see: carriage returns, CSI sequences such @@ -97,6 +96,16 @@ class PreparedRender: #: What the frame was prepared against. generations: Generations + #: Whether the renderer was on the alternate screen before it prepared this frame. A + #: full-screen frame enters it, and one which is not emitted has to leave the renderer + #: believing what it did before. + in_alternate_screen: bool = False + + #: Where the renderer had the cursor before it prepared this frame. It takes the frame's + #: cursor as the terminal's while the frame is only prepared, and one which is not emitted + #: has moved nothing. + cursor_before: Point | None = None + @dataclass(frozen=True) class TerminalModePolicy: @@ -168,6 +177,10 @@ def __init__(self, renderer: "Renderer", display: "TerminalDisplay", lock: Termi self._after_render_installed: Any = None self._render_suppressed = False self._unfinished_command_output = False + # Whether the last thing to move the cursor was command output ending a line, which + # leaves it at the start of a row holding none of that output. Not the opposite of the + # flag above: after a guest program or an erase, neither is known. + self._command_output_ended_a_line = False # -- what is known --------------------------------------------------------------------- @@ -282,14 +295,19 @@ def note_managed_write(self, prompt_anchor: int | None = None, *, data: str | No visible = _TRAILING_CONTROL.sub("", data) if visible: self._unfinished_command_output = not visible.endswith("\n") + self._command_output_ended_a_line = visible.endswith("\n") self._prompt_anchor = prompt_anchor # Only the frame in flight goes; it was prepared against the cursor and content this # write moved, so committing it would emit a stale frame. The renderer's baseline is # reset to the last committed screen -- not left as the advance a pending preparation # made, which the terminal never received, and not cleared, which would force the next # frame to erase down over the output just written. - self._in_flight = None + dropped, self._in_flight = self._in_flight, None self._renderer._last_screen = self._committed_screen + if dropped is not None and dropped.cursor_before is not None: + # The renderer's cursor is likewise where the dropped frame would have left it. + # The next frame moves from there, so it goes back to where it was before. + self._renderer._cursor_pos = dropped.cursor_before self._request_redraw() @property @@ -307,6 +325,7 @@ def forget_unfinished_command_output(self) -> None: the guest's to finish, as it was before the reservation existed. """ self._unfinished_command_output = False + self._command_output_ended_a_line = False def before_managed_write(self) -> None: """Remove retained pager-startup cells before output can scroll them into history. @@ -443,10 +462,9 @@ def _retry_frame(self) -> None: Not through ``_request_redraw()``. A request made before this frame began is still marked pending, because only a committed frame clears it and the command display's suppressed frames never commit. The scheduling which went with that request is what - ran this frame, so a retry coalesced into it would never be scheduled at all: the - built-in pager's first frame, which cannot be prepared because it enters the - alternate screen, would not be followed by a second until a key or a refresh timer - caused one. + ran this frame, so a retry coalesced into it would never be scheduled at all: a + frame of the built-in pager's which could not be prepared would not be followed by + another until a key or a refresh timer caused one. A frame whose preparation keeps raising is retried only a few times. Its layout is broken until something changes, and whatever changes it causes a frame of its own. @@ -644,7 +662,9 @@ def _reconfigure_if_resized(self) -> None: elif self._display.terminal.physical_size() == geometry.physical_size: return else: - self._display.reconfigure() + # While a command has the terminal, the row output has just moved on to may be + # the old band's: the terminal dropped the scroll region when it was resized. + self._display.reconfigure(cursor_row_is_fresh=self._render_suppressed and self._command_output_ended_a_line) self.forget_prompt_anchor() # A prompt owes recovery: its origin has to be re-established from the terminal, and # its frame repainted. A command does not -- it owns the cursor and is still writing @@ -796,11 +816,18 @@ def prepare(self, app: "Application[Any]", layout: Any = None, *, is_done: bool # them would consume a screen that does not exist. self._preparing = True render = self._originals.get("render", self._renderer.render) + # A full-screen frame begins by entering the alternate screen, and the renderer marks + # itself as there before anything is emitted. + in_alternate_screen = self._renderer._in_alternate_screen + # What the terminal was last sent, and where that left the cursor. The renderer takes + # the frame it is about to prepare as both, whether or not the frame is emitted. + baseline = (self._renderer._last_screen, self._renderer._cursor_pos) try: render(app, app.layout if layout is None else layout, is_done) except Exception as error: # noqa: BLE001 - a layout callback must not end a command self._pending_error = error self._failed_preparations += 1 + self._forget_screen_switch(in_alternate_screen) self.require_resynchronization("preparing the frame raised") return None finally: @@ -819,6 +846,7 @@ def prepare(self, app: "Application[Any]", layout: Any = None, *, is_done: bool # reservation outright. Either way the operations are recorded against a # terminal that has moved on. self._retire() + self._forget_screen_switch(in_alternate_screen) return None if self.generations() != generations: @@ -826,10 +854,23 @@ def prepare(self, app: "Application[Any]", layout: Any = None, *, is_done: bool # recovery of its own -- command output leaves the empty command display's # baseline correct -- but the frame was recorded against the cursor and content # that write moved, so it must not be published as current. + # + # Nor may it stay the renderer's baseline. The write put back the last + # committed screen, but the renderer was still preparing and has since taken + # this frame in its place. Diffed against a frame the terminal never received, + # the next one would find nothing to draw where the two agree, and what is on + # the terminal would stay as it was. self._in_flight = None + self._renderer._last_screen, self._renderer._cursor_pos = baseline + self._forget_screen_switch(in_alternate_screen) return None - prepared = PreparedRender(batch=recorder.batch(), generations=generations) + prepared = PreparedRender( + batch=recorder.batch(), + generations=generations, + in_alternate_screen=in_alternate_screen, + cursor_before=baseline[1], + ) self._in_flight = prepared return prepared @@ -841,31 +882,8 @@ def commit(self, prepared: PreparedRender) -> bool: """ assert_no_terminal_transaction("committing a prepared frame") with self._lock.transaction("commit", generation=prepared.generations.geometry): - if prepared is not self._in_flight: - # Already retired, or from a previous attempt. Replaying it would emit a frame - # nothing has validated, and possibly emit it twice. - # - # Read here, after the terminal has been acquired: read before the wait, it - # answers a question about a terminal somebody else still held, since a writer - # can retire the batch while this call queues, changing neither the - # generations nor the size. - return False - if self._needs_resynchronization or self._reserved_emission_stopped: - # Not covered by the identity test above. Retirement clears the frame in - # flight, but a preparation completing concurrently can publish a new one over - # that retirement, and the frame it publishes matches on identity and on every - # generation. What makes it uncommittable is the state of the terminal, so - # that is what is asked. - return False - if self.generations() != prepared.generations: - self.require_resynchronization("the terminal changed between preparing and committing") - return False - if prepared.batch.facts.size != self._display.output.get_size(): - # The generations can agree while the frame was laid out for a different - # terminal -- the geometry is read once per snapshot, and the batch carries - # what the renderer actually branched on. The frame's own facts are the last - # word on whether it still fits. - self.require_resynchronization("the frame was laid out for a different size") + if not self._still_current(prepared): + self._forget_screen_switch(prepared.in_alternate_screen) return False try: # Preparation may be expensive for a large pager. Its main-screen bar is @@ -877,6 +895,10 @@ def commit(self, prepared: PreparedRender) -> bool: # Some of the batch reached the terminal and some did not, and nothing here # knows where the boundary was. The frame is never replayed: a retry would # duplicate whatever already landed. + # + # The renderer keeps what the frame told it about the alternate screen. The + # switch is the first thing in a frame, so it has probably happened, and a + # renderer which wrongly believes it is there only leaves once too often. self._pending_error = error self.require_resynchronization("a frame was only partly emitted") self._attempt_cleanup() @@ -890,6 +912,57 @@ def commit(self, prepared: PreparedRender) -> bool: self._redraw_pending = False return True + def _forget_screen_switch(self, in_alternate_screen: bool) -> None: + """Undo what preparing a frame told the renderer about the alternate screen. + + A full-screen frame begins by entering the alternate screen, and the renderer marks + itself as there while the frame is only being prepared. A frame which is then not + emitted did not switch screens. Left believing otherwise, the renderer would prepare + the next frame without the switch, and draw it over the main screen. + + :param in_alternate_screen: whether the renderer was there before preparing the frame + """ + renderer = self._renderer + if renderer._in_alternate_screen and not in_alternate_screen: + renderer._in_alternate_screen = False + # What the frame drew was laid out for a screen the terminal never showed, so it + # is no baseline for the frame which does switch. + renderer._last_screen = None + renderer._cursor_pos = Point(x=0, y=0) + + def _still_current(self, prepared: PreparedRender) -> bool: + """Return whether a prepared frame still describes the terminal, inside the transaction. + + :param prepared: the frame about to be emitted + """ + if prepared is not self._in_flight: + # Already retired, or from a previous attempt. Replaying it would emit a frame + # nothing has validated, and possibly emit it twice. + # + # Read here, after the terminal has been acquired: read before the wait, it + # answers a question about a terminal somebody else still held, since a writer + # can retire the batch while this call queues, changing neither the + # generations nor the size. + return False + if self._needs_resynchronization or self._reserved_emission_stopped: + # Not covered by the identity test above. Retirement clears the frame in + # flight, but a preparation completing concurrently can publish a new one over + # that retirement, and the frame it publishes matches on identity and on every + # generation. What makes it uncommittable is the state of the terminal, so + # that is what is asked. + return False + if self.generations() != prepared.generations: + self.require_resynchronization("the terminal changed between preparing and committing") + return False + if prepared.batch.facts.size != self._display.output.get_size(): + # The generations can agree while the frame was laid out for a different + # terminal -- the geometry is read once per snapshot, and the batch carries + # what the renderer actually branched on. The frame's own facts are the last + # word on whether it still fits. + self.require_resynchronization("the frame was laid out for a different size") + return False + return True + def _attempt_cleanup(self) -> bool: """Bring the terminal back to a known state after a partial commit. diff --git a/cmd2/reserved_toolbar.py b/cmd2/reserved_toolbar.py index 0b654eb82..2bfc2bd26 100644 --- a/cmd2/reserved_toolbar.py +++ b/cmd2/reserved_toolbar.py @@ -26,7 +26,7 @@ from prompt_toolkit.filters import Condition, Never from prompt_toolkit.layout import HSplit, Window from prompt_toolkit.layout.containers import ConditionalContainer -from prompt_toolkit.styles import DynamicStyle +from prompt_toolkit.styles import DynamicStyle, default_ui_style, merge_styles from prompt_toolkit.utils import suspend_to_background_supported from .command_toolbar import suspend_process_group @@ -213,12 +213,16 @@ def start(self) -> bool: # invalidations, its key presses -- rather than inventing a second timer, and it # paints after the prompt rather than into the middle of it. self._bridge.set_frame_committed_handler(self.refresh) + # Styled as prompt-toolkit styles the toolbar it draws itself. An application's + # style is laid over prompt-toolkit's default one, which is what makes that + # toolbar a reverse-video bar; its window has one class and its text another. self._painter = ToolbarPainter( display=display, lock=self._lock, - style=DynamicStyle(get_pt_theme), + style=merge_styles([default_ui_style(), DynamicStyle(get_pt_theme)]), color_depth=app.color_depth, default_style="class:bottom-toolbar", + text_style="class:bottom-toolbar class:bottom-toolbar.text", ) # Strict on the way in: a band that cannot be painted at all is a reservation # that cannot be established, and the rollback below hands the terminal back diff --git a/cmd2/terminal_display.py b/cmd2/terminal_display.py index b9d8e885e..eb5587921 100644 --- a/cmd2/terminal_display.py +++ b/cmd2/terminal_display.py @@ -265,18 +265,33 @@ def make_room_for_region(self, geometry: Geometry) -> None: self._output.write_raw("\x1bD" * rows + f"\x1b[{rows}A") self._output.flush() - def erase_rows(self, first: int, last: int) -> None: - """Clear whole physical rows, preserving the cursor. - - Used to wipe the old toolbar's rows when a resize leaves them inside the screen. The - erase is by line, so it does not depend on the scroll margins, and the cursor is saved - and restored around it so the caller's position survives. - - :param first: the one-based first row to clear - :param last: the one-based last row to clear, inclusive + def erase_below_cursor(self, *, cursor_row_is_fresh: bool = False) -> None: + """Clear every row below the one the cursor is on, preserving the cursor. + + Used to wipe the old toolbar after a resize. Where its rows are by then depends on the + terminal: one which adds rows at the bottom leaves them where they were, one which + brings rows back from its scrollback moves them down with everything else, and one + which rewraps a narrower window can turn each into two. In every case they are still + below the row the cursor is on, which the rows of the old band always were. + + Unless output has moved on to them. A terminal sets its scroll region back to the + whole screen when it is resized, and the next line of output to end then leaves the + cursor at the start of the old band's first row instead of scrolling the region. A row + which output has only just moved on to holds nothing of that output's, so it is + cleared with the rows below it. + + The cursor must not be on the last row, where moving down would not move it and the + erase would take the row it is on. Making room for the new band sees to that. + + :param cursor_row_is_fresh: whether the cursor is at the start of a row which command + output has just moved on to, and has written nothing on """ - moves = "".join(f"\x1b[{row};1H\x1b[2K" for row in range(first, last + 1)) - self._output.write_raw(f"{cursor_save_sequence()}{moves}{cursor_restore_sequence()}") + if cursor_row_is_fresh: + # From the second column, with the first cleared separately: iTerm2 saves a screen + # which is erased from its top-left corner to its scrollback, band and all. + self._output.write_raw("\x1b[K\x1b[C\x1b[J\x1b[D") + else: + self._output.write_raw(f"{cursor_save_sequence()}\x1b[B\r\x1b[J{cursor_restore_sequence()}") self._output.flush() def install_region(self, geometry: Geometry) -> None: @@ -442,7 +457,7 @@ def _teardown(self) -> None: geometry, self._geometry = self._geometry, None self._terminal.release_region(geometry) - def reconfigure(self) -> bool: + def reconfigure(self, *, cursor_row_is_fresh: bool = False) -> bool: """Resample the terminal and re-establish the reservation for the new geometry. Used after a resize, and on the way back from a handoff. A terminal that has shrunk @@ -450,6 +465,8 @@ def reconfigure(self) -> bool: reacquires. An unqualified backend never installs anything: a refused acquisition still holds a lease, so capability is re-checked here rather than assumed settled. + :param cursor_row_is_fresh: whether the cursor is at the start of a row which command + output has just moved on to, so that the row holds none of it :return: whether a reservation is installed after this call """ if self._depth == 0: @@ -478,17 +495,16 @@ def reconfigure(self) -> bool: # margins -- which is also what making room needs, so that an index at the bottom # scrolls the whole screen rather than an obsolete region. self._terminal.release_region() - if geometry.physical_rows > previous.physical_rows: - # The terminal grew, so the rows the old band occupied are now inside the - # screen and still hold its stale text. They never scrolled -- the band sits - # outside the scroll region -- so they hold nothing but the old toolbar and - # are safe to clear before the new region is installed. - self._terminal.erase_rows(previous.usable_rows + 1, previous.physical_rows) # A terminal that shrank may have left the cursor, and the output on its row, in # the rows the new band will take. Making room scrolls that output up into the # usable region and moves the cursor with it, column intact, before the band is # installed over those rows and painted. self._terminal.make_room_for_region(geometry) + # The old band's text is still on the screen, and not necessarily on the rows it + # was painted on: see erase_below_cursor(). It is below the cursor's row wherever + # the terminal has put it, and so is nothing else: output goes on from the cursor, + # and a prompt redraws itself after a resize. + self._terminal.erase_below_cursor(cursor_row_is_fresh=cursor_row_is_fresh) self._terminal.install_region(geometry) self._geometry = geometry if self._adapter is None: diff --git a/cmd2/toolbar_painter.py b/cmd2/toolbar_painter.py index 063b7d416..2b0104ac8 100644 --- a/cmd2/toolbar_painter.py +++ b/cmd2/toolbar_painter.py @@ -125,6 +125,7 @@ def build( width: int, height: int, default_style: str = "", + text_style: str = "", ) -> "ToolbarFrame": """Lay content out into a frame of exactly ``height`` by ``width`` cells. @@ -141,6 +142,8 @@ def build( :param width: the terminal width in columns :param height: the height of the reserved band in rows :param default_style: the style for padding and truncation-indicator cells + :param text_style: the style under every fragment's own, as a window's style is under + the text it holds :return: the frame :raises ValueError: if ``width`` or ``height`` is not positive """ @@ -153,7 +156,7 @@ def build( # value, and this runs on every refresh, where constructing one per column was most # of the cost of laying out a short toolbar. pad = Cell(" ", default_style) - lines = list(split_lines(to_formatted_text(content))) + lines = list(split_lines(to_formatted_text(content, style=text_style))) rows: list[list[Cell]] = [] for line in lines[:height]: row, clipped = _clip_line(line, width, pad) @@ -325,6 +328,7 @@ def __init__( style: "BaseStyle", color_depth: ColorDepth, default_style: str = "", + text_style: str = "", autowrap_after_paint: bool = True, ) -> None: """Bind a painter to the display that owns the reservation. @@ -342,6 +346,7 @@ def __init__( :param style: the style rules used to resolve fragment styles :param color_depth: the color depth to render attributes at :param default_style: the style for padding and truncation-indicator cells + :param text_style: the style under every fragment's own :param autowrap_after_paint: the committed autowrap policy to restore afterwards. Upstream's renderer leaves autowrap enabled between frames, which is the default here; a bridge that has committed a different policy passes it instead. @@ -352,6 +357,7 @@ def __init__( self._style = style self._color_depth = color_depth self._default_style = default_style + self._text_style = text_style self._autowrap_after_paint = autowrap_after_paint self._last_frame: ToolbarFrame | None = None self._last_attrs: Mapping[str, Attrs] | None = None @@ -410,6 +416,7 @@ def prepare(self, content: "Callable[[], AnyFormattedText]") -> PreparedFrame | width=geometry.columns, height=geometry.reserved_rows, default_style=self._default_style, + text_style=self._text_style, ) styles = {cell.style for row in frame.rows for cell in row} return PreparedFrame( diff --git a/examples/stage5_pager_check.py b/examples/stage5_pager_check.py new file mode 100755 index 000000000..12e75c356 --- /dev/null +++ b/examples/stage5_pager_check.py @@ -0,0 +1,145 @@ +#!/usr/bin/env python +"""Manual check for the Stage 5 investigation of the built-in pager. Remove before merging to main. + + uv run python examples/stage5_pager_check.py [auto|reserved|legacy|off] + +The argument is the bottom toolbar mode, ``auto`` by default. Then, at the prompt: + + info what was selected: toolbar rendering, terminal classes, pagers + pager builtin|external which pager ``rows`` uses (the built-in one needs a toolbar) + hist 40 print numbered lines, to have something above the pager + rows 2000 page 2000 lines; add ``color``, ``wide`` or ``long``, and ``chop`` + +After each ``rows`` the application prints how long Rich took to render the text, how long the +built-in pager took to draw its first page, and how long the pager was open. + +What the investigation still needs from Windows, where none of this has been measured. Run it in +Windows Terminal, in conhost.exe and in mintty (Git Bash), once as ``auto`` and once as ``legacy``, +and record for each: + +1. The output of ``info``. +2. ``hist 40`` then ``rows 2000 color``. Which pager came up: the built-in one ends in + ``q: quit`` on the row above the toolbar, the external one shows ``-- More --``. Does the + toolbar clock stay visible and keep ticking? Do Space, ``b``, ``G``, ``g``, ``/row 150`` Enter + and ``n`` work, and are ``row N`` green and ``bold red`` red? After ``q``: the timing line, and + whether ``hist 0`` to ``hist 39`` are intact and whether any paged rows, the pager's key + summary or a second toolbar are left on the screen or in the scrollback. +3. ``rows 2000 long chop``: do the right and left arrows scroll sideways to ``tail0``? +4. ``rows 2000 wide``: do the wide characters wrap without breaking? +5. ``rows 100000``: the timing line. +6. Resize the window while the pager is open, then page on and quit. Ctrl-C while it is open. +7. ``pager external`` and steps 2 to 6 again. For ``more``: are colors shown or printed as escape + sequences, can it go back or search, and does the toolbar return when it exits? +""" + +import os +import platform +import subprocess +import sys +import time + +import prompt_toolkit + +import cmd2 +from cmd2 import command_toolbar + +KINDS = { + "plain": lambda number: f"row {number} the quick brown fox jumps over the lazy dog", + "color": lambda number: f"\x1b[32mrow {number}\x1b[0m plain \x1b[1;31mbold red\x1b[0m plain again", + "wide": lambda number: f"row {number} " + "漢字" * 50 + " end", + "long": lambda number: f"row {number} " + "abcdefghij" * 30 + f" tail{number}", +} + + +class PagerCheck(cmd2.Cmd): + def __init__(self, mode: str) -> None: + super().__init__(allow_cli_args=False, bottom_toolbar_mode=mode, refresh_interval=0.5) + self.prompt = "check> " + self.requested_mode = mode + self.timings: dict[str, float] = {} + + def get_bottom_toolbar(self) -> str: + return f"TOOLBAR {time.strftime('%H:%M:%S')}" + + def do_info(self, _: cmd2.Statement) -> None: + """Show what this terminal selected.""" + reserved = self.reserved_toolbar + rendering = "off" if self.main_session.bottom_toolbar is None else "legacy" + if reserved is not None and reserved.is_active: + rendering = "reserved" + size = self.main_session.output.get_size() + self.poutput(f"platform {platform.platform()}") + self.poutput(f"python {sys.version.split()[0]} prompt-toolkit {prompt_toolkit.__version__}") + self.poutput(f"toolbar requested {self.requested_mode}, rendering {rendering}") + self.poutput(f"output / input {type(self.main_session.output).__name__} / {type(self.main_session.input).__name__}") + self.poutput( + f"terminal {size.columns}x{size.rows} stdin tty {self.stdin.isatty()} stdout tty {self.stdout.isatty()}" + ) + self.poutput(f"environment TERM={os.environ.get('TERM')} MSYSTEM={os.environ.get('MSYSTEM')}") + self.poutput(f"pager {'built-in' if self.use_builtin_pager else 'external'}") + self.poutput(f"external pagers {self.pager!r} / chop {self.pager_chop!r}") + + def do_pager(self, arg: cmd2.Statement) -> None: + """pager builtin|external: choose the pager which ``rows`` uses.""" + self.use_builtin_pager = str(arg).strip() != "external" + self.poutput(f"using the {'built-in' if self.use_builtin_pager else 'external'} pager") + + def do_hist(self, arg: cmd2.Statement) -> None: + """hist COUNT: print numbered lines.""" + for number in range(int(str(arg) or 40)): + self.poutput(f"hist {number}") + + def do_rows(self, arg: cmd2.Statement) -> None: + """rows COUNT [plain|color|wide|long] [chop]: page that many generated lines.""" + words = str(arg).split() + count = int(words[0]) if words else 2000 + kind = next((word for word in words[1:] if word in KINDS), "plain") + text = "\n".join(KINDS[kind](number) for number in range(count)) + self.timings = {"start": time.perf_counter()} + self.ppaged(text, chop="chop" in words) + timings, end = self.timings, time.perf_counter() + handed = timings.get("handed") + if handed is None: + self.poutput(f"not paged ({end - timings['start']:.2f} s)") + return + report = ( + f"rendered by Rich in {handed - timings['start']:.2f} s; {timings['which']} pager open for {end - handed:.2f} s" + ) + if "first frame" in timings: + report += f"; its first page drawn after {timings['first frame'] - handed:.2f} s" + self.poutput(report) + + +def instrument(app: PagerCheck) -> None: + """Note when the text reaches a pager, and when the built-in one has drawn.""" + builtin_page = command_toolbar.CommandToolbar.page + + def page(display: command_toolbar.CommandToolbar, text: str, *, chop: bool) -> None: + app.timings.update(handed=time.perf_counter(), which="built-in") + + def drawn(_: object) -> None: + if display._paging: + app.timings.setdefault("first frame", time.perf_counter()) + + display.app.after_render += drawn + try: + builtin_page(display, text, chop=chop) + finally: + display.app.after_render -= drawn + + command_toolbar.CommandToolbar.page = page + popen = subprocess.Popen + + class Popen(popen): + def __init__(self, *args, **kwargs): + if kwargs.get("stdin") == subprocess.PIPE and "handed" not in app.timings: + app.timings.update(handed=time.perf_counter(), which="external") + super().__init__(*args, **kwargs) + + subprocess.Popen = Popen + + +if __name__ == "__main__": + check = PagerCheck(sys.argv[1] if len(sys.argv) > 1 else "auto") + instrument(check) + sys.exit(check.cmdloop()) diff --git a/tests/test_managed_output.py b/tests/test_managed_output.py index d1091d6ec..5b90265a3 100644 --- a/tests/test_managed_output.py +++ b/tests/test_managed_output.py @@ -129,6 +129,9 @@ def __init__(self) -> None: def write_raw(self, data: str) -> None: self.vt100_output.write_raw(data) + def enable_autowrap(self) -> None: + self.vt100_output.enable_autowrap() + def flush(self) -> None: nonlocal mode original_mode = mode @@ -147,13 +150,47 @@ def flush(self) -> None: else: assert writer.write(data) == len(data) writer.flush() - assert console.getvalue() == data + assert console.getvalue() == "\x1b[?7h" + data assert mode == 0 assert observed assert all(enabled == 4 and transaction is not None for enabled, transaction in observed) assert len(bridge.notes) == 1 assert bridge.notes[0] is not None + def test_autowrap_is_turned_on_before_each_write_to_a_backend_whose_flush_resets_it(self) -> None: + """Windows' backend sets a console mode at each flush in which a row does not wrap. + + Written without autowrap, a line wider than the terminal loses everything past the + last column: each character there is written over the one before it. + """ + stream = RecordingStream() + + class WindowsLikeOutput(DummyOutput): + def __init__(self) -> None: + self.vt100_output = Vt100_Output(stream, lambda: Size(24, 80)) + + def write_raw(self, data: str) -> None: + self.vt100_output.write_raw(data) + + def enable_autowrap(self) -> None: + self.vt100_output.enable_autowrap() + + def flush(self) -> None: + self.vt100_output.flush() + + writer = SerializedTerminalWriter(stream, TerminalLock(), output=WindowsLikeOutput()) + writer.write("first\n") + writer.write("second\n") + assert stream.getvalue() == "\x1b[?7hfirst\n\x1b[?7hsecond\n" + + def test_a_backend_which_keeps_its_modes_is_sent_only_the_output(self) -> None: + """A VT terminal keeps autowrap as it was left, so nothing is added to what it is sent.""" + stream = RecordingStream() + writer = SerializedTerminalWriter(stream, TerminalLock(), output=Vt100_Output(stream, lambda: Size(24, 80))) + writer.write("first\n") + writer.write("second\n") + assert stream.getvalue() == "first\nsecond\n" + class TestInvalidationContract: def test_the_bridge_is_told_inside_the_emitting_transaction(self) -> None: diff --git a/tests/test_output_recorder.py b/tests/test_output_recorder.py index a24d37900..e0df8681f 100644 --- a/tests/test_output_recorder.py +++ b/tests/test_output_recorder.py @@ -141,12 +141,29 @@ def test_the_recorder_holds_no_reference_to_a_backend(self) -> None: recorder = make_recorder() assert not any(isinstance(value, Vt100_Output) for value in vars(recorder).values()) - def test_a_screen_buffer_transition_cannot_be_recorded(self) -> None: - """Buffer transitions are ownership boundaries, taken before a frame is prepared.""" + def test_entering_the_alternate_screen_is_recorded_with_the_frame_drawn_there(self) -> None: + """A full-screen frame begins by entering the alternate screen, and is emitted as one piece. + + Refused, the renderer had already noted itself as switched, so the frame it prepared + next was drawn on the main screen. + """ recorder = make_recorder() - for transition in (recorder.enter_alternate_screen, recorder.quit_alternate_screen): - with pytest.raises(UnrecordableOperationError): - transition() + recorder.enter_alternate_screen() + recorder.write("first page") + assert recorder.operations == (Operation("enter_alternate_screen"), Operation("write", ("first page",))) + + stream = io.StringIO() + backend = Vt100_Output(stream, lambda: Size(rows=24, columns=80), term="xterm") + recorder.batch().replay(backend) + backend.flush() + assert stream.getvalue().startswith("\x1b[?1049h") + assert stream.getvalue().endswith("first page") + + def test_leaving_the_alternate_screen_cannot_be_recorded(self) -> None: + """A renderer leaves the alternate screen when it is reset, never in the middle of a frame.""" + recorder = make_recorder() + with pytest.raises(UnrecordableOperationError): + recorder.quit_alternate_screen() def test_a_viewport_move_cannot_be_recorded(self) -> None: recorder = make_recorder() @@ -157,7 +174,7 @@ def test_a_rejected_operation_is_not_left_in_the_batch(self) -> None: recorder = make_recorder() recorder.write("hello") with pytest.raises(UnrecordableOperationError): - recorder.enter_alternate_screen() + recorder.quit_alternate_screen() assert recorder.operations == (Operation("write", ("hello",)),) diff --git a/tests/test_prompt_toolkit_bridge.py b/tests/test_prompt_toolkit_bridge.py index 03d728474..b78137175 100644 --- a/tests/test_prompt_toolkit_bridge.py +++ b/tests/test_prompt_toolkit_bridge.py @@ -1170,6 +1170,48 @@ def test_a_render_reinstalls_the_region_after_a_resize(self) -> None: assert harness.display.geometry is not None assert harness.display.geometry.physical_rows == 12 + @pytest.mark.parametrize( + ("suppressed", "written", "fresh"), + [ + # A command has the terminal, and its last line ended: the cursor is at the start + # of a row it has written nothing on, which may be the old band's. + (True, ["one\n"], True), + (True, ["one\n", "\x1b[0m"], True), + # The line is still in progress, so the cursor's row is the command's. + (True, ["one\n", "two"], False), + # Nothing is known of where the cursor is: no output yet, or a guest has had it. + (True, [], False), + (True, ["one\n", None], False), + # A prompt has the terminal. Its rows are its own to redraw. + (False, ["one\n"], False), + ], + ) + def test_a_resize_says_whether_output_has_just_moved_on_to_the_cursor_s_row(self, suppressed, written, fresh) -> None: + """A terminal drops the scroll region when it is resized, and output then runs on to the band.""" + harness = self.bound() + with set_app(harness.app): + harness.renderer.render(harness.app, harness.app.layout) + harness.bridge.set_render_suppressed(suppressed) + for data in written: + if data is None: + harness.bridge.forget_unfinished_command_output() + else: + harness.bridge.note_managed_write(data=data) + asked: list[bool] = [] + reconfigure = harness.display.reconfigure + + def record(*, cursor_row_is_fresh: bool = False) -> bool: + asked.append(cursor_row_is_fresh) + return reconfigure(cursor_row_is_fresh=cursor_row_is_fresh) + + harness.display.reconfigure = record # type: ignore[method-assign] + harness.size = Size(rows=30, columns=80) + with set_app(harness.app): + harness.renderer.render(harness.app, harness.app.layout) + assert asked == [fresh] + assert harness.display.geometry is not None + assert harness.display.geometry.physical_rows == 30 + def test_a_suppressed_render_below_the_floor_is_a_no_op(self) -> None: """With no reservation there is nothing to remeasure and nothing of its own to draw.""" harness = self.bound() @@ -1253,6 +1295,96 @@ def test_a_stale_frame_emits_nothing_and_asks_for_another(self) -> None: assert harness.stream_recorder.getvalue() == "" assert redraws + @pytest.mark.parametrize("full_screen", [False, True]) + def test_a_frame_dropped_while_it_was_prepared_is_not_the_next_baseline(self, full_screen) -> None: + """A write which lands while a frame is prepared drops the frame, and what it drew too. + + The renderer has taken the dropped frame as its last screen by then, and its cursor + as where the cursor is. Diffed against that, the frame prepared next finds nothing to + draw, and the terminal goes on showing the frame before. + """ + frame: list[Any] = ["hello"] + write_lands = [False] + + def content() -> Any: + if write_lands[0]: + write_lands[0] = False + harness.bridge.note_managed_write() + return frame[0] + + harness = self.bound(content=content) + harness.app.full_screen = harness.renderer.full_screen = full_screen + + def render() -> str: + # The control keeps its content until the application counts another render. + harness.app.render_counter += 1 + harness.stream_recorder.truncate(0) + harness.stream_recorder.seek(0) + harness.renderer.render(harness.app, harness.app.layout) + return harness.stream_recorder.getvalue() + + with set_app(harness.app): + assert "hello" in render() + committed = (harness.renderer._last_screen, harness.renderer._cursor_pos) + + # No character in common with the frame before, so all of it has to be drawn. + frame[0] = [("", "WORLD\n"), ("[SetCursorPosition]", ""), ("", "SECOND")] + write_lands[0] = True + assert render() == "" + assert harness.renderer._last_screen is committed[0] + assert harness.renderer._cursor_pos == committed[1] + + emitted = render() + assert "WORLD" in emitted + assert "SECOND" in emitted + assert harness.renderer._cursor_pos == Point(x=0, y=1) + harness.bridge.unbind() + + @pytest.mark.parametrize("full_screen", [False, True]) + def test_a_frame_dropped_before_it_was_emitted_leaves_the_cursor_where_it_was(self, full_screen) -> None: + """A write which lands after a frame is prepared, and before it is emitted, drops it too. + + The renderer has taken the frame's cursor as where the cursor is by then. The frame + prepared next would move from there, and be drawn that far from where it belongs. + """ + frame: list[Any] = ["hello"] + harness = self.bound(content=lambda: frame[0]) + harness.app.full_screen = harness.renderer.full_screen = full_screen + + def render() -> str: + # The control keeps its content until the application counts another render. + harness.app.render_counter += 1 + harness.stream_recorder.truncate(0) + harness.stream_recorder.seek(0) + harness.renderer.render(harness.app, harness.app.layout) + return harness.stream_recorder.getvalue() + + with set_app(harness.app): + assert "hello" in render() + committed = (harness.renderer._last_screen, harness.renderer._cursor_pos) + + # This frame leaves the cursor a row below where the one before left it. + frame[0] = [("", "WORLD\n"), ("[SetCursorPosition]", ""), ("", "SECOND")] + harness.app.render_counter += 1 + harness.stream_recorder.truncate(0) + harness.stream_recorder.seek(0) + prepared = harness.bridge.prepare(harness.app) + assert prepared is not None + assert harness.renderer._cursor_pos != committed[1] + harness.bridge.note_managed_write() + assert harness.bridge.commit(prepared) is False + assert harness.stream_recorder.getvalue() == "" + assert harness.renderer._last_screen is committed[0] + assert harness.renderer._cursor_pos == committed[1] + + emitted = render() + # Drawn from the row the cursor is on, not from one below it. + assert "\x1b[A" not in emitted + assert "WORLD" in emitted + assert "SECOND" in emitted + assert harness.renderer._cursor_pos == Point(x=0, y=1) + harness.bridge.unbind() + def test_a_frame_which_fails_after_command_output_asks_for_another(self) -> None: """A redraw requested before a frame began must not swallow the retry that frame needs. @@ -1306,6 +1438,51 @@ def redraw() -> None: assert 1 <= len(redraws) <= 3 harness.bridge.unbind() + def test_a_full_screen_frame_enters_the_alternate_screen_as_it_is_emitted(self) -> None: + """The switch and the frame drawn after it reach the terminal together, and once.""" + harness = self.bound() + harness.app.full_screen = harness.renderer.full_screen = True + with set_app(harness.app): + harness.renderer.render(harness.app, harness.app.layout) + harness.renderer.render(harness.app, harness.app.layout) + emitted = harness.stream_recorder.getvalue() + assert emitted.count("\x1b[?1049h") == 1 + assert emitted.index("\x1b[?1049h") < emitted.index("hello") + assert harness.renderer._in_alternate_screen is True + harness.bridge.unbind() + + @pytest.mark.parametrize("fault", ["retired", "raised"]) + def test_a_full_screen_frame_which_is_not_emitted_has_not_switched_screens(self, fault) -> None: + """The renderer notes the switch while the frame is prepared. A frame dropped must undo that. + + Otherwise the frame prepared next believes the terminal is already on the alternate + screen, and is drawn over the main one. + """ + faults = [fault] + + def content() -> str: + if faults: + if faults.pop() == "raised": + raise RuntimeError("cannot be prepared this time") + harness.bridge.note_managed_write() + return "hello" + + harness = self.bound(content=content) + harness.app.full_screen = harness.renderer.full_screen = True + with set_app(harness.app): + harness.renderer.render(harness.app, harness.app.layout) + assert harness.stream_recorder.getvalue() == "" + assert harness.renderer._in_alternate_screen is False + + if fault == "raised": + harness.resynchronize() + harness.renderer.render(harness.app, harness.app.layout) + emitted = harness.stream_recorder.getvalue() + assert emitted.count("\x1b[?1049h") == 1 + assert emitted.index("\x1b[?1049h") < emitted.index("hello") + assert harness.renderer._in_alternate_screen is True + harness.bridge.unbind() + def test_binding_twice_keeps_the_first_interception(self) -> None: """A second bind would save the wrapper as the original and never unwind.""" harness = self.bound() diff --git a/tests/test_reserved_terminal.py b/tests/test_reserved_terminal.py index 148e6951b..97f02f00d 100644 --- a/tests/test_reserved_terminal.py +++ b/tests/test_reserved_terminal.py @@ -293,11 +293,94 @@ def resize(harness, terminal, rows: int, columns: int) -> None: harness.size = Size(rows=rows, columns=columns) +@pytest.mark.skipif(not hasattr(signal, "SIGWINCH"), reason="this platform has no window-change signal") +class TestResizeSignal: + """A resize during a command is passed to the display from the thread the signal comes to. + + A terminal sets its scroll region back to the whole screen when it is resized. Until the + display has installed it again, command output runs on to the toolbar's row and is written + over it. Left to prompt-toolkit's look at the size twice a second, that is most resizes. + """ + + def test_the_region_is_installed_again_without_waiting_for_the_size_poll(self, terminal_harness) -> None: + harness, terminal = terminal_harness + if threading.current_thread() is not threading.main_thread(): # pragma: no cover + pytest.skip("signals are delivered to the main thread") + # Nothing else which would have the display look at the size: no poll of it, and no + # toolbar refresh to draw a frame. Only the signal can bring the news. + ui = harness.app.main_session.app + ui.terminal_size_polling_interval = None + ui.refresh_interval = 0 + before = signal.getsignal(signal.SIGWINCH) + with harness.app._reserved_toolbar_context(), harness.app._command_toolbar_context(): + display = harness.app.reserved_toolbar.display + assert display.geometry.physical_rows == 24 + # The frames a display draws as it starts would see the new size too. Wait them out. + drawn = -1 + while drawn != ui.render_counter: + drawn = ui.render_counter + time.sleep(0.2) + resize(harness, terminal, 30, 80) + time.sleep(0.2) + assert display.geometry.physical_rows == 24 + signal.raise_signal(signal.SIGWINCH) + assert wait_for(lambda: display.geometry is not None and display.geometry.physical_rows == 30, timeout=2) + assert wait_for(lambda: terminal.screen.display[-1].startswith("STATUS")) + assert terminal.screen.margins == pyte.screens.Margins(0, 28) + assert signal.getsignal(signal.SIGWINCH) is before + + def test_a_handler_which_was_already_there_still_hears_of_it(self, terminal_harness) -> None: + harness, _ = terminal_harness + if threading.current_thread() is not threading.main_thread(): # pragma: no cover + pytest.skip("signals are delivered to the main thread") + heard: list[int] = [] + + def earlier(signum: int, _frame: Any) -> None: + heard.append(signum) + + before = signal.signal(signal.SIGWINCH, earlier) + try: + with harness.app._reserved_toolbar_context(), harness.app._command_toolbar_context(): + assert signal.getsignal(signal.SIGWINCH) is not earlier + signal.raise_signal(signal.SIGWINCH) + assert heard == [signal.SIGWINCH] + assert signal.getsignal(signal.SIGWINCH) is earlier + finally: + signal.signal(signal.SIGWINCH, before) + + def test_a_handler_which_python_cannot_put_back_is_left_alone(self, terminal_harness, monkeypatch) -> None: + """One installed from C is reported as None, which cannot be given to signal() again.""" + harness, _ = terminal_harness + installed: list[Any] = [] + monkeypatch.setattr(signal, "getsignal", lambda _signum: None) + monkeypatch.setattr(signal, "signal", lambda *args: installed.append(args)) + with harness.app._reserved_toolbar_context(), harness.app._command_toolbar_context(): + pass + assert not [args for args in installed if args[0] == signal.SIGWINCH] + + def test_a_display_started_off_the_main_thread_leaves_the_signal_alone(self, terminal_harness) -> None: + """Only the main thread may install a handler, or be sent the signal.""" + harness, _ = terminal_harness + before = signal.getsignal(signal.SIGWINCH) + during: list[Any] = [] + + def command() -> None: + with harness.app._reserved_toolbar_context(), harness.app._command_toolbar_context(): + during.append(signal.getsignal(signal.SIGWINCH)) + + thread = threading.Thread(target=command) + thread.start() + thread.join(timeout=10) + assert during == [before] + assert signal.getsignal(signal.SIGWINCH) is before + + class TestResize: - """A resize during a command reaches the display only through prompt-toolkit's size poll. + """A resize during a command reaches a display off the main thread through the size poll. The command display runs on its own thread, where no window-change signal can be - attached, so the poll on ``output.get_size()`` is the only way a resize arrives there. + attached, so the poll on ``output.get_size()`` is how a resize arrives there unless the + main thread passes the signal on. These tests are of the poll. """ @pytest.mark.parametrize("terminal_harness", [2, 3], indirect=True) @@ -974,6 +1057,69 @@ def prepare(*args, **kwargs): assert reserved.display._deferred_band is None assert terminal.screen.display[-1].startswith("STATUS") + def test_the_pager_is_drawn_on_the_alternate_screen(self, terminal_harness) -> None: + """One switch to the alternate screen before the first page, and one back after the last. + + The pager used to be drawn on the main screen, over the command's earlier output, and + left its last page and its key summary in the scrollback. + """ + harness, terminal = terminal_harness + with harness.app._reserved_toolbar_context(), harness.app._command_toolbar_context(): + assert run_pager(harness, terminal) + emitted = terminal.getvalue() + assert emitted.count("\x1b[?1049h") == 1 + assert emitted.count("\x1b[?1049l") == 1 + assert emitted.index("\x1b[?1049h") < emitted.index("row 000") < emitted.index("\x1b[?1049l") + + def test_the_pager_never_erases_its_screen_from_the_corner(self, terminal_harness) -> None: + """iTerm2 keeps a screen which is erased from its top-left corner, the pager's included. + + The renderer erases from there when the pager closes and when the terminal is resized. + Here the erase reaches the terminal through the reserved adapter, or replayed from a + recorded frame. + """ + harness, terminal = terminal_harness + careful = command_toolbar.ERASE_DOWN_FROM_FIRST_COLUMN + + def resize() -> None: + display = harness.app._command_toolbar + before = terminal.getvalue().count(careful) + display.app.loop.call_soon_threadsafe(display.app._on_resize) + assert wait_for(lambda: terminal.getvalue().count(careful) > before) + + with harness.app._reserved_toolbar_context(), harness.app._command_toolbar_context(): + backend = harness.app.reserved_toolbar.display.terminal.output + assert run_pager(harness, terminal, while_open=resize) + # The terminal's own way of erasing is back once the pager has closed. + assert "erase_down" not in vars(backend) + emitted = terminal.getvalue() + paged = emitted[emitted.index("\x1b[?1049h") : emitted.rindex("\x1b[?1049l")] + assert paged.count("\x1b[J") >= 3 + assert paged.count("\x1b[J") == paged.count(careful) + + def test_the_pager_returns_to_the_alternate_screen_after_lending_the_terminal(self, terminal_harness) -> None: + """What Ctrl-Z does: the renderer leaves the alternate screen, and has to enter it again.""" + harness, terminal = terminal_harness + + def lend_the_terminal() -> None: + display = harness.app._command_toolbar + + def lend(app) -> None: + # From a handler of the application's own, to be in its context. + app.after_render -= lend + run_in_terminal(lambda: None) + + display.app.after_render += lend + display.app.invalidate() + assert wait_for(lambda: terminal.getvalue().count("\x1b[?1049h") == 2) + assert wait_for(lambda: terminal.getvalue().rindex("row 000") > terminal.getvalue().rindex("\x1b[?1049h")) + + with harness.app._reserved_toolbar_context(), harness.app._command_toolbar_context(): + assert run_pager(harness, terminal, while_open=lend_the_terminal) + emitted = terminal.getvalue() + assert emitted.count("\x1b[?1049h") == 2 + assert emitted.count("\x1b[?1049l") == 2 + def test_first_pager_frame_uses_full_geometry(self, terminal_harness) -> None: harness, terminal = terminal_harness with harness.app._reserved_toolbar_context(), harness.app._command_toolbar_context(): diff --git a/tests/test_reserved_toolbar.py b/tests/test_reserved_toolbar.py index a44289042..6f5aad1ab 100644 --- a/tests/test_reserved_toolbar.py +++ b/tests/test_reserved_toolbar.py @@ -382,6 +382,41 @@ def test_the_band_is_painted_when_the_reservation_starts(self) -> None: finally: harness.close() + def test_the_band_is_drawn_as_a_bar_as_the_native_toolbar_is(self) -> None: + """prompt-toolkit draws its toolbar in reverse video, by its default style for an application. + + Text and the padding after it are both part of the bar. + """ + harness = Harness() + try: + harness.toolbar.start() + reverse = "\x1b[0;7m" + assert f"{reverse}STATUS{reverse}{' ' * 74}" in harness.written() + finally: + harness.close() + + def test_the_band_is_styled_as_the_application_styles_its_own_toolbar(self) -> None: + """A theme's rule for the toolbar, or for its text, reaches the band as it does the window.""" + harness = Harness() + try: + harness.toolbar.start() + painter = harness.toolbar.painter + assert painter is not None + assert painter.last_frame is not None + styles = {cell.style for cell in painter.last_frame.rows[0]} + native = harness.app._merged_style + text = native.get_attrs_for_style_str("class:bottom-toolbar class:bottom-toolbar.text") + padding = native.get_attrs_for_style_str("class:bottom-toolbar") + assert {painter._style.get_attrs_for_style_str(style) for style in styles} == {text, padding} + assert text.reverse + assert padding.reverse + assert {tuple(style.split()) for style in styles} == { + ("class:bottom-toolbar", "class:bottom-toolbar.text"), + ("class:bottom-toolbar",), + } + finally: + harness.close() + def test_refreshing_repaints_changed_content(self) -> None: harness = Harness() try: diff --git a/tests/test_terminal_display.py b/tests/test_terminal_display.py index c2ed5eb7c..1b2a10360 100644 --- a/tests/test_terminal_display.py +++ b/tests/test_terminal_display.py @@ -300,6 +300,51 @@ def test_reconfigure_does_nothing_without_a_lease(self) -> None: assert stream.getvalue() == "" +def test_a_resize_erases_the_old_band_when_output_has_moved_on_to_its_row() -> None: + """A terminal drops the scroll region when it is resized, and the next line to end moves on to the band. + + The cursor is then at the start of the old band's row. Kept as the row output goes on from, + the next line would be written over the old toolbar and leave the rest of it in the output. + """ + import pyte + + output, stream, size = make_resizable_output(rows=24, columns=80) + display = TerminalDisplay(output) + display.acquire() + size.rows = 32 + stream.truncate(0), stream.seek(0) + assert display.reconfigure(cursor_row_is_fresh=True) + + # Eight rows came back from the scrollback, and a line was written before the news of it. + screen = pyte.Screen(80, 32) + terminal = pyte.Stream(screen) + for number, text in enumerate([*SCROLLBACK, *OUTPUT, BAND], 1): + terminal.feed(f"\x1b[{number};1H{text}") + terminal.feed("\x1b[32;1H") + terminal.feed(stream.getvalue()) + terminal.feed("next line") + + # Making room took the top row, and the band's row is where output goes on. + shown = [line.rstrip() for line in screen.display] + assert shown == [*SCROLLBACK[1:], *OUTPUT, "next line", ""] + assert screen.margins == pyte.screens.Margins(0, 30) + + +def test_erasing_a_fresh_row_does_not_start_in_the_corner() -> None: + """iTerm2 would save the screen, and the old band with it, to its scrollback.""" + output, stream = make_output() + PhysicalTerminal(output).erase_below_cursor(cursor_row_is_fresh=True) + assert "\x1b[J" in stream.getvalue() + assert stream.getvalue() == "\x1b[K\x1b[C\x1b[J\x1b[D" + + +#: A screen of 24 rows which command output has filled, and the toolbar on its last row. +OUTPUT = [f"line {number:02d}" for number in range(23)] +BAND = "TOOLBAR n=75".ljust(80, ".") +#: Rows which had scrolled off the top, and which some terminals bring back when they grow. +SCROLLBACK = [f"earlier {number}" for number in range(8)] + + class TestResize: def test_reconfigure_installs_the_region_for_the_new_height(self) -> None: output, stream, screen = make_resizable_output(rows=24, columns=80) @@ -309,10 +354,50 @@ def test_reconfigure_installs_the_region_for_the_new_height(self) -> None: screen.rows = 40 stream.truncate(0), stream.seek(0) assert display.reconfigure() - # A resize starts from full-screen margins, erases the old band's row -- growing has - # brought it back inside the screen with its stale toolbar -- makes room for the new - # band, and installs the new region. - assert stream.getvalue() == "\x1b7\x1b[r\x1b8\x1b7\x1b[24;1H\x1b[2K\x1b8\x1bD\x1b[1A\x1b7\x1b[1;39r\x1b8" + # A resize starts from full-screen margins, makes room for the new band, erases what + # is below the cursor's row -- the old band's stale toolbar, wherever the terminal has + # put it -- and installs the new region. + assert stream.getvalue() == "\x1b7\x1b[r\x1b8\x1bD\x1b[1A\x1b7\x1b[B\r\x1b[J\x1b8\x1b7\x1b[1;39r\x1b8" + + @pytest.mark.parametrize( + ("moved", "rows", "columns", "before", "cursor_row"), + [ + # Rows were added at the bottom: output and the old band are where they were. + pytest.param("nothing", 32, 80, [*OUTPUT, BAND], 23, id="rows added at the bottom"), + # Rows came back from the scrollback at the top: everything moved down with them, + # and the row the old band was on now holds a line of output. + pytest.param("down", 32, 80, [*SCROLLBACK, *OUTPUT, BAND], 31, id="rows brought back from the scrollback"), + # The window was made narrower and its rows rewrapped: the old band, which filled + # its row, is two rows now, and a row of output has gone to the scrollback for it. + pytest.param("up", 24, 60, [*OUTPUT[1:], BAND[:60], BAND[60:]], 22, id="rows rewrapped"), + # Rows were taken from the top: the old band is still the last row. + pytest.param("up", 16, 80, [*OUTPUT[8:], BAND], 15, id="rows taken from the top"), + ], + ) + def test_a_resize_erases_the_old_band_wherever_the_terminal_put_it(self, moved, rows, columns, before, cursor_row) -> None: + """And erases nothing else: where the old band's rows are afterwards is up to the terminal.""" + import pyte + + output, stream, size = make_resizable_output(rows=24, columns=80) + display = TerminalDisplay(output) + display.acquire() + size.rows, size.columns = rows, columns + stream.truncate(0), stream.seek(0) + assert display.reconfigure() + + # The screen as the terminal left it, with the cursor after the last line of output. + screen = pyte.Screen(columns, rows) + terminal = pyte.Stream(screen) + for number, text in enumerate(before, 1): + terminal.feed(f"\x1b[{number};1H{text}") + terminal.feed(f"\x1b[{cursor_row};8H") + terminal.feed(stream.getvalue()) + + output_rows = [text for text in before if not text.startswith("TOOLBAR") and text.strip(".")] + shown = [line.rstrip() for line in screen.display] + assert shown == output_rows + [""] * (rows - len(output_rows)), moved + assert (screen.cursor.y + 1, screen.cursor.x + 1) == (cursor_row, 8) + assert screen.margins == pyte.screens.Margins(0, rows - 2) def test_a_width_change_alone_is_still_a_new_generation(self) -> None: """Toolbar height is measured against the width, so a rewrap can change the reservation.""" diff --git a/tests/test_toolbar_painter.py b/tests/test_toolbar_painter.py index c1d9095f7..0a109fee6 100644 --- a/tests/test_toolbar_painter.py +++ b/tests/test_toolbar_painter.py @@ -143,6 +143,19 @@ def test_each_fragment_styles_its_own_cells(self) -> None: frame = ToolbarFrame.build([("bold", "ab"), ("italic", "c")], width=4, height=1, default_style="base") assert styles_of(frame) == ["bold", "bold", "italic", "base"] + def test_the_text_style_is_under_the_style_of_every_fragment(self) -> None: + """As a window's style is: text in a bar keeps the bar, whatever style of its own it has.""" + frame = ToolbarFrame.build( + [("bold", "ab"), ("", "c")], width=5, height=1, default_style="bar", text_style="bar bar.text" + ) + assert [style.split() for style in styles_of(frame)] == [ + ["bar", "bar.text", "bold"], + ["bar", "bar.text", "bold"], + ["bar", "bar.text"], + ["bar"], + ["bar"], + ] + def test_a_zero_width_escape_fragment_is_dropped(self) -> None: """Passing arbitrary cursor control through the painter would move the real cursor.""" content = [("", "a"), ("[ZeroWidthEscape]", "\x1b[6n"), ("", "b")]