From da8491b08ac4357a237bb1f09b1d9a1019ad6af5 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sat, 14 Nov 2026 21:50:13 -0500 Subject: [PATCH 1/9] Add a manual check for the Stage 5 pager investigation Stage 5 asks whether the built-in pager is still worth keeping now that reserved rendering exists. The comparison with an external pager has been measured on macOS and Linux in a pseudo-terminal, which cannot be done on Windows. examples/stage5_pager_check.py is the Windows half: an application which pages generated text through either pager, says which toolbar rendering and terminal classes were selected, and reports 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. Its docstring lists what to record in Windows Terminal, conhost and mintty. Like examples/stage4_manual.py, it is for the integration branch only and is to be removed before the work reaches main. --- examples/stage5_pager_check.py | 145 +++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100755 examples/stage5_pager_check.py 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()) From 9993b7244170a14a1c3aebacd60d542ed1ec6e3c Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 13:00:25 -0500 Subject: [PATCH 2/9] Enter the alternate screen for the built-in pager in reserved rendering In reserved rendering the pager was drawn on the main screen. One pager session sent no switch to the alternate screen and one switch back; legacy rendering sends one of each. The pager painted over the command's earlier output and left a page of paged rows, its key summary and a second toolbar row in the scrollback. A renderer enters the alternate screen as the first thing in a full-screen frame, and marks itself as there before it asks the output to switch. Under reserved rendering a frame is recorded first and emitted afterwards, and the recorder refused to record the switch. The frame failed to prepare, the renderer went on believing it had switched, and the frame prepared next was drawn without the switch. Record the switch with the frame which is drawn after it, so both reach the terminal in one piece or not at all. A frame which is not emitted has not switched screens, so the renderer is put back to believing what it did before preparing it, and the screen it laid out is not kept as a baseline. This also covers the pager coming back from Ctrl-Z, where the renderer has left the alternate screen to lend the terminal and enters it again. Leaving the alternate screen stays unrecordable: a renderer does that when it is reset, never inside a frame. --- CHANGELOG.md | 3 + cmd2/output_recorder.py | 20 +++--- cmd2/prompt_toolkit_bridge.py | 107 +++++++++++++++++++--------- tests/test_output_recorder.py | 29 ++++++-- tests/test_prompt_toolkit_bridge.py | 45 ++++++++++++ tests/test_reserved_terminal.py | 37 ++++++++++ 6 files changed, 194 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fc7afe30f..f75ccb339 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,9 @@ 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. - 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/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..ec1117d61 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,11 @@ 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 + @dataclass(frozen=True) class TerminalModePolicy: @@ -443,10 +447,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. @@ -796,11 +799,15 @@ 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 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 +826,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: @@ -827,9 +835,10 @@ def prepare(self, app: "Application[Any]", layout: Any = None, *, is_done: bool # baseline correct -- but the frame was recorded against the cursor and content # that write moved, so it must not be published as current. self._in_flight = None + 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) self._in_flight = prepared return prepared @@ -841,31 +850,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 +863,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 +880,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/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..6785de4c3 100644 --- a/tests/test_prompt_toolkit_bridge.py +++ b/tests/test_prompt_toolkit_bridge.py @@ -1306,6 +1306,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..864cdf1e5 100644 --- a/tests/test_reserved_terminal.py +++ b/tests/test_reserved_terminal.py @@ -974,6 +974,43 @@ 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_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(): From dc84f6c68b977c1fd7ed1716c45c3704de4d8e87 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 15:23:03 -0500 Subject: [PATCH 3/9] Wrap command output wider than the terminal in reserved rendering on Windows prompt-toolkit's Windows10_Output sets the console mode around every flush, and the mode it sets does not wrap at the end of a row. Its own stdout proxy turns autowrap on before each write for that reason. SerializedTerminalWriter takes that proxy's place in reserved rendering and did not, so everything past the last column of a line of command output was written over the last column and lost. Legacy rendering wrapped the same line. Autowrap is now turned on before each write to that backend. A VT backend is sent exactly what it was before. Found in Windows Terminal while running examples/stage5_pager_check.py: with a window narrower than the timing line, the line ended "its first pags". --- CHANGELOG.md | 2 ++ cmd2/managed_output.py | 8 ++++++++ tests/test_managed_output.py | 39 +++++++++++++++++++++++++++++++++++- 3 files changed, 48 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4bc7652b7..26ab8f7a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ - 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. - 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/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/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: From 3f349136c4c4ff1549d96bce8d138a0e4b434613 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 15:23:12 -0500 Subject: [PATCH 4/9] Put back the renderer's baseline when a frame is dropped while it is prepared A managed write which lands while a frame is being prepared retires the frame. The write puts the renderer's last screen back to the committed one, but the renderer is still preparing and takes the frame it is preparing in its place when it finishes. The frame prepared next was then diffed against one the terminal never received, drew nothing where the two agreed, and left the terminal showing the frame before. prepare() now notes the renderer's last screen and cursor before the frame is prepared, and puts both back when the frame is dropped for this reason. Not changed: output written by another thread while the built-in pager is open still goes straight onto the pager's screen in reserved rendering. --- CHANGELOG.md | 3 ++ cmd2/prompt_toolkit_bridge.py | 10 +++++++ tests/test_prompt_toolkit_bridge.py | 45 +++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 26ab8f7a6..8078bd9b2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,9 @@ 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. - 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/prompt_toolkit_bridge.py b/cmd2/prompt_toolkit_bridge.py index ec1117d61..fb999ec3e 100644 --- a/cmd2/prompt_toolkit_bridge.py +++ b/cmd2/prompt_toolkit_bridge.py @@ -802,6 +802,9 @@ def prepare(self, app: "Application[Any]", layout: Any = None, *, is_done: bool # 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 @@ -834,7 +837,14 @@ 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 diff --git a/tests/test_prompt_toolkit_bridge.py b/tests/test_prompt_toolkit_bridge.py index 6785de4c3..d658abe3d 100644 --- a/tests/test_prompt_toolkit_bridge.py +++ b/tests/test_prompt_toolkit_bridge.py @@ -1253,6 +1253,51 @@ 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() + 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. From fb041f6bd284bc7e228cfada47f88b0e90bc1d0b Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 15:56:34 -0500 Subject: [PATCH 5/9] Put back the renderer's cursor when a prepared frame is dropped before it is emitted A managed write which lands after a frame is prepared, and before it is emitted, drops the frame. The write puts the renderer's last screen back to the committed one, but the renderer's cursor stayed where the dropped frame would have left it. The frame prepared next moved from there, and was drawn that many rows from where it belonged: one row too high where the dropped frame had left the cursor a row lower. A prepared frame now carries where the renderer's cursor was before it was prepared, and the write which drops the frame puts it back. This is the other half of 3f349136, which did the same for a write landing while the frame is still being prepared. --- CHANGELOG.md | 3 ++ cmd2/prompt_toolkit_bridge.py | 18 ++++++++++-- tests/test_prompt_toolkit_bridge.py | 45 +++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8078bd9b2..6fd6a7d06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,9 @@ - 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. - 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/prompt_toolkit_bridge.py b/cmd2/prompt_toolkit_bridge.py index fb999ec3e..d8d5c7d35 100644 --- a/cmd2/prompt_toolkit_bridge.py +++ b/cmd2/prompt_toolkit_bridge.py @@ -101,6 +101,11 @@ class PreparedRender: #: 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: @@ -292,8 +297,12 @@ def note_managed_write(self, prompt_anchor: int | None = None, *, data: str | No # 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 @@ -848,7 +857,12 @@ def prepare(self, app: "Application[Any]", layout: Any = None, *, is_done: bool self._forget_screen_switch(in_alternate_screen) return None - prepared = PreparedRender(batch=recorder.batch(), generations=generations, in_alternate_screen=in_alternate_screen) + prepared = PreparedRender( + batch=recorder.batch(), + generations=generations, + in_alternate_screen=in_alternate_screen, + cursor_before=baseline[1], + ) self._in_flight = prepared return prepared diff --git a/tests/test_prompt_toolkit_bridge.py b/tests/test_prompt_toolkit_bridge.py index d658abe3d..5fb04cc9a 100644 --- a/tests/test_prompt_toolkit_bridge.py +++ b/tests/test_prompt_toolkit_bridge.py @@ -1298,6 +1298,51 @@ def render() -> str: 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. From 8e37a0b174d2629f952259909b53bf5fc22fb6a0 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 15:56:43 -0500 Subject: [PATCH 6/9] Draw the reserved toolbar as a bar, as prompt-toolkit draws its own The reserved toolbar was plain text. In legacy rendering it is a reverse-video bar across the whole row. Two things differed. The painter resolved styles against cmd2's theme alone, which has no rule for bottom-toolbar; an application lays its style over prompt-toolkit's default one, and "reverse" comes from there. And the toolbar's text had no class at all: prompt-toolkit's window gives every cell class:bottom-toolbar and its text class:bottom-toolbar.text besides, so a rule for either reached only the padding after the text. The painter is now given the default style with the theme over it, and a style to put under every fragment's own. A theme's rules still win. Found on Windows while running examples/stage5_pager_check.py, and not specific to it. In a pseudo-terminal on macOS the bottom row went from 0 to 80 of 80 cells in reverse video, at the prompt and during a command, as it is in legacy rendering. --- CHANGELOG.md | 3 +++ cmd2/reserved_toolbar.py | 8 ++++++-- cmd2/toolbar_painter.py | 9 ++++++++- tests/test_reserved_toolbar.py | 35 ++++++++++++++++++++++++++++++++++ tests/test_toolbar_painter.py | 13 +++++++++++++ 5 files changed, 65 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6fd6a7d06..35fdbdc45 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,9 @@ - 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. - 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/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/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/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_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")] From d181692cd71fabe49dfb6aa144f2fafe794aa64c Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 16:56:31 -0500 Subject: [PATCH 7/9] Test that the pager on a reservation never erases its screen from the corner There the erase reaches the terminal through the reserved adapter, or replayed from a recorded frame, and the adapter is what the application holds. Without looking through it to the backend, no erase was changed. --- tests/test_reserved_terminal.py | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/tests/test_reserved_terminal.py b/tests/test_reserved_terminal.py index 864cdf1e5..1d5860418 100644 --- a/tests/test_reserved_terminal.py +++ b/tests/test_reserved_terminal.py @@ -988,6 +988,32 @@ def test_the_pager_is_drawn_on_the_alternate_screen(self, terminal_harness) -> N 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 From 79c44604c12ea123a8456914576b32b482330887 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 17:51:27 -0500 Subject: [PATCH 8/9] Clear the old toolbar after a resize from wherever the terminal has moved it After a resize the old band's text is still on the screen, and where depends on the terminal. reconfigure() cleared the rows it had been painted on, and only when the terminal had grown, which is right for a terminal that adds rows at the bottom. iTerm2 brings rows back from its scrollback instead, so the old band moves down with everything else and the rows it was painted on hold output: a line of output was erased each time the window grew. Made narrower, iTerm2 rewraps the band's row into two, and one was left. The rows of the old band are below the cursor's row wherever the terminal has put them, and nothing else is: output goes on from the cursor, and a prompt redraws itself after a resize. reconfigure() now makes room for the new band and then clears everything below the cursor's row, after any resize. One case is not below it. A terminal sets its scroll region back to the whole screen when it is resized, so the next line of output to end moves the cursor on to the old band's row instead of scrolling. The line after it was then written over the old toolbar and the rest of the toolbar stayed in the output. The bridge now notes when 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, and that row is then cleared as well. It is erased from its second column, with the first cleared separately, because iTerm2 saves a screen erased from its top-left corner to the scrollback. In iTerm2 3.7.7, resizing while a command printed 200 lines a second left a line printed over the toolbar at every resize before this and the next commit (8 of 8), and at 2 of 16 after them. Legacy rendering: 0 of 8. --- cmd2/prompt_toolkit_bridge.py | 10 +++- cmd2/terminal_display.py | 52 ++++++++++------ tests/test_prompt_toolkit_bridge.py | 42 +++++++++++++ tests/test_terminal_display.py | 93 +++++++++++++++++++++++++++-- 4 files changed, 174 insertions(+), 23 deletions(-) diff --git a/cmd2/prompt_toolkit_bridge.py b/cmd2/prompt_toolkit_bridge.py index d8d5c7d35..8ad423c4f 100644 --- a/cmd2/prompt_toolkit_bridge.py +++ b/cmd2/prompt_toolkit_bridge.py @@ -177,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 --------------------------------------------------------------------- @@ -291,6 +295,7 @@ 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 @@ -320,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. @@ -656,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 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/tests/test_prompt_toolkit_bridge.py b/tests/test_prompt_toolkit_bridge.py index 5fb04cc9a..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() 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.""" From 6eeecab680eaba24609aaa8e3a052a5e38989dc3 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 17:51:45 -0500 Subject: [PATCH 9/9] Tell the command display of a resize as soon as the signal arrives A terminal sets its scroll region back to the whole screen when it is resized. Until the display has installed the region again, command output runs on to the toolbar's row. The display runs off the main thread, where prompt-toolkit cannot attach the window-change signal and looks at the terminal's size twice a second instead; the bridge also looks whenever a frame is drawn, which is as often as the toolbar refreshes. A command printing four lines a second had its output damaged at most resizes. The signal comes to the main thread, where the command is. While a display holding a reservation runs, a handler there asks the application for a frame, which is where the bridge looks at the size. It calls whatever handler was installed before it, puts that one back when the display stops, and is not installed off the main thread or where there is no such signal. Reinstalling the region inside the handler instead, in the thread doing the writing, was tried and measured no better: what is left is output the terminal had already taken when it was resized. In iTerm2 3.7.7, with a command printing four lines a second, resizes in four directions damaged the output in 5 runs of 8 before this and the previous commit and in 0 of 4 after them. --- CHANGELOG.md | 7 +++ cmd2/command_toolbar.py | 37 ++++++++++++++ tests/test_reserved_terminal.py | 87 ++++++++++++++++++++++++++++++++- 3 files changed, 129 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 35fdbdc45..a43c6c788 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,13 @@ - 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/tests/test_reserved_terminal.py b/tests/test_reserved_terminal.py index 1d5860418..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)