Skip to content

Commit 54c3366

Browse files
authored
Merge pull request #1761 from python-cmd2/stage4-handoffs-integration
Stage 4: integrate reserved toolbar handoffs, job control, and resize recovery
2 parents 56d57f5 + 712f353 commit 54c3366

24 files changed

Lines changed: 1234 additions & 58 deletions

‎CHANGELOG.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
- Bug Fixes
44
- Fixed file path completion for names containing square brackets, including bracketed working
55
directories and home directories.
6+
- The built-in pager (used by `Cmd.ppaged()`) now appears at once in reserved toolbar mode. Its
7+
first page had waited for the next toolbar refresh, and without a `refresh_interval` did not
8+
appear until a key was pressed.
9+
- A line of command output left unfinished before `Cmd.ppaged()` opens the built-in pager is no
10+
longer deleted in reserved toolbar mode.
611
- Background output printed above an active reserved prompt through `run_in_terminal()` or
712
`patch_stdout()` is preserved when the prompt redraws.
813
- Reserved rendering preserves unfinished command output when the main prompt returns by
@@ -56,8 +61,12 @@
5661
is enabled.
5762
- `Cmd.read_input()` and `Cmd.read_secret()` now keep the bottom toolbar visible while they wait
5863
for input, refreshing at the same `refresh_interval` as the main prompt, instead of the
59-
toolbar disappearing for the duration of the nested prompt. `Cmd.select()` is unchanged, since
60-
prompt-toolkit's `choice()` offers no way to configure a refresh interval
64+
toolbar disappearing for the duration of the nested prompt. With reserved rendering they keep
65+
the reserved rows, and so does `Cmd.select()`. With legacy rendering `Cmd.select()` is
66+
unchanged, since prompt-toolkit's `choice()` offers no way to configure a refresh interval
67+
- With reserved rendering, Ctrl-Z gives the reserved rows back to the shell before the process
68+
stops and takes them again when it resumes, and the built-in pager keeps the toolbar visible
69+
while it prepares a large first page.
6170
- Added an embedded pager which `Cmd.ppaged()` uses while the bottom toolbar is running, so the
6271
toolbar stays visible and refreshing instead of the terminal being handed to an external
6372
pager. It supports vertical and horizontal scrolling, incremental search, and chopped lines on

‎cmd2/cmd2.py‎

Lines changed: 64 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@
8787
from prompt_toolkit.output import DummyOutput, Output, create_output
8888
from prompt_toolkit.patch_stdout import patch_stdout
8989
from prompt_toolkit.shortcuts import CompleteStyle, PromptSession, choice
90+
from prompt_toolkit.shortcuts.choice_input import ChoiceInput
9091
from prompt_toolkit.styles import DynamicStyle
9192
from rich.console import (
9293
Group,
@@ -2201,13 +2202,41 @@ def _require_terminal_ownership(self) -> None:
22012202
return
22022203
raise RuntimeError("the bottom toolbar's display has not released the terminal")
22032204

2205+
def _await_terminal_ownership(self) -> bool:
2206+
"""Wait for a display that would not stop to release the terminal before the main prompt.
2207+
2208+
Prompting while its thread is still inside the application would put two readers on one
2209+
terminal, so the command loop waits rather than failing. The thread usually finishes once
2210+
its toolbar callback returns. If it never does, Ctrl-C gives up on it and ends the loop.
2211+
2212+
:return: whether the terminal is ours to prompt on
2213+
"""
2214+
display = self._display_holding_terminal
2215+
if display is None:
2216+
return True
2217+
try:
2218+
# The display left the terminal in raw mode, where Ctrl-C is only a key, and the binding
2219+
# that would signal it runs on the event loop the stuck callback is blocking. Cook the
2220+
# terminal so its driver sends SIGINT again. This is not undone: a display that finishes
2221+
# restores the modes it found, and one given up on should leave the terminal cooked.
2222+
# From here on Ctrl-C can arrive at any point, including while the notice is printing.
2223+
self.main_session.app.input.cooked_mode().__enter__()
2224+
self.perror("Waiting for the bottom toolbar to release the terminal. Press Ctrl-C to quit.")
2225+
while display.thread_is_alive:
2226+
time.sleep(0.05)
2227+
except KeyboardInterrupt:
2228+
return False
2229+
self._require_terminal_ownership()
2230+
return True
2231+
22042232
@contextlib.contextmanager
22052233
def suspend_bottom_toolbar(self) -> Generator[None]:
22062234
"""Temporarily hide the command toolbar and give exclusive access to the terminal.
22072235
22082236
Use this context manager around application-specific calls to ``input()``, other
22092237
terminal UIs, or subprocesses that inherit the terminal. cmd2 automatically suspends
2210-
its toolbar for its own input prompts, external pagers, and shell commands.
2238+
its toolbar for external pagers and shell commands. Managed input prompts borrow
2239+
the reservation without releasing the rows.
22112240
22122241
In reserved mode this also gives the reserved rows back, because a program that
22132242
inherits the terminal knows nothing about a scroll region and would find its output
@@ -2308,6 +2337,11 @@ def _command_toolbar_context(self) -> Generator[None]:
23082337
with self.sigint_protection:
23092338
try:
23102339
toolbar.stop()
2340+
except command_toolbar._DisplayStillRunningError as exc:
2341+
# The display has already disabled itself and kept hold of the terminal,
2342+
# which the next prompt waits for. Like a display that cannot start, it
2343+
# must not escape cmdloop() over a toolbar callback that will not return.
2344+
self.perror(f"Disabling the bottom toolbar during commands: {exc}")
23112345
finally:
23122346
# Always forget a toolbar that has been torn down. Keeping a failed
23132347
# one would disable the toolbar for the rest of the session.
@@ -3896,21 +3930,23 @@ def _read_raw_input(
38963930
The command display is stopped either way, but only some prompts give the terminal
38973931
away with it. The main prompt is the one the reservation exists for: it renders
38983932
through the reserved output, and the toolbar has to still be there while the user is
3899-
typing -- that is what "stable across ordinary commands" means. Any other session is
3900-
an application prompt cmd2 has not bound to the reservation, so it gets the terminal
3901-
to itself, rows included.
3933+
typing. Managed nested prompts on the same terminal borrow that reservation with
3934+
their own bridge after the command input reader stops. Other terminals and prompts
3935+
inside an external handoff retain the exclusive-terminal path.
39023936
39033937
:param prompt: the prompt text or a callable that returns the prompt.
39043938
:param session: the PromptSession instance to use for reading.
39053939
:param prompt_kwargs: additional arguments passed directly to session.prompt().
39063940
:return: the stripped input string.
39073941
:raises EOFError: if the input stream is closed or the user signals EOF (e.g., Ctrl+D)
39083942
"""
3909-
owns_the_reservation = session is self.main_session
3943+
reserved = self._reserved_toolbar
3944+
owns_the_reservation = session is self.main_session or (reserved is not None and reserved.can_manage(session))
39103945
with self._quiesce_bottom_toolbar() if owns_the_reservation else self.suspend_bottom_toolbar():
3911-
reserved = self._reserved_toolbar
39123946
if owns_the_reservation and reserved is not None and reserved.bridge is not None:
39133947
reserved.bridge.finish_command_output()
3948+
with reserved.prompt_session(session):
3949+
return self._read_raw_input_now(prompt, session, **prompt_kwargs)
39143950
return self._read_raw_input_now(prompt, session, **prompt_kwargs)
39153951

39163952
def _read_raw_input_now(
@@ -4043,7 +4079,7 @@ def read_input(
40434079

40444080
temp_session: PromptSession[str] = PromptSession(
40454081
auto_suggest=self.main_session.auto_suggest,
4046-
bottom_toolbar=self.get_bottom_toolbar if self.main_session.bottom_toolbar is not None else None,
4082+
bottom_toolbar=self.main_session.bottom_toolbar,
40474083
color_depth=self.main_session.color_depth,
40484084
complete_style=self.main_session.complete_style,
40494085
complete_in_thread=self.main_session.complete_in_thread,
@@ -4072,7 +4108,7 @@ def read_secret(
40724108
:raises Exception: any other exceptions raised by prompt()
40734109
"""
40744110
temp_session: PromptSession[str] = PromptSession(
4075-
bottom_toolbar=self.get_bottom_toolbar if self.main_session.bottom_toolbar is not None else None,
4111+
bottom_toolbar=self.main_session.bottom_toolbar,
40764112
color_depth=self.main_session.color_depth,
40774113
enable_suspend=self.main_session.enable_suspend,
40784114
input=self.main_session.input,
@@ -4207,6 +4243,9 @@ def _cmdloop(self) -> None:
42074243
self._startup_commands.clear()
42084244

42094245
while not stop:
4246+
if not self._await_terminal_ownership():
4247+
break
4248+
42104249
# Get commands from user
42114250
try:
42124251
line = self._read_command_line(self.prompt)
@@ -5048,7 +5087,7 @@ def do_quit(self, _: argparse.Namespace) -> bool | None:
50485087
self.last_result = True
50495088
return True
50505089

5051-
@command_toolbar.suspend_toolbar
5090+
@command_toolbar.quiesce_toolbar
50525091
def select(self, opts: str | Iterable[str] | Iterable[tuple[Any, str | None]], prompt: str = "Your choice? ") -> Any:
50535092
"""Present a menu to the user.
50545093
@@ -5085,7 +5124,22 @@ def select(self, opts: str | Iterable[str] | Iterable[tuple[Any, str | None]], p
50855124
with create_app_session(input=self.main_session.input, output=self.main_session.output) as app_session:
50865125
self._select_app_session = app_session
50875126
try:
5088-
result = choice(message=prompt, options=fulloptions)
5127+
reserved = self._reserved_toolbar
5128+
if reserved is not None and reserved.can_manage(self.main_session):
5129+
if reserved.bridge is not None:
5130+
reserved.bridge.finish_command_output()
5131+
# ChoiceInput.prompt() constructs and runs in one step. Binding
5132+
# its application first gives the initial frame reserved geometry.
5133+
selection = ChoiceInput(
5134+
message=prompt,
5135+
options=fulloptions,
5136+
style=self.main_session.style,
5137+
enable_suspend=self.main_session.enable_suspend,
5138+
)._create_application()
5139+
with reserved.prompt_application(selection):
5140+
result = selection.run()
5141+
else:
5142+
result = choice(message=prompt, options=fulloptions)
50895143
finally:
50905144
self._select_app_session = None
50915145
self._flush_pending_window_title_quietly()

‎cmd2/command_toolbar.py‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -357,7 +357,9 @@ def __init__(self, cmd: "Cmd") -> None:
357357
session = cmd.main_session
358358
self.app = session.app
359359
# Ctrl-Z during a command is handled on the display's thread, where upstream's
360-
# version would not hold the thread until the job has stopped.
360+
# version would not hold the thread until the job has stopped. The reserved toolbar
361+
# layers its row release over whatever is installed, so one it put there first is
362+
# left in place; it releases the rows and then stops the process the same way.
361363
if "suspend_to_background" not in vars(self.app):
362364
cast("Any", self.app).suspend_to_background = self._suspend_to_background
363365
# PromptSession has no public hook for replacing just its input area.
@@ -924,11 +926,20 @@ def page(self, text: str, *, chop: bool) -> None:
924926
# Measuring the toolbar can invoke its callback; keep that work on the
925927
# UI thread along with rendering and layout changes.
926928
toolbar_height = self._call_in_ui(lambda: self.toolbar.preferred_height(size.columns, size.rows).preferred)
927-
if output_fits(text, size.columns, max(0, size.rows - toolbar_height), chop=chop):
929+
reserved = self.cmd.reserved_toolbar
930+
available_rows = size.rows if reserved is not None and reserved.is_active else max(0, size.rows - toolbar_height)
931+
if output_fits(text, size.columns, available_rows, chop=chop):
928932
self.cmd.stdout.write(text)
929933
self.cmd.stdout.flush()
930934
return
931935

936+
bridge = self._reserved_bridge()
937+
if bridge is not None:
938+
# The pager's first erase deletes whole lines from the cursor's row, before it
939+
# switches to its own screen. Move past a line of command output still in
940+
# progress there, as before a nested prompt, or that line is deleted with them.
941+
bridge.finish_command_output()
942+
932943
pager = Pager(text, chop=chop)
933944
pager.bindings.add(
934945
"c-z",
@@ -939,6 +950,7 @@ def page(self, text: str, *, chop: bool) -> None:
939950
entered = False
940951
restored = False
941952
close_error: BaseException | None = None
953+
handoff = contextlib.ExitStack()
942954

943955
def restore() -> None:
944956
"""Give the application back to the display, whichever thread is doing it.
@@ -966,6 +978,10 @@ def enter() -> None:
966978
# duration -- otherwise the pager swaps in its layout and nothing is ever painted.
967979
self._set_render_suppressed(False)
968980
self.app.renderer.erase()
981+
if reserved is not None:
982+
# The very first pager layout must see the physical size. Releasing from
983+
# enter_alternate_screen during replay is too late: that frame was measured.
984+
handoff.enter_context(reserved.suspended(defer_band_clear=True))
969985
self.app.layout = layout
970986
self.app.key_bindings = pager.bindings
971987
self.app.editing_mode = EditingMode.EMACS
@@ -979,8 +995,20 @@ def leave() -> None:
979995
entered = False
980996
try:
981997
self.app.renderer.erase()
998+
except BaseException:
999+
# An erase can fail before quitting the alternate screen. Complete upstream's
1000+
# mode/buffer cleanup before returning the main-screen reservation; never
1001+
# retry the erase itself, which may already have changed visible output.
1002+
with contextlib.suppress(Exception):
1003+
transaction = (
1004+
reserved.lock.transaction("pager cleanup") if reserved is not None else contextlib.nullcontext()
1005+
)
1006+
with transaction:
1007+
self.app.renderer.reset()
1008+
raise
9821009
finally:
9831010
restore()
1011+
handoff.__exit__(*sys.exc_info())
9841012
self.app.renderer.request_absolute_cursor_position()
9851013
self.app.invalidate()
9861014

@@ -1016,6 +1044,7 @@ def close() -> None:
10161044
# the full-screen flag and editing mode would carry into the next prompt.
10171045
if not restored:
10181046
restore()
1047+
handoff.__exit__(*sys.exc_info())
10191048
# A reservation abandoned while the pager was open deferred its legacy fallback until
10201049
# the pager closed; now that it has, on the main screen, finish it.
10211050
if self._legacy_fallback_pending and self.thread_is_alive:

‎cmd2/managed_output.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,9 @@ def write(self, data: str) -> int:
6363
"""
6464
with self._lock.transaction("managed write"):
6565
try:
66+
before_write = getattr(self.bridge, "before_managed_write", None)
67+
if before_write is not None:
68+
before_write()
6669
if self._output is None:
6770
written = self._stream.write(data)
6871
else:

0 commit comments

Comments
 (0)