Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
da8491b
Add a manual check for the Stage 5 pager investigation
tleonhardt Nov 15, 2026
1226346
Merge branch 'reserved_row_toolbar' into stage5-pager-investigation
tleonhardt Nov 15, 2026
9993b72
Enter the alternate screen for the built-in pager in reserved rendering
tleonhardt Nov 15, 2026
31d4623
Merge branch 'reserved_row_toolbar' into stage5-pager-investigation
tleonhardt Nov 15, 2026
dc84f6c
Wrap command output wider than the terminal in reserved rendering on …
tleonhardt Nov 15, 2026
3f34913
Put back the renderer's baseline when a frame is dropped while it is …
tleonhardt Nov 15, 2026
fb041f6
Put back the renderer's cursor when a prepared frame is dropped befor…
tleonhardt Nov 15, 2026
8e37a0b
Draw the reserved toolbar as a bar, as prompt-toolkit draws its own
tleonhardt Nov 15, 2026
4208161
Merge branch 'reserved_row_toolbar' into stage5-pager-investigation
tleonhardt Nov 15, 2026
d181692
Test that the pager on a reservation never erases its screen from the…
tleonhardt Nov 15, 2026
79c4460
Clear the old toolbar after a resize from wherever the terminal has m…
tleonhardt Nov 15, 2026
6eeecab
Tell the command display of a resize as soon as the signal arrives
tleonhardt Nov 15, 2026
0af637b
Merge branch 'reserved_row_toolbar' into stage5-pager-investigation
tleonhardt Nov 17, 2026
82ca56a
Merge branch 'reserved_row_toolbar' into stage5-pager-investigation
tleonhardt Nov 17, 2026
c632297
Merge branch 'reserved_row_toolbar' into stage5-pager-investigation
tleonhardt Nov 17, 2026
d5e7215
Merge branch 'reserved_row_toolbar' into stage5-pager-investigation
tleonhardt Nov 17, 2026
49c18d0
Merge branch 'reserved_row_toolbar' into stage5-pager-investigation
tleonhardt Nov 17, 2026
0228e7a
Merge branch 'reserved_row_toolbar' into stage5-pager-investigation
tleonhardt Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 37 additions & 0 deletions cmd2/command_toolbar.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
8 changes: 8 additions & 0 deletions cmd2/managed_output.py
Original file line number Diff line number Diff line change
Expand Up @@ -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":
Expand All @@ -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
Expand Down
20 changes: 12 additions & 8 deletions cmd2/output_recorder.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""


Expand Down Expand Up @@ -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.
Expand Down
Loading
Loading