diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e2fb4fde..5d121708f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ +## 4.5.0 (TBD) + +- Enhancements + - `enable_bottom_toolbar=True` now keeps the toolbar visible and refreshing during command + execution. Command output appears above it. A line of output left unfinished when a command + ends is ended there, so the next prompt starts on a new line while the toolbar is enabled. + - `Cmd.read_input()` and `Cmd.read_secret()` now keep the bottom toolbar visible while they wait + for input, refreshing at the same `refresh_interval` as the main prompt, instead of the + toolbar disappearing for the duration of the nested prompt. `Cmd.select()` is unchanged, since + prompt-toolkit's `choice()` offers no way to configure a refresh interval + ## 4.4.3 (2026-11-16) - Bug Fixes diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 5adb6ba6a..374d62f40 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -48,6 +48,7 @@ from collections import deque from collections.abc import ( Callable, + Generator, Iterable, Mapping, Sequence, @@ -109,6 +110,7 @@ from . import ( argparse_completer, argparse_utils, + command_toolbar, constants, plugin, utils, @@ -429,7 +431,7 @@ def __init__( This allows CommandSets with custom constructor parameters to be loaded. This also allows the a set of CommandSets to be provided when `auto_load_commands` is set to False - :param enable_bottom_toolbar: if ``True``, enables a bottom toolbar while at the main prompt. + :param enable_bottom_toolbar: if ``True``, enables a bottom toolbar at the main prompt and during commands. Override ``get_bottom_toolbar()`` to define its content. :param enable_rprompt: if ``True``, enables a right prompt while at the main prompt. Override ``get_rprompt()`` to define its content. @@ -572,6 +574,9 @@ def __init__( # custom prompt). Completion and UI logic should reference this variable # to ensure they modify the correct session state. self.active_session = self.main_session + self._command_toolbar: command_toolbar.CommandToolbar | None = None + # Set once a toolbar fails to start, so the failure is reported only once + self._command_toolbar_disabled = False # Commands to exclude from the history command self.exclude_from_history = ["_eof", "history"] @@ -2010,6 +2015,9 @@ def ppaged( fits on the screen. A pager is not used inside a script (Python or text) or when output is redirected or piped, and in these cases, output is sent to `poutput`. + The pager takes over the terminal, so the bottom toolbar is hidden while it is open and + comes back when it exits. + If the pager program cannot be run, for example because it is not installed, the output is printed without one. That pager command is not tried again while the application runs. @@ -2067,7 +2075,7 @@ def ppaged( # Prevent KeyboardInterrupts while in the pager. The pager application will # still receive the SIGINT since it is in the same process group as us. - with self.sigint_protection, utils._utf8_console(): + with self.suspend_bottom_toolbar(), self.sigint_protection, utils._utf8_console(): import subprocess pipe_proc = subprocess.Popen( # noqa: S602 @@ -2170,7 +2178,7 @@ def ppretty( def get_bottom_toolbar(self) -> AnyFormattedText: """Get the bottom toolbar content. - This method is called by prompt-toolkit while at the main prompt if ``enable_bottom_toolbar`` + This method is called by prompt-toolkit at the main prompt and during commands if ``enable_bottom_toolbar`` was set to ``True`` during initialization. Because prompt-toolkit executes this callback on every UI refresh (such as on every keypress or at scheduled refresh intervals), keeping this function highly optimized is critical to ensuring the CLI remains responsive. @@ -2179,10 +2187,70 @@ def get_bottom_toolbar(self) -> AnyFormattedText: your application. This could be information like the application name, current state, or even a real-time clock. + During command execution this callback runs in a background UI thread. Protect shared + state with a lock when necessary, but never hold that lock in a command while it prompts + for input, pages output, runs a shell command, or otherwise pauses the toolbar: pausing + waits for this callback to return. The toolbar is suspended while another prompt, a + pager, or an interactive shell owns the terminal. + + If this callback raises an exception during a command, the error is reported once and the + command carries on without the toolbar. + :return: Content to populate the bottom toolbar. """ return None + @contextlib.contextmanager + def suspend_bottom_toolbar(self) -> Generator[None]: + """Temporarily hide the command toolbar and give exclusive access to the terminal. + + Use this context manager around application-specific calls to ``input()``, other + terminal UIs, or subprocesses that inherit the terminal. cmd2 automatically suspends + its toolbar for its own input prompts, external pagers, and shell commands. + """ + if self._command_toolbar is None: + yield + else: + with self._command_toolbar.suspend(): + yield + + @contextlib.contextmanager + def _command_toolbar_context(self) -> Generator[None]: + """Display the toolbar around commands launched by the interactive command loop.""" + if ( + self._command_toolbar is not None + or self._command_toolbar_disabled + or self.main_session.bottom_toolbar is None + or not self._is_tty_session(self.main_session) + ): + yield + return + + try: + with self.sigint_protection: + toolbar = command_toolbar.CommandToolbar(self) + toolbar.start() + self._command_toolbar = toolbar + except Exception as exc: # noqa: BLE001 + # The toolbar is cosmetic, so a display that cannot start must not take + # the command down, nor escape cmdloop() and leave its signal handlers + # installed. Report it once and run without it for the rest of the session. + self._command_toolbar_disabled = True + self.perror(f"Disabling the bottom toolbar during commands: {exc!r}") + yield + return + + try: + yield + finally: + with self.sigint_protection: + try: + toolbar.stop() + finally: + # Always forget a toolbar that has been torn down. Keeping a failed + # one would disable the toolbar for the rest of the session. + self._command_toolbar = None + def get_rprompt(self) -> AnyFormattedText: """Provide text to populate the prompt-toolkit right prompt. @@ -3220,6 +3288,7 @@ def onecmd_plus_hooks( return stop + @command_toolbar.suspend_toolbar def _run_cmdfinalization_hooks(self, stop: bool, statement: Statement | None) -> bool: """Run the command finalization hooks.""" if not sys.platform.startswith("win") and self._initial_termios_settings is not None and self.stdin.isatty(): @@ -3445,9 +3514,15 @@ def _redirect_output(self, statement: Statement) -> utils.RedirectionSavedState: if shell: kwargs["executable"] = shell - # For any stream that is a StdSim, we will use a pipe so we can capture its output - pipe_stdout = None if isinstance(self.stdout, utils.StdSim) else self.stdout # type: ignore[unreachable] - pipe_stderr = None if isinstance(sys.stderr, utils.StdSim) else sys.stderr + # Hand the pipe process the real terminal when there is one to inherit, since it + # may be interactive. Otherwise capture its output so it can pass through a Python + # stream, including the toolbar proxy which prints above the running display. + pipe_stdout = ( + None + if isinstance(self.stdout, utils.StdSim) # type: ignore[unreachable] + else command_toolbar.pipe_target(self.stdout) + ) + pipe_stderr = None if isinstance(sys.stderr, utils.StdSim) else command_toolbar.pipe_target(sys.stderr) terminal_fd: int | None = None popen_command = statement.redirect_to @@ -3480,6 +3555,12 @@ def _redirect_output(self, statement: Statement) -> utils.RedirectionSavedState: kwargs["executable"] = posix_shell with contextlib.ExitStack() as pipe_stack, contextlib.ExitStack() as setup_stack: + # The toolbar can neither draw nor hold the keyboard while a pipe process owns the terminal, so step aside + # until _restore_output() has reaped it. Entered first, the suspension ends last, once cmd2 has the terminal + # back. + if pipe_stdout is not None or pipe_stderr is not None: + pipe_stack.enter_context(self.suspend_bottom_toolbar()) + # The console stays UTF-8 from before the pipe process starts, since a program may read the code page once as # it starts, until _restore_output() has reaped it. pipe_stack.enter_context(utils._utf8_console()) @@ -3551,7 +3632,8 @@ def _redirect_output(self, statement: Statement) -> utils.RedirectionSavedState: self.stdout = new_stdout setup_stack.pop_all() - # Keep the UTF-8 console and the pipeline's job control until _restore_output() reaps the pipe process. + # Keep the toolbar suspended, the UTF-8 console and the pipeline's job control until _restore_output() reaps + # the pipe process. redir_saved_state.pipe_context = pipe_stack.pop_all() elif statement.redirector in (constants.REDIRECTION_OVERWRITE, constants.REDIRECTION_APPEND): @@ -3611,7 +3693,8 @@ def _restore_output(self, statement: Statement, saved_redir_state: utils.Redirec :param statement: Statement object which contains the parsed input from the user :param saved_redir_state: contains information needed to restore state data """ - # The UTF-8 console and the pipeline's job control end once its pipe process has been reaped. + # The UTF-8 console and the pipeline's job control end once its pipe process has been reaped, and then the toolbar + # gets the terminal back. with contextlib.ExitStack() as pipe_stack: if saved_redir_state.pipe_context is not None: pipe_stack.callback(saved_redir_state.pipe_context.close) @@ -3749,6 +3832,7 @@ def _is_tty_session(session: PromptSession[str]) -> bool: # a DummyOutput. return not isinstance(session.input, DummyInput) + @command_toolbar.suspend_toolbar def _read_raw_input( self, prompt: Callable[[], ANSI | str] | ANSI | str, @@ -3883,6 +3967,7 @@ def read_input( temp_session: PromptSession[str] = PromptSession( auto_suggest=self.main_session.auto_suggest, + bottom_toolbar=self.get_bottom_toolbar if self.main_session.bottom_toolbar is not None else None, color_depth=self.main_session.color_depth, complete_style=self.main_session.complete_style, complete_in_thread=self.main_session.complete_in_thread, @@ -3893,6 +3978,7 @@ def read_input( key_bindings=self.main_session.key_bindings, input=self.main_session.input, output=self.main_session.output, + refresh_interval=self.main_session.refresh_interval, style=self.main_session.style, ) @@ -3910,10 +3996,12 @@ def read_secret( :raises Exception: any other exceptions raised by prompt() """ temp_session: PromptSession[str] = PromptSession( + bottom_toolbar=self.get_bottom_toolbar if self.main_session.bottom_toolbar is not None else None, color_depth=self.main_session.color_depth, enable_suspend=self.main_session.enable_suspend, input=self.main_session.input, output=self.main_session.output, + refresh_interval=self.main_session.refresh_interval, style=self.main_session.style, ) @@ -4035,7 +4123,11 @@ def _cmdloop(self) -> None: """ try: # Run startup commands - stop = self.runcmds_plus_hooks(self._startup_commands) + if self._startup_commands: + with self._command_toolbar_context(): + stop = self.runcmds_plus_hooks(self._startup_commands) + else: + stop = False self._startup_commands.clear() while not stop: @@ -4049,7 +4141,8 @@ def _cmdloop(self) -> None: line = "_eof" # Run the command along with all associated pre and post hooks - stop = self.onecmd_plus_hooks(line) + with self._command_toolbar_context(): + stop = self.onecmd_plus_hooks(line) finally: with self.sigint_protection: # Shut down the alert thread. @@ -4879,6 +4972,7 @@ def do_quit(self, _: argparse.Namespace) -> bool | None: self.last_result = True return True + @command_toolbar.suspend_toolbar def select(self, opts: str | Iterable[str] | Iterable[tuple[Any, str | None]], prompt: str = "Your choice? ") -> Any: """Present a menu to the user. @@ -5117,6 +5211,7 @@ def do_shell(self, args: argparse.Namespace) -> None: utils.expand_user_in_tokens(tokens) self._run_shell_command(" ".join(tokens)) + @command_toolbar.suspend_toolbar def _run_shell_command(self, command: str) -> None: """Run a command line in the OS shell and wait for it to finish. @@ -5285,6 +5380,7 @@ def _restore_cmd2_env(self, cmd2_env: _SavedCmd2Env) -> None: readline.set_completer(cmd2_env.completer) + @command_toolbar.suspend_toolbar def _run_python(self, *, pyscript: str | None = None) -> bool | None: """Run an interactive Python shell or execute a pyscript file. @@ -5496,6 +5592,7 @@ def _build_ipython_parser() -> Cmd2ArgumentParser: return argparse_utils.DEFAULT_ARGUMENT_PARSER(description="Run an interactive IPython shell.") @with_argparser(_build_ipython_parser) + @command_toolbar.suspend_toolbar def do_ipy(self, _: argparse.Namespace) -> bool | None: # pragma: no cover """Run an interactive IPython shell. @@ -6068,6 +6165,9 @@ def set_window_title(self, title: str) -> None: several titles are set before then, only the latest is written. Output errors are ignored so they can't disrupt the prompt. + The bottom toolbar's display counts as a prompt here. While it is shown during a command, the + title is written on its event loop in the same way. + :param title: the new window title """ with self._window_title_lock: @@ -6108,6 +6208,11 @@ def _get_prompt_loop(self) -> asyncio.AbstractEventLoop | None: if select_app is not None: apps.append(select_app) + # While a command runs, the bottom toolbar's display draws on this terminal from its own thread. + toolbar = self._command_toolbar + if toolbar is not None: + apps.append(toolbar.app) + for app in apps: loop = app.loop if loop is not None: @@ -6358,20 +6463,22 @@ def cmdloop(self, intro: RenderableType = "") -> int: self.poutput(self.intro) # And then call _cmdloop() to enter the main loop - self._cmdloop() + try: + self._cmdloop() + finally: + # Restore original signal handlers however the loop ended. Leaving cmd2's + # handlers installed would outlive the application in its host process. + signal.signal(signal.SIGINT, original_sigint_handler) + + if not sys.platform.startswith("win"): + signal.signal(signal.SIGHUP, original_sighup_handler) + signal.signal(signal.SIGTERM, original_sigterm_handler) # Run the postloop() no matter what for func in self._postloop_hooks: func() self.postloop() - # Restore original signal handlers - signal.signal(signal.SIGINT, original_sigint_handler) - - if not sys.platform.startswith("win"): - signal.signal(signal.SIGHUP, original_sighup_handler) - signal.signal(signal.SIGTERM, original_sigterm_handler) - return self.exit_code ### diff --git a/cmd2/command_toolbar.py b/cmd2/command_toolbar.py new file mode 100644 index 000000000..dc709f1e3 --- /dev/null +++ b/cmd2/command_toolbar.py @@ -0,0 +1,575 @@ +"""Internal support for displaying a toolbar during synchronous commands.""" + +import asyncio +import codecs +import contextlib +import contextvars +import functools +import os +import re +import signal +import sys +import threading +import time +from collections.abc import Callable, Generator +from typing import TYPE_CHECKING, Any, TextIO, TypeVar, cast + +from prompt_toolkit.application import Application, create_app_session, run_in_terminal +from prompt_toolkit.filters import Condition, to_filter +from prompt_toolkit.input.typeahead import get_typeahead, store_typeahead +from prompt_toolkit.key_binding import KeyBindings +from prompt_toolkit.key_binding.key_processor import KeyPress, KeyPressEvent +from prompt_toolkit.layout import HSplit, Layout, Window +from prompt_toolkit.layout.containers import ConditionalContainer +from prompt_toolkit.patch_stdout import StdoutProxy +from prompt_toolkit.utils import get_cwidth, suspend_to_background_supported + +if TYPE_CHECKING: + from .cmd2 import Cmd + +# Control sequences, operating system commands, and two-character escapes: text which takes +# no room on the screen. +_ESCAPE_RE = re.compile(r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])") + +_F = TypeVar("_F", bound=Callable[..., Any]) + + +def suspend_process_group(suspend_group: bool = True) -> None: + """Stop this process, or its whole process group, with SIGTSTP from any thread. + + A process-directed stop signal can be taken by a thread other than the sender. Sent + from the display thread, it lands on the main thread, and the display thread carries + on for a few milliseconds: it puts the terminal back into raw mode and redraws before + the job has stopped. When the shell resumes the job it restores the modes it saved + beforehand, and nothing is left to undo that -- the terminal stays cooked, keys are + held until Enter, and every cursor-position query is echoed as ``^[[row;colR``. + + So after sending the signal this thread waits for the stop to take it too. A stop + shows as time passing while asleep; a signal that was ignored, or discarded for an + orphaned process group, shows as nothing, and the wait ends on its own. + + :param suspend_group: stop the whole process group, as a shell's Ctrl-Z would, rather + than only this process + """ + if not hasattr(signal, "SIGTSTP"): # pragma: no cover - POSIX only + return + os.kill(0 if suspend_group else os.getpid(), signal.SIGTSTP) + deadline = time.monotonic() + 0.25 + while (before := time.monotonic()) < deadline: + time.sleep(0.01) + if time.monotonic() - before > 0.1: + return + + +def suspend_toolbar(func: _F) -> _F: + """Give a method exclusive access to the terminal.""" + + @functools.wraps(func) + def wrapped(self: "Cmd", *args: Any, **kwargs: Any) -> Any: + with self.suspend_bottom_toolbar(): + return func(self, *args, **kwargs) + + return cast(_F, wrapped) + + +def pipe_target(stream: Any) -> Any: + """Return the stream a pipe process can inherit, or ``None`` if its output must be captured. + + A pipe process may be interactive, such as ``less`` or ``fzf``, so it needs the real + terminal rather than a stream this process reads on its behalf. Look through a + :class:`ToolbarStream` wrapper, but only hand back a stream owning a file descriptor. + """ + if isinstance(stream, ToolbarStream): + stream = stream.original + try: + stream.fileno() + except (AttributeError, OSError): + # io.UnsupportedOperation, raised by streams like io.StringIO, subclasses OSError. + return None + return stream + + +class _ContextStdoutProxy(StdoutProxy): + """Print above the toolbar from its isolated application session, keeping unfinished lines. + + prompt-toolkit draws the toolbar starting at the cursor, and erases it from the first + column of that row before printing anything more. Output which stopped in the middle of + a line, such as ``Working...`` or a progress line ending in a carriage return, would be + erased with it. So a line left unfinished is ended on the screen, which gives the toolbar + a row of its own, and it is continued from where it stopped when more output arrives. + """ + + def __init__(self, toolbar_rows: Callable[[], int] = lambda: 1) -> None: + """Start printing above a toolbar. + + :param toolbar_rows: returns how many rows the toolbar takes below the output + """ + # The line which output last left unfinished, exactly as written. Set before the + # base class starts the thread which reads it. + self._unfinished = "" + self._toolbar_rows = toolbar_rows + # The worker already combines queued writes. A batching sleep would also delay + # close(), which runs at each command finalization boundary. + super().__init__(raw=True, sleep_between_writes=0) + + def _start_write_thread(self) -> threading.Thread: + context = contextvars.copy_context() + thread = threading.Thread(target=context.run, args=(self._write_thread,), daemon=True) + thread.start() + return thread + + def _write_and_flush(self, loop: asyncio.AbstractEventLoop | None, text: str) -> None: + """Write text above the toolbar as the base class does, continuing an unfinished line.""" + + def write_and_flush() -> None: + output = self._output + # See the base class: Windows resets autowrap at each flush. + output.enable_autowrap() + if self._unfinished: + # The cursor is at the start of the row below the unfinished line. Go back + # to the row its last carriage return left it on, and write the rest of + # it again to put the cursor, and any style it set, where they were. + output.cursor_up(self._rows(self._unfinished)) + output.write_raw(self._unfinished) + output.write_raw(text) + line = self._last_line(self._unfinished + text) + if line: + output.write_raw("\r\n") + # A line whose start has scrolled off the screen can't be found again, so it + # stays ended where it is. Its first row scrolls off once the screen has no + # room for the whole line and the toolbar below it. A row is needed below the + # line even with no toolbar, for the cursor which ended it. + room = output.get_size().rows - max(1, self._toolbar_rows()) + self._unfinished = line if self._rows(line) <= room else "" + output.flush() + + if loop is None: + write_and_flush() + else: + loop.call_soon_threadsafe(lambda: run_in_terminal(write_and_flush, in_executor=False)) + + @staticmethod + def _last_line(text: str) -> str: + """Return what must be written again to continue the line which text leaves unfinished. + + :param text: everything written since the last finished line + :return: the unfinished line from its last carriage return, or "" if the last line is + finished + """ + line = text.rpartition("\n")[2] + if not line.strip("\r"): + # Nothing has been written on this row, wherever the cursor returned to. + return "" + # A carriage return went back to the start of the row the cursor is on, so nothing + # before it is needed to find that place again. Dropping it also keeps a progress + # line which is redrawn thousands of times from growing without bound. + return line[max(0, line.rfind("\r")) :] + + def _rows(self, line: str) -> int: + """Return how many rows below its start the cursor was left after line was ended.""" + width = self._width(line) + columns = self._wrap_columns() + if self._wraps_at_once(): + # A line which has just filled a row has put the cursor on the next one. + return width // columns + 1 + return max(1, -(-width // columns)) + + def _wraps_at_once(self) -> bool: + """Return whether the terminal moves to the next row as soon as a row is full. + + A terminal which understands escape sequences waits for the next character. A legacy + Windows console does not wait. It gets prompt-toolkit's Win32Output which, unlike its + other Windows outputs, has no vt100 output to write escape sequences with. + """ + output = self._output + return hasattr(output, "get_win32_screen_buffer_info") and not hasattr(output, "vt100_output") + + def _wrap_columns(self) -> int: + """Return how many columns the terminal fits on a row before it wraps a line. + + prompt-toolkit's Windows outputs report one column fewer than the console has, which + keeps what prompt-toolkit draws out of the last column. Text written raw is wrapped by + the console itself, at the width of its screen buffer. + """ + screen_buffer_info = getattr(self._output, "get_win32_screen_buffer_info", None) + if screen_buffer_info is not None: + return max(1, int(screen_buffer_info().dwSize.X)) + return max(1, self._output.get_size().columns) + + @staticmethod + def _width(line: str) -> int: + return get_cwidth(_ESCAPE_RE.sub("", line)) + + +class ToolbarStream: + """Keep a stable stream identity across suspensions and cmd2 redirections.""" + + def __init__(self, original: TextIO, lock: "threading.RLock") -> None: + """Wrap a terminal stream while preserving its ordinary file attributes.""" + self.original = original + self.proxy: StdoutProxy | None = None + # Shared with the toolbar so a write from another thread cannot land on a proxy + # that is being closed. Such a write is accepted by the dead proxy and discarded. + self._lock = lock + self.buffer = _ToolbarBuffer(self) + + def write(self, data: str) -> int: + """Write above the toolbar, or directly while the toolbar is suspended.""" + with self._lock: + return (self.proxy or self.original).write(data) + + def flush(self) -> None: + """Flush the currently active output stream.""" + with self._lock: + (self.proxy or self.original).flush() + + def __getattr__(self, name: str) -> Any: + """Delegate file attributes to the original terminal stream.""" + return getattr(self.original, name) + + +class _ToolbarBuffer: + """Decode subprocess output incrementally, including split Unicode characters.""" + + def __init__(self, stream: ToolbarStream) -> None: + self.stream = stream + self._decoder = codecs.getincrementaldecoder(stream.original.encoding or "utf-8")(errors="replace") + self._lock = threading.Lock() + + def write(self, data: bytes) -> int: + with self._lock: + self.stream.write(self._decoder.decode(data)) + return len(data) + + def flush(self) -> None: + self.stream.flush() + + def finish(self) -> None: + with self._lock: + self.stream.write(self._decoder.decode(b"", final=True)) + self._decoder.reset() + + +class CommandToolbar: + """Borrow the main prompt's application while a command runs on the main thread. + + The display owns terminal input so it can receive cursor position reports. Keys + typed during execution are saved for the next prompt; Ctrl-C is sent to cmd2's + normal signal handler. Terminal output goes through prompt-toolkit's stdout + proxy so that it appears above the toolbar. + """ + + def __init__(self, cmd: "Cmd") -> None: + """Configure a command display using the main prompt's terminal and settings.""" + self.cmd = cmd + self._stack: contextlib.ExitStack | None = None + self._keys: list[KeyPress] = [] + self._error: BaseException | None = None + self._ready = threading.Event() + self._thread: threading.Thread | None = None + self._streams: list[ToolbarStream] = [] + self._proxy: StdoutProxy | None = None + self._lock = threading.RLock() + self._pausing = False + # Set once the display has stopped after an error. It is reported once and not + # restarted, so a callback which keeps failing cannot repeat that at every pause. + self._failed = False + + session = cmd.main_session + self.app = session.app + # Ctrl-Z during a command is handled on the display's thread, where upstream's + # version would not hold the thread until the job has stopped. + if "suspend_to_background" not in vars(self.app): + cast("Any", self.app).suspend_to_background = self._suspend_to_background + # PromptSession has no public hook for replacing just its input area. + # Keep this small dependency on its layout shape in one place, and fail + # explicitly if upstream changes it. Reuse the actual toolbar container, + # including its visibility filter and support for multiline toolbars. + root = session.layout.container + if not isinstance(root, HSplit): + raise TypeError("Unsupported PromptSession layout") + self.toolbar = root.children[-1] + if not ( + isinstance(self.toolbar, ConditionalContainer) + and isinstance(self.toolbar.content, Window) + and self.toolbar.content.style == "class:bottom-toolbar" + ): + raise RuntimeError("Cannot locate PromptSession bottom toolbar") + self._toolbar_window = self.toolbar.content + # The rows the toolbar took when it was last drawn, to begin with by the main prompt. + # Each run of the application forgets what it drew, and prompt-toolkit leaves the + # toolbar out until the terminal has reported where its cursor is, which can be after + # a command's first output. The toolbar is about to take these rows again. + self._toolbar_height = 0 + self._note_toolbar_height() + self._layout = Layout(HSplit([Window(height=0), Window(), self.toolbar])) + self._display_stack: contextlib.ExitStack | None = None + bindings = KeyBindings() + + @bindings.add("") + def save_key(event: KeyPressEvent) -> None: + self._keys.extend(event.key_sequence) + + @bindings.add("c-c") + def interrupt(event: KeyPressEvent) -> None: # noqa: ARG001 + # Match the terminal's normal Ctrl-C input flush: cancelled typeahead + # must not become a command when the main prompt resumes. + self._keys.clear() + if sys.platform == "win32": + # os.kill(..., SIGINT) terminates the process on Windows instead + # of dispatching Python's signal handler. This reaches only this + # process, so a console subprocess started by a command keeps + # running until it is waited on. + import _thread + + _thread.interrupt_main() + else: + # Raw mode clears ISIG, so no signal is generated for us. Signal the + # foreground process group the way the terminal driver would, since a + # command may be waiting on a subprocess that shares this group. Pipe + # processes are excluded because cmd2 starts them in their own session + # and forwards to them from sigint_handler(). + os.killpg(os.getpgrp(), signal.SIGINT) + + @bindings.add( + "c-z", + filter=Condition(lambda: suspend_to_background_supported() and to_filter(session.enable_suspend)()), + ) + def suspend(event: KeyPressEvent) -> None: + # This restores cooked mode before stopping the process group and + # redraws the toolbar after the process resumes. + event.app.suspend_to_background() + + self._bindings = bindings + + @staticmethod + def _suspend_to_background(suspend_group: bool = True) -> None: + """Suspend like upstream's ``Application.suspend_to_background()``, from any thread.""" + run_in_terminal(functools.partial(suspend_process_group, suspend_group)) + + def _after_render(self, app: Application[str]) -> None: # noqa: ARG002 + self._note_toolbar_height() + self._ready.set() + + def _note_toolbar_height(self) -> None: + """Remember how many rows the toolbar took, if the last frame drew it.""" + info = self._toolbar_window.render_info + if info is not None: + self._toolbar_height = info.window_height + + def _toolbar_rows(self) -> int: + """Return how many rows the toolbar took when it was last drawn.""" + return self._toolbar_height + + def start(self) -> None: + """Start rendering and protect terminal output.""" + stack = contextlib.ExitStack() + self._stack = stack + self._ready.clear() + self._error = None + try: + stack.enter_context(create_app_session(input=self.app.input, output=self.app.output)) + # Only replace terminal streams. In particular, preserve redirected stderr + # and self.stdout when a nested command has redirected its output to a file. + for obj, name in ((self.cmd, "stdout"), (sys, "stdout"), (sys, "stderr")): + stream = getattr(obj, name) + if stream.isatty(): + wrapper = ToolbarStream(stream, self._lock) + self._streams.append(wrapper) + setattr(obj, name, cast(TextIO, wrapper)) + stack.callback(self._restore_stream, obj, name, wrapper) + self._resume() + except BaseException: + self.stop() + raise + + @staticmethod + def _restore_stream(obj: Any, name: str, stream: ToolbarStream) -> None: + if getattr(obj, name) is stream: + setattr(obj, name, stream.original) + + def _resume(self) -> None: + if self._failed: + return + self._ready.clear() + self._error = None + stack = self._display_stack = contextlib.ExitStack() + # Replace key_bindings only together with a layout whose focused window prompt-toolkit + # has not seen with other bindings. It caches the bindings it merges for each focused + # window, application bindings included, and does not notice this attribute being + # reassigned, so reusing a window with different bindings would keep the old ones. + # This layout and the main prompt's have windows of their own. + for name, value in (("layout", self._layout), ("key_bindings", self._bindings), ("erase_when_done", True)): + stack.callback(setattr, self.app, name, getattr(self.app, name)) + setattr(self.app, name, value) + self.app.after_render += self._after_render + stack.callback(self.app.after_render.remove_handler, self._after_render) + context = contextvars.copy_context() + + def run() -> None: + try: + self.app.run(pre_run=self._handle_loop_errors, handle_sigint=False, set_exception_handler=False) + except EOFError: + pass + except BaseException as exc: # noqa: BLE001 + # Propagate startup/render failures to the command thread. Stopping after an + # error in the loop draws a last frame, and a failure there is only a + # consequence of the error already recorded. + if self._error is None: + self._error = exc + finally: + self._ready.set() + self._app_exited() + + self._thread = threading.Thread(target=context.run, args=(run,), name="cmd2-toolbar", daemon=True) + self._thread.start() + self._ready.wait() + if self._error is not None: + raise self._error + proxy = _ContextStdoutProxy(self._toolbar_rows) + with self._lock: + self._proxy = proxy + for stream in self._streams: + stream.proxy = proxy + + def _handle_loop_errors(self) -> None: + """Stop the display on the first unhandled error in its event loop. + + prompt-toolkit's own handler prints the traceback and waits for Enter, which would + hold up a command that is still running. With no handler at all, asyncio logs each + error to stderr. That write goes through the stdout proxy, whose redraw of the + toolbar calls a failing ``get_bottom_toolbar()`` again, so a single faulty callback + buries the command's output in tracebacks for as long as the command runs. + """ + asyncio.get_running_loop().set_exception_handler(self._loop_error) + + def _loop_error(self, loop: asyncio.AbstractEventLoop, context: dict[str, Any]) -> None: # noqa: ARG002 + """Record the first error for the command thread and end the display. + + ``_resume()`` raises it if the display has not finished starting. After that, + ``_app_exited()`` reports it once. + """ + if self._error is None: + self._error = context.get("exception") or RuntimeError(context.get("message", "unknown error")) + self._exit() + + def _app_exited(self) -> None: + """Give the terminal back to the streams when the display stops on its own. + + ``_ready`` is set as soon as the first frame renders, so a failure after that is + never seen by the command thread waiting in ``_resume()``. The display is gone at + that point and its stdout proxy can no longer reach the terminal, so anything + written through it would be discarded without a trace. + """ + if self._pausing: + # A deliberate pause restores the streams itself, in the right order. + return + + with self._lock: + # Leave self._proxy set so that the next _pause() still drains and closes + # it. With the display gone, its worker writes to the terminal directly. + started = self._proxy is not None + for stream in self._streams: + stream.proxy = None + + # A proxy exists only once _resume() has handed startup failures to the command + # thread, so reporting here does not duplicate the exception it raises. + if started and self._error is not None: + self._report_failure(self._error) + + def _report_failure(self, error: BaseException) -> None: + """Say once that the command carries on without its toolbar.""" + if not self._failed: + self._failed = True + self.cmd.perror(f"Bottom toolbar stopped after an error: {error!r}") + + def _exit(self) -> None: + """Stop the display unless it has already stopped on its own. + + Application.exit() raises once the result is set, and this runs later than the + check that scheduled it. Any exception here would reach the loop's default + handler, which prints a traceback over the terminal. + + Output queued before this does not need draining: Application.run_async() waits + for cursor position reports and for run_in_terminal() calls still in flight + before its loop closes. + """ + if self.app.is_running and not self.app.is_done: + self.app.exit() + + def _pause(self) -> None: + self._pausing = True + try: + try: + # Hold off other threads while the proxy drains so their output is never + # handed to a proxy whose worker has already stopped. Writes that arrive + # after this go straight to the terminal, still in order. + with self._lock: + try: + if self._proxy is not None: + self._proxy.flush() + self._proxy.close() + finally: + self._proxy = None + for stream in self._streams: + stream.proxy = None + finally: + # The lock is released before joining, since the toolbar thread may be + # blocked writing through a stream that is waiting on it. + if self.app.is_running and self.app.loop is not None: + self.app.loop.call_soon_threadsafe(self._exit) + if self._thread is not None: + self._thread.join() + self._thread = None + # Write any window title whose callback the display's loop didn't run. The display + # has stopped, so this can't interleave with its rendering. + self.cmd._flush_pending_window_title_quietly() + # Return the borrowed application to the main prompt, including on + # proxy failures. The upstream toolbar owned a separate application. + if self._display_stack is not None: + self._display_stack.close() + self._display_stack = None + # Application.run() saves its unprocessed queue before the thread + # exits. Those keys arrived after the ones handled by save_key(). + pending_keys = get_typeahead(self.app.input) + store_typeahead(self.app.input, self._keys + pending_keys) + self._keys.clear() + finally: + self._pausing = False + + def stop(self) -> None: + """Flush output, stop rendering, and restore the terminal and its streams.""" + try: + for stream in self._streams: + stream.buffer.finish() + self._pause() + finally: + if self._stack is not None: + self._stack.close() + self._stack = None + + @property + def is_active(self) -> bool: + """Whether the display currently owns the terminal.""" + return self._proxy is not None and self.app.is_running + + @contextlib.contextmanager + def suspend(self) -> Generator[None]: + """Temporarily restore ordinary terminal access, including nested suspensions.""" + if self._proxy is None: + yield + return + with self.cmd.sigint_protection: + self._pause() + try: + yield + finally: + with self.cmd.sigint_protection: + try: + self._resume() + except Exception as exc: # noqa: BLE001 + # The toolbar is cosmetic. A display that cannot come back must not fail + # the command which paused it, nor escape cmdloop() from command + # finalization. The command carries on without one, and stop() still + # returns the borrowed application to the main prompt. + self._report_failure(exc) diff --git a/cmd2/utils.py b/cmd2/utils.py index 908df7337..761318db8 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -1534,8 +1534,8 @@ def __init__( self.saved_pipe_proc_reader = pipe_proc_reader self.saved_redirecting = saved_redirecting - # Holds what a pipe needs until its pipe process has been reaped: on Windows a UTF-8 console, and for a terminal - # pipeline its job control + # Holds what a pipe needs until its pipe process has been reaped: the bottom toolbar's suspension while the pipe + # process owns the terminal, on Windows a UTF-8 console, and for a terminal pipeline its job control self.pipe_context: contextlib.ExitStack | None = None diff --git a/docs/examples/embedding_in_textual.md b/docs/examples/embedding_in_textual.md index 25924bc83..e1d4c6ada 100644 --- a/docs/examples/embedding_in_textual.md +++ b/docs/examples/embedding_in_textual.md @@ -120,9 +120,12 @@ The example handles several details which are easy to miss when building somethi ## A Bottom Toolbar Which Stays While Commands Run -A [bottom toolbar](../features/prompt.md#bottom-toolbar) is drawn by `prompt-toolkit` as part of the -prompt, so it is only on the screen while the prompt is. The same embedding technique gives you one -which stays, and keeps refreshing, while a command runs. The +`cmd2` can keep its own [bottom toolbar](../features/prompt.md#bottom-toolbar) on the screen while a +command runs. It draws that toolbar in the terminal which the command is using, so it has to hide it +whenever something else +[takes over the terminal](../features/prompt.md#commands-that-take-over-the-terminal), as a shell +command does. The same embedding technique gives you a toolbar which is drawn outside that terminal, +so it stays, and keeps refreshing, whatever runs there. The [textual_tty_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_toolbar.py) example is a Textual application which is nothing but a terminal pane running a `cmd2` application and a toolbar docked below it, so it looks like the `cmd2` application running on its own: @@ -131,8 +134,9 @@ and a toolbar docked below it, so it looks like the `cmd2` application running o uv run examples/textual_tty_toolbar.py ``` -Try `slow`, `burst 2000 1`, or resizing the window while a command runs. Pass `--cmd2-only` to see -what `cmd2` does without Textual, where the toolbar disappears for as long as a command runs. +Try `slow`, `burst 2000 1`, `shell sleep 5`, or resizing the window while a command runs. Pass +`--cmd2-only` to compare it with the toolbar `cmd2` draws itself, without Textual, which is hidden +for as long as the shell command runs. Here the `cmd2` application doesn't draw the toolbar at all. It passes `enable_bottom_toolbar=False` to [cmd2.Cmd.__init__][] when it is running inside the Textual application, and sends what @@ -166,7 +170,8 @@ in the middle of the command's output. So this example uses a Unix socket instea - `get_bottom_toolbar()` is therefore called on that thread while a command is running on the main thread, so it must only read state which is safe to read from another thread. -This approach has costs which are easy to overlook, and they are why `cmd2` doesn't do it for you: +This approach has costs which are easy to overlook, and they are why `cmd2` draws its own toolbar in +the user's terminal instead: - There is no scrollback. The terminal pane keeps none, so output which scrolls off its top is gone, and Textual uses the terminal's alternate screen, so none of the session is in the scrollback of diff --git a/docs/features/os.md b/docs/features/os.md index 7d6489bc4..5c2329218 100644 --- a/docs/features/os.md +++ b/docs/features/os.md @@ -42,7 +42,12 @@ system. ## Terminal pagers -Output of any command can be displayed one page at a time using the [cmd2.Cmd.ppaged][] method. +Output of any command can be displayed one page at a time using the [cmd2.Cmd.ppaged][] method. A +pager is only used when the terminal is interactive. Inside a script, or when the command's output +is redirected or piped, `ppaged()` falls back to `poutput()`. + +While the [bottom toolbar](./prompt.md#bottom-toolbar) is running, a pager temporarily hides it, +because the pager takes over the terminal. The toolbar comes back when the pager exits. The pager is the command in `self.pager`, or `self.pager_chop` when chopping long lines: `less` on POSIX systems and `more` on Windows by default. If that program cannot be run, for example because diff --git a/docs/features/prompt.md b/docs/features/prompt.md index 482499c1c..20c0ed897 100644 --- a/docs/features/prompt.md +++ b/docs/features/prompt.md @@ -81,7 +81,8 @@ example for a demonstration. ## Bottom Toolbar `cmd2` supports an optional, persistent bottom toolbar that is always visible at the bottom of the -terminal window while the application is idle and waiting for input. +terminal window while the application is waiting for input and while commands execute. Command +output appears above the toolbar. ### Enabling the Toolbar @@ -112,10 +113,10 @@ def get_bottom_toolbar(self) -> AnyFormattedText: ### Refreshing the Toolbar -Since the toolbar is rendered by `prompt-toolkit` as part of the prompt, it is naturally redrawn -whenever the prompt is refreshed. If you want the toolbar to update automatically (for example, to -display a clock), you can set `refresh_interval` in the [cmd2.Cmd.__init__][] constructor to a value -greater than 0.0. +The toolbar is rendered by `prompt-toolkit` and is naturally redrawn whenever the prompt is +refreshed. If you want the toolbar to update automatically during input and command execution (for +example, to display a clock), you can set `refresh_interval` in the [cmd2.Cmd.__init__][] +constructor to a value greater than 0.0. ```py class App(cmd2.Cmd): @@ -125,7 +126,23 @@ class App(cmd2.Cmd): See the [getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py) -example for a demonstration of this technique. +example for a demonstration of this technique. Run its `work 5` command to see the clock update +while the command prints output. + +During command execution, `get_bottom_toolbar()` runs in a background UI thread. Keep the callback +fast and use a lock when reading state that a command or another thread modifies. + +!!! warning + + A command must not hold a lock which `get_bottom_toolbar()` acquires while it calls anything + that pauses the toolbar: `read_input()`, `read_secret()`, `select()`, `ppaged()`, `do_shell()`, + `run_editor()`, an embedded Python shell, or `suspend_bottom_toolbar()`. To pause the toolbar, + `cmd2` waits for the refresh in progress to finish. A callback blocked on a lock the command is + holding never finishes, so the application hangs. Copy what you need while holding the lock, + release it, and then prompt or page. + +If `get_bottom_toolbar()` raises an exception while a command is running, `cmd2` reports the error +once and the command carries on without the toolbar. !!! tip @@ -134,7 +151,40 @@ example for a demonstration of this technique. widgets which display that information. See [Embedding in Textual](../examples/embedding_in_textual.md). - The same technique can keep a toolbar on the screen while a command runs, which this one is - not: it is part of the prompt. See + The same technique can also draw the toolbar itself, in a widget of the Textual application. See [A Bottom Toolbar Which Stays While Commands Run](../examples/embedding_in_textual.md#a-bottom-toolbar-which-stays-while-commands-run) for an example, and for what it costs. + +### Commands That Take Over the Terminal + +cmd2 temporarily hides the toolbar for pagers, Python environments, and shell commands. It also +hides it while a command's output is piped to another process, since that process may be +interactive, as `less` and `fzf` are. It restores the toolbar when those operations finish. + +[cmd2.Cmd.read_input][] and [cmd2.Cmd.read_secret][] keep the toolbar visible, and it continues to +refresh at the same `refresh_interval` as the main prompt, so a clock or status display does not go +stale while your command waits for input. [cmd2.Cmd.select][] does not yet show one, because +prompt-toolkit's `choice()` has no way to configure a refresh interval and its toolbar would go +stale while the selection sits idle. + +For custom terminal UIs, calls to `input()`, or subprocesses your own command code starts, use +[cmd2.Cmd.suspend_bottom_toolbar][]: + +```py +with self.suspend_bottom_toolbar(): + answer = input("Continue? ") +``` + +Suspending matters for subprocesses even when they only print. While the toolbar is displayed, the +terminal is in raw mode, so the kernel generates no signals from keystrokes. cmd2 sends `Ctrl-C` on +to its own process group, which reaches a subprocess your command started and waits on, but `Ctrl-\` +(`SIGQUIT`) does nothing, exactly as at the main prompt. + +Output which stops in the middle of a line, such as `Working...` or a progress line redrawn with +carriage returns, stays on the screen and is continued by the output which follows it. A line still +unfinished when the command ends, or when the toolbar is hidden for one of the operations above, is +ended there, so whatever comes next starts on a new line. + +The command toolbar is used by the interactive command loop, including startup commands and scripts +launched from that loop. It is disabled for non-interactive input. Calls to `onecmd_plus_hooks()` +outside the command loop do not start a toolbar. diff --git a/examples/getting_started.py b/examples/getting_started.py index a21f84364..5b67a1ece 100755 --- a/examples/getting_started.py +++ b/examples/getting_started.py @@ -25,6 +25,7 @@ import pathlib import sys import threading +import time from typing import Annotated from prompt_toolkit.application import get_app @@ -37,7 +38,7 @@ Color, stylize, ) -from cmd2.annotated import Option +from cmd2.annotated import Argument, Option class BasicApp(cmd2.Cmd): @@ -164,6 +165,18 @@ def get_rprompt(self) -> AnyFormattedText: text = f"cwd={current_working_directory}" return [(style, text)] + @cmd2.with_annotated + def do_work( + self, + seconds: Annotated[ # Optional positional argument, so both "work" and "work 5" are valid + int, Argument(nargs="?", help_text="number of seconds to work for") + ] = 5, + ) -> None: + """Simulate work while the bottom toolbar clock keeps updating.""" + for second in range(seconds): + self.poutput(f"Working: {second + 1}/{seconds}") + time.sleep(1) + @cmd2.with_annotated def do_cat( self, diff --git a/examples/textual_tty_toolbar.py b/examples/textual_tty_toolbar.py index 7c46e760f..a2b40348c 100755 --- a/examples/textual_tty_toolbar.py +++ b/examples/textual_tty_toolbar.py @@ -1,10 +1,11 @@ #!/usr/bin/env python3 """Keep a bottom toolbar on the screen while commands run, by letting Textual draw it using textual-tty. -cmd2's bottom toolbar is drawn by prompt-toolkit as part of the prompt, so it is only there while the prompt is. -This example shows a way to have one which stays, and keeps refreshing, while a command runs: the cmd2 -application doesn't draw the toolbar at all. A small Textual application owns the terminal instead. It shows the -cmd2 application in a terminal pane which fills the screen except for the bottom, where it draws the toolbar. +cmd2 can keep its own bottom toolbar on the screen while a command runs. It draws that toolbar in the terminal +which the command is using, so it has to hide it whenever something else takes over the terminal, as a shell +command does. This example shows a way to have one which stays, and keeps refreshing, whatever runs there: the +cmd2 application doesn't draw the toolbar at all. A small Textual application owns the terminal instead. It shows +the cmd2 application in a terminal pane which fills the screen except for the bottom, where it draws the toolbar. How it works: - [textual-tty](https://github.com/ttygroup/textual-tty) provides the ``Terminal`` widget, a terminal @@ -22,7 +23,7 @@ output. A toolbar which refreshes during a command is sent from another thread, and a window title written into the terminal's stream from another thread could land in the middle of the command's output. -Things this approach gives up, which is why cmd2 doesn't do it for you: +Things this approach gives up, which is why cmd2 draws its own toolbar in your terminal instead: - Scrollback. The terminal pane keeps none, so output which scrolls off its top is gone, and Textual uses the terminal's alternate screen, so none of the session is in your terminal's own scrollback either. Pipe long output to a pager. @@ -38,8 +39,9 @@ Otherwise, install textual-tty into your own environment with ``pip install textual-tty`` and then run ``python examples/textual_tty_toolbar.py``. -Things to try: ``slow``, ``burst 2000 1``, ``page``, ``ask``, resizing the window while a command runs, and -Ctrl-C during ``slow``. To compare with what cmd2 does on its own, run just the cmd2 application, on any platform: +Things to try: ``slow``, ``burst 2000 1``, ``page``, ``ask``, ``shell sleep 5``, resizing the window while a +command runs, and Ctrl-C during ``slow``. To compare with the toolbar cmd2 draws itself, run just the cmd2 +application, on any platform: python examples/textual_tty_toolbar.py --cmd2-only @@ -171,8 +173,7 @@ def __init__(self, toolbar_socket: str | None) -> None: """Initialize the cmd2 application. :param toolbar_socket: the Unix socket of the Textual application which draws the toolbar, or None if this - application isn't running inside one. Then prompt-toolkit draws the toolbar as usual, - which means only while the prompt is on the screen. + application isn't running inside one. Then cmd2 draws the toolbar itself. """ refresh_interval = 0.5 super().__init__( diff --git a/mkdocs.yml b/mkdocs.yml index 13631c2cb..34b5499d6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -76,6 +76,7 @@ plugins: filters: - "!^_" - "get_bottom_toolbar" + - "suspend_bottom_toolbar" merge_init_into_class: true docstring_style: sphinx docstring_section_style: spacy diff --git a/tests/conftest.py b/tests/conftest.py index b2e7e091f..0c6f835b3 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1,5 +1,6 @@ """Cmd2 unit/functional testing""" +import io import os import subprocess import sys @@ -18,6 +19,11 @@ ) import pytest +from prompt_toolkit.application import create_app_session +from prompt_toolkit.data_structures import Size +from prompt_toolkit.input import create_pipe_input +from prompt_toolkit.output import DummyOutput +from prompt_toolkit.shortcuts import PromptSession import cmd2 from cmd2 import rich_utils as ru @@ -253,3 +259,47 @@ def autoload_command_sets_app(): @pytest.fixture def manual_command_sets_app(): return WithCommandSets(auto_load_commands=False) + + +class Terminal(io.StringIO): + """An in-memory stream that claims to be a terminal.""" + + def isatty(self) -> bool: + return True + + +class RecordingOutput(DummyOutput): + """A prompt-toolkit output that records everything written to a Terminal.""" + + def __init__(self, stream: Terminal) -> None: + self.stdout = stream + self.size = Size(rows=24, columns=80) + + def get_size(self) -> Size: + return self.size + + def write(self, data: str) -> None: + self.stdout.write(data) + + def write_raw(self, data: str) -> None: + self.stdout.write(data) + + +@pytest.fixture +def toolbar_app(): + app = cmd2.Cmd(allow_cli_args=False) + output = Terminal() + app.stdout = output + with create_pipe_input() as pipe: + terminal = RecordingOutput(output) + # Bind the ambient app session to this terminal. Without it, prompt-toolkit + # builds a real one on demand for calls such as patch_stdout() in + # _read_raw_input(), which needs a console that Windows CI does not provide. + with create_app_session(input=pipe, output=terminal): + app.main_session = PromptSession( + input=pipe, + output=terminal, + bottom_toolbar="STATUS", + refresh_interval=0.01, + ) + yield app, pipe, output diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py index 7e79174bb..c2e4182a4 100644 --- a/tests/test_cmd2.py +++ b/tests/test_cmd2.py @@ -3088,6 +3088,72 @@ def test_read_secret_eof(base_app, monkeypatch): base_app.read_secret("Secret: ") +def _capture_nested_session(app, call): + """Run `call` and return the real PromptSession cmd2 built for the nested prompt.""" + captured = [] + + def fake_read_raw_input(prompt, session, **kwargs): + captured.append(session) + return "typed" + + with mock.patch.object(app, "_read_raw_input", side_effect=fake_read_raw_input): + call() + assert len(captured) == 1 + return captured[0] + + +def test_read_input_session_shows_the_bottom_toolbar(base_app) -> None: + """A nested prompt keeps the persistent toolbar instead of dropping it. + + read_input() builds its own PromptSession, so without being told about the + toolbar the bar simply vanishes for as long as the nested prompt is up. + """ + base_app.main_session.bottom_toolbar = base_app.get_bottom_toolbar + + session = _capture_nested_session(base_app, lambda: base_app.read_input("Prompt> ")) + + assert session.bottom_toolbar == base_app.get_bottom_toolbar + + +def test_read_input_session_inherits_refresh_interval(base_app) -> None: + """A toolbar clock keeps ticking while the nested prompt waits for input.""" + base_app.main_session.bottom_toolbar = base_app.get_bottom_toolbar + base_app.main_session.refresh_interval = 0.25 + + session = _capture_nested_session(base_app, lambda: base_app.read_input("Prompt> ")) + + assert session.refresh_interval == 0.25 + + +def test_read_secret_session_shows_the_bottom_toolbar(base_app) -> None: + """Reading a secret keeps the persistent toolbar; the bar is not the secret.""" + base_app.main_session.bottom_toolbar = base_app.get_bottom_toolbar + + session = _capture_nested_session(base_app, lambda: base_app.read_secret("Secret: ")) + + assert session.bottom_toolbar == base_app.get_bottom_toolbar + + +def test_read_secret_session_inherits_refresh_interval(base_app) -> None: + """A toolbar clock keeps ticking while a secret is being entered.""" + base_app.main_session.bottom_toolbar = base_app.get_bottom_toolbar + base_app.main_session.refresh_interval = 0.25 + + session = _capture_nested_session(base_app, lambda: base_app.read_secret("Secret: ")) + + assert session.refresh_interval == 0.25 + + +@pytest.mark.parametrize("method", ["read_input", "read_secret"]) +def test_nested_prompt_has_no_toolbar_when_the_app_has_none(base_app, method) -> None: + """An app without a bottom toolbar must not sprout one at a nested prompt.""" + assert base_app.main_session.bottom_toolbar is None + + session = _capture_nested_session(base_app, lambda: getattr(base_app, method)("Prompt> ")) + + assert session.bottom_toolbar is None + + def test_read_input_passes_all_arguments_to_resolver(base_app): mock_choices = ["choice1", "choice2"] mock_provider = mock.MagicMock(name="provider") diff --git a/tests/test_command_toolbar.py b/tests/test_command_toolbar.py new file mode 100644 index 000000000..18b1ffe9b --- /dev/null +++ b/tests/test_command_toolbar.py @@ -0,0 +1,1075 @@ +"""Command toolbar lifecycle and terminal integration tests.""" + +import sys +import threading +import time +from types import SimpleNamespace +from unittest import mock + +import pytest +from prompt_toolkit.application import create_app_session, get_app +from prompt_toolkit.data_structures import Size +from prompt_toolkit.input import create_pipe_input +from prompt_toolkit.input.typeahead import get_typeahead +from prompt_toolkit.keys import Keys +from prompt_toolkit.layout import HSplit, Layout, Window +from prompt_toolkit.output.vt100 import Vt100_Output +from prompt_toolkit.shortcuts import PromptSession + +from cmd2 import Cmd, command_toolbar + +from .conftest import RecordingOutput, Terminal + + +def test_command_toolbar_refresh_and_output(toolbar_app, monkeypatch) -> None: + app, _, output = toolbar_app + refreshed = threading.Event() + state = ["BEFORE"] + threads = [] + + def toolbar(): + threads.append(threading.current_thread()) + if state[0] == "AFTER": + refreshed.set() + return state[0] + + app.main_session.bottom_toolbar = toolbar + monkeypatch.setattr(sys, "stdout", output) + original_stderr = sys.stderr + with app._command_toolbar_context(): + assert threading.current_thread() is threading.main_thread() + assert get_app() is app._command_toolbar.app + assert sys.stderr is original_stderr # Keep redirected stderr separate. + app.poutput("command output") + print("standard output", end="") # Flush unterminated output on exit. + state[0] = "AFTER" + assert refreshed.wait(2) + + assert "command output\n" in output.getvalue() + assert "standard output" in output.getvalue() + assert "AFTER" in output.getvalue() + assert all(thread is not threading.main_thread() and not thread.is_alive() for thread in threads) + assert app.stdout is output + assert sys.stdout is output + assert app._command_toolbar is None + + +def test_command_toolbar_redirected_output(toolbar_app, tmp_path) -> None: + app, _, output = toolbar_app + destination = tmp_path / "help.txt" + with app._command_toolbar_context(): + app.onecmd_plus_hooks(f'help > "{destination}"') + text = destination.read_text(encoding="utf-8") + assert "Cmd2 Commands" in text + assert "STATUS" not in text + assert "Cmd2 Commands" not in output.getvalue() + + +def test_command_toolbar_redirection_survives_suspension(toolbar_app, tmp_path) -> None: + app, _, output = toolbar_app + destination = tmp_path / "output.txt" + + def command(statement, **kwargs): + app.poutput("before") + with app.suspend_bottom_toolbar(): + app.poutput("during") + app.poutput("after") + return False + + with mock.patch.object(app, "onecmd", side_effect=command), app._command_toolbar_context(): + app.onecmd_plus_hooks(f'custom > "{destination}"') + app.poutput("terminal output") + + assert destination.read_text(encoding="utf-8") == "before\nduring\nafter\n" + assert "before" not in output.getvalue() + assert "during" not in output.getvalue() + assert "after" not in output.getvalue() + assert "terminal output" in output.getvalue() + assert app.stdout is output + + +def test_command_toolbar_pipe_output(toolbar_app) -> None: + app, _, output = toolbar_app + with app._command_toolbar_context(): + app.onecmd_plus_hooks(f'help | "{sys.executable}" -c "import sys; print(sys.stdin.read().upper())"') + assert "CMD2 COMMANDS" in output.getvalue() + + +class FileTerminal: + """A real file that claims to be a terminal, so it owns a descriptor a subprocess can inherit.""" + + def __init__(self, file) -> None: + self.file = file + + def isatty(self) -> bool: + return True + + def __getattr__(self, name): + return getattr(self.file, name) + + +def test_command_toolbar_pipe_process_inherits_terminal(toolbar_app, tmp_path) -> None: + app, _, _ = toolbar_app + destination = tmp_path / "terminal.txt" + running = [] + readers = [] + + def command(statement, **kwargs): + # The pipe process owns the terminal, so the toolbar must have stepped aside. + running.append(app._command_toolbar.app.is_running) + assert app.main_session.app.layout is app.main_session.layout + readers.append(app._cur_pipe_proc_reader) + app.ppaged("piped") + return False + + with destination.open("w+") as handle: + app.stdout = FileTerminal(handle) + with mock.patch.object(app, "onecmd", side_effect=command), app._command_toolbar_context(): + app.onecmd_plus_hooks(f'custom | "{sys.executable}" -c "import sys; sys.stdout.write(sys.stdin.read().upper())"') + # The terminal goes back to the toolbar once the pipe process has exited. + assert app._command_toolbar.app.is_running + assert app.stdout.proxy is not None + + assert running == [False] + # A process given the terminal writes to it directly instead of through a captured pipe. + assert readers[0]._proc.stdout is None + assert "PIPED" in destination.read_text(encoding="utf-8") + + +def test_command_toolbar_binary_output(toolbar_app) -> None: + app, _, output = toolbar_app + data = "Unicode: 😇\n".encode() + with app._command_toolbar_context(): + for byte in data: + app.stdout.buffer.write(bytes([byte])) + app.stdout.buffer.flush() + assert "Unicode: 😇\n" in output.getvalue() + + +def test_command_toolbar_interrupt_uses_signal_handler(toolbar_app) -> None: + app, pipe, _ = toolbar_app + interrupted = threading.Event() + signal_target = "_thread.interrupt_main" if sys.platform == "win32" else "cmd2.command_toolbar.os.killpg" + with mock.patch(signal_target, side_effect=lambda *_: interrupted.set()) as interrupt: + with app._command_toolbar_context(): + pipe.send_text("\x03") + assert interrupted.wait(2) + interrupt.assert_called_once() + if sys.platform != "win32": + # Reach subprocesses a command started, as the terminal driver would. + import os + import signal + + assert interrupt.call_args.args == (os.getpgrp(), signal.SIGINT) + + +def test_command_toolbar_interrupt_discards_cancelled_typeahead(toolbar_app) -> None: + app, pipe, _ = toolbar_app + interrupted = threading.Event() + received = threading.Event() + signal_target = "_thread.interrupt_main" if sys.platform == "win32" else "cmd2.command_toolbar.os.killpg" + with mock.patch(signal_target, side_effect=lambda *_: interrupted.set()), app._command_toolbar_context(): + toolbar = app._command_toolbar + + def key_processed(_): + if "".join(key.data for key in toolbar._keys).endswith("kept\n"): + received.set() + + toolbar.app.key_processor.after_key_press += key_processed + pipe.send_text("cancelled\n\x03") + assert interrupted.wait(2) + # Input entered after the interrupt should still reach the next prompt. + pipe.send_text("kept\n") + assert received.wait(2) + + assert app._read_raw_input("Next: ", app.main_session) == "kept" + + +@pytest.mark.parametrize(("supported", "enabled"), [(True, True), (True, False), (False, True)]) +def test_command_toolbar_ctrl_z(toolbar_app, supported, enabled) -> None: + app, pipe, _ = toolbar_app + app.main_session.enable_suspend = enabled + processed = threading.Event() + with ( + mock.patch("cmd2.command_toolbar.suspend_to_background_supported", return_value=supported), + app._command_toolbar_context(), + ): + toolbar = app._command_toolbar + toolbar.app.key_processor.after_key_press += lambda _: processed.set() + with mock.patch.object(toolbar.app, "suspend_to_background") as suspend: + pipe.send_text("\x1a") + assert processed.wait(2) + if supported and enabled: + suspend.assert_called_once_with() + else: + suspend.assert_not_called() + + keys = get_typeahead(pipe) + assert [key.key for key in keys] == ([] if supported and enabled else [Keys.ControlZ]) + + +@pytest.mark.skipif(sys.platform == "win32", reason="POSIX job control") +@pytest.mark.parametrize("stopped", [True, False]) +def test_suspend_process_group_waits_for_the_stop_to_take_its_thread(stopped) -> None: + """The sender sleeps until the stop reaches it, or gives up once nothing has happened. + + A stop shows as time passing while asleep, so a clock that jumps across the first sleep + stands in for a job that was stopped and then resumed. A signal that was ignored, or + discarded for an orphaned group, lets the clock advance only by what was slept. + """ + import signal + + clock = [100.0] + sleeps = [] + + def sleep(seconds): + sleeps.append(seconds) + clock[0] += 5.0 if stopped and len(sleeps) == 1 else seconds + + with ( + mock.patch("cmd2.command_toolbar.time", SimpleNamespace(monotonic=lambda: clock[0], sleep=sleep)), + mock.patch("cmd2.command_toolbar.os.kill") as kill, + ): + command_toolbar.suspend_process_group() + kill.assert_called_once_with(0, signal.SIGTSTP) + if stopped: + assert sleeps == [0.01] + else: + assert len(sleeps) > 1 + assert clock[0] >= 100.25 - 1e-6 + + +def test_command_toolbar_suspends_through_its_own_stop(toolbar_app) -> None: + """Ctrl-Z during a command stops the process with the helper which holds the display's thread.""" + app, _, _ = toolbar_app + with app._command_toolbar_context(): + toolbar = app._command_toolbar + assert vars(toolbar.app)["suspend_to_background"] == toolbar._suspend_to_background + with mock.patch("cmd2.command_toolbar.run_in_terminal") as run_in_terminal: + toolbar.app.suspend_to_background(suspend_group=False) + + (stop,) = run_in_terminal.call_args.args + assert stop.func is command_toolbar.suspend_process_group + assert stop.args == (False,) + + +def test_command_toolbar_script_output_has_no_batching_delay(toolbar_app) -> None: + app, _, output = toolbar_app + sleep = mock.Mock() + + def command(statement, **kwargs): + app.poutput("script output") + return False + + # Observe requested sleeps instead of depending on the machine's execution speed. + with ( + mock.patch("prompt_toolkit.patch_stdout.time", SimpleNamespace(sleep=sleep)), + mock.patch.object(app, "onecmd", side_effect=command), + app._command_toolbar_context(), + ): + app.runcmds_plus_hooks(["custom"] * 10) + + assert output.getvalue().count("script output\n") == 10 + assert all(call.args[0] == 0 for call in sleep.call_args_list) + + +def test_command_toolbar_suspension_and_nested_input(toolbar_app) -> None: + app, pipe, output = toolbar_app + with app._command_toolbar_context(): + toolbar = app._command_toolbar + with app.suspend_bottom_toolbar(): + assert not toolbar.app.is_running + assert app.stdout.original is output + assert app.stdout.proxy is None + with app.suspend_bottom_toolbar(): + assert not toolbar.app.is_running + assert toolbar.app.is_running + + # Feed the nested prompt only after it has taken ownership of input. + result = app._read_raw_input("Value: ", app.main_session, pre_run=lambda: pipe.send_text("answer\n")) + assert result == "answer" + assert toolbar.app.is_running + + +@pytest.mark.parametrize("launch", ["shell", "editor"]) +def test_command_toolbar_suspended_for_shell_and_editor(toolbar_app, launch) -> None: + """The shell command and the editor both hand the terminal to another program.""" + app, _, _ = toolbar_app + app.editor = "vim" + running = [] + + def popen(*args, **kwargs): + running.append(app._command_toolbar.app.is_running) + return mock.Mock(returncode=0) + + with ( + mock.patch("subprocess.Popen", side_effect=popen), + mock.patch("cmd2.utils.ProcReader"), + app._command_toolbar_context(), + ): + if launch == "shell": + app.do_shell("ls") + else: + app.run_editor("notes.txt") + assert app._command_toolbar.app.is_running + + assert running == [False] + + +class CursorOutput(RecordingOutput): + """Record moving the cursor up along with the text written.""" + + def cursor_up(self, amount: int) -> None: + self.stdout.write(f"") + + +@pytest.mark.parametrize( + ("writes", "expected"), + [ + pytest.param(["one\n", "two\nthree\n"], "one\ntwo\nthree\n", id="finished lines are written as they are"), + pytest.param( + ["Working...", " finished\n"], + "Working...\r\nWorking... finished\n", + id="an unfinished line is ended for the toolbar and continued", + ), + pytest.param( + ["\rprogress 10%", "\rprogress 20%", "\n"], + "\rprogress 10%\r\n\rprogress 10%\rprogress 20%\r\n\rprogress 20%\n", + id="a redrawn progress line is continued from its last carriage return", + ), + pytest.param( + ["progress 10%\r", "progress 20%\r", "done\n"], + "progress 10%\r\r\n\rprogress 20%\r\r\n\rdone\n", + id="a line ending in a carriage return is still unfinished", + ), + pytest.param(["one\n\r", "two\n"], "one\n\rtwo\n", id="a carriage return on an empty row leaves nothing unfinished"), + pytest.param( + ["x" * 200, "END\n"], + "x" * 200 + "\r\n" + "x" * 200 + "END\n", + id="a wrapped line is continued from the row it started on", + ), + pytest.param( + ["y" * 80, "Z\n"], + "y" * 80 + "\r\n" + "y" * 80 + "Z\n", + id="a line as wide as the screen has not wrapped yet", + ), + pytest.param( + ["漢" * 41, "END\n"], + "漢" * 41 + "\r\n" + "漢" * 41 + "END\n", + id="wide characters take two columns", + ), + pytest.param( + ["\x1b[31mred\x1b]8;;http://example.com\x07", " still\x1b[0m\n"], + "\x1b[31mred\x1b]8;;http://example.com\x07\r\n\x1b[31mred\x1b]8;;http://example.com\x07 still\x1b[0m\n", + id="escape sequences take no room and are written again", + ), + pytest.param( + ["z" * (24 * 80 + 1), "END\n"], + "z" * (24 * 80 + 1) + "\r\nEND\n", + id="a line longer than the screen stays ended", + ), + pytest.param( + ["z" * (23 * 80 + 1), "END\n"], + "z" * (23 * 80 + 1) + "\r\nEND\n", + id="a line which reaches the last row stays ended", + ), + pytest.param( + ["z" * (23 * 80), "END\n"], + "z" * (23 * 80) + "\r\n" + "z" * (23 * 80) + "END\n", + id="a line which stops above the last row is continued", + ), + ], +) +def test_stdout_proxy_continues_unfinished_lines(writes, expected) -> None: + """Output which stops in the middle of a line survives the toolbar being drawn below it.""" + stream = Terminal() + with create_pipe_input() as pipe, create_app_session(input=pipe, output=CursorOutput(stream)): + proxy = command_toolbar._ContextStdoutProxy() + try: + # No application is running, so each write reaches the output before the next. + for text in writes: + proxy._write_and_flush(None, text) + finally: + proxy.close() + + assert stream.getvalue() == expected + + +@pytest.mark.parametrize( + ("width", "expected"), + [ + pytest.param(22 * 80, "\r\n" + "z" * (22 * 80) + "END\n", id="continued while the toolbar fits below it"), + pytest.param(22 * 80 + 1, "\r\nEND\n", id="stays ended once the toolbar would scroll its first row off"), + ], +) +def test_stdout_proxy_leaves_room_for_every_row_of_the_toolbar(width, expected) -> None: + """A toolbar of several rows scrolls the screen sooner than one row does.""" + stream = Terminal() + with create_pipe_input() as pipe, create_app_session(input=pipe, output=CursorOutput(stream)): + proxy = command_toolbar._ContextStdoutProxy(lambda: 2) + try: + proxy._write_and_flush(None, "z" * width) + proxy._write_and_flush(None, "END\n") + finally: + proxy.close() + + assert stream.getvalue() == "z" * width + expected + + +def test_command_toolbar_tells_the_proxy_how_many_rows_it_takes(toolbar_app) -> None: + app, _, _ = toolbar_app + app.main_session.bottom_toolbar = "one\ntwo" + # Nothing has been drawn yet. + assert command_toolbar.CommandToolbar(app)._toolbar_rows() == 0 + with app._command_toolbar_context(): + assert app._command_toolbar._toolbar_rows() == 2 + assert app._command_toolbar._proxy._toolbar_rows() == 2 + + +class LegacyConsoleOutput(CursorOutput): + """Report a size the way prompt-toolkit's Windows outputs do, one column short of the console's. + + Like prompt-toolkit's Win32Output, which a legacy console gets, it has no vt100 output. + """ + + def __init__(self, stream: Terminal) -> None: + super().__init__(stream) + self.size = Size(rows=24, columns=79) + + def get_win32_screen_buffer_info(self) -> SimpleNamespace: + return SimpleNamespace(dwSize=SimpleNamespace(X=80, Y=24)) + + +class WindowsConsoleOutput(LegacyConsoleOutput): + """A console which understands escape sequences, as prompt-toolkit's Windows10_Output writes to.""" + + def __init__(self, stream: Terminal) -> None: + super().__init__(stream) + self.vt100_output = self + + +@pytest.mark.parametrize( + ("width", "rows"), + [ + pytest.param(80, 1, id="a line as wide as the console"), + pytest.param(159, 2, id="a line one column short of two rows"), + pytest.param(160, 2, id="a line which fills two rows"), + pytest.param(161, 3, id="a line which reaches a third row"), + ], +) +def test_stdout_proxy_counts_rows_by_the_width_a_windows_console_wraps_at(width, rows) -> None: + """A line which fills the last column of a Windows console is continued from its own row. + + prompt-toolkit reports such a console as one column narrower than the width it wraps at. + Counting rows by that size went up one row too many, and wrote over the line above. + """ + stream = Terminal() + with create_pipe_input() as pipe, create_app_session(input=pipe, output=WindowsConsoleOutput(stream)): + proxy = command_toolbar._ContextStdoutProxy() + try: + proxy._write_and_flush(None, "x" * width) + proxy._write_and_flush(None, "END\n") + finally: + proxy.close() + + assert stream.getvalue() == "x" * width + f"\r\n" + "x" * width + "END\n" + + +@pytest.mark.parametrize( + ("width", "rows"), + [ + pytest.param(79, 1, id="a line one column short of the console's width"), + pytest.param(80, 2, id="a line as wide as the console has already wrapped"), + pytest.param(81, 2, id="a line which reaches a second row"), + pytest.param(159, 2, id="a line one column short of two rows"), + pytest.param(160, 3, id="a line which fills two rows has already wrapped"), + ], +) +def test_stdout_proxy_counts_the_row_a_legacy_windows_console_has_wrapped_to(width, rows) -> None: + """A legacy console moves to the next row as soon as a row is full, not at the next character. + + Ending a line which exactly fills its rows therefore leaves the cursor a row lower than + on a terminal which waits. Going up one row too few wrote the line again a row below + itself, which showed its last row twice. + """ + stream = Terminal() + with create_pipe_input() as pipe, create_app_session(input=pipe, output=LegacyConsoleOutput(stream)): + proxy = command_toolbar._ContextStdoutProxy() + try: + proxy._write_and_flush(None, "x" * width) + proxy._write_and_flush(None, "END\n") + finally: + proxy.close() + + assert stream.getvalue() == "x" * width + f"\r\n" + "x" * width + "END\n" + + +@pytest.mark.parametrize("flushed", [True, False]) +def test_command_toolbar_keeps_an_unfinished_line(toolbar_app, flushed) -> None: + """An unfinished line is continued by later output, and ended when the toolbar stops.""" + app, _, output = toolbar_app + terminal = CursorOutput(output) + app.main_session.app.output = terminal + with app._command_toolbar_context(): + proxy = app._command_toolbar._proxy + app.stdout.write("Working...") + if flushed: + app.stdout.flush() + # Let the display print this much before any more is written. + deadline = time.monotonic() + 2 + while "Working..." not in output.getvalue() and time.monotonic() < deadline: + time.sleep(0.01) + app.stdout.write(" finished\n") + app.stdout.write("last line") + assert proxy.closed + + text = output.getvalue() + if flushed: + assert "Working...\r\n" in text + assert "Working... finished\n" in text + else: + assert "Working... finished\n" in text + # The prompt which follows starts on a row of its own. + assert "last line\r\n" in text + + +class CprOutput(RecordingOutput): + """A terminal that asks for cursor position reports and never answers them.""" + + def get_rows_below_cursor_position(self) -> int: + raise NotImplementedError + + @property + def responds_to_cpr(self) -> bool: + return True + + +def test_command_toolbar_flushes_writes_waiting_on_cursor_reports() -> None: + app = Cmd(allow_cli_args=False) + output = Terminal() + app.stdout = output + + with create_pipe_input() as pipe: + app.main_session = PromptSession( + input=pipe, + output=CprOutput(output), + bottom_toolbar="STATUS", + refresh_interval=0.01, + ) + # Terminal writes wait for a pending cursor position report, so stopping the + # display must not cancel them out from under the text. + with app._command_toolbar_context(): + app.poutput("last words") + + assert "last words\n" in output.getvalue() + + +def test_command_toolbar_remembers_the_rows_its_toolbar_took_before_it_is_drawn_again() -> None: + """A command's first output can arrive before the toolbar has been drawn for that command. + + Each run of the application forgets what it drew, and prompt-toolkit leaves the toolbar + out until the terminal has reported where its cursor is. Until then the toolbar counts + for the rows the main prompt drew it with, which are the rows it is about to take again. + """ + app = Cmd(allow_cli_args=False) + output = Terminal() + app.stdout = output + + with create_pipe_input() as pipe: + app.main_session = PromptSession( + input=pipe, + output=CprOutput(output), + bottom_toolbar="one\ntwo", + refresh_interval=0.01, + ) + window = app.main_session.layout.container.children[-1].content + # What the main prompt leaves behind after drawing a toolbar of two rows. + window.render_info = SimpleNamespace(window_height=2) + with app._command_toolbar_context(): + assert window.render_info is None + assert app._command_toolbar._toolbar_rows() == 2 + assert app._command_toolbar._proxy._toolbar_rows() == 2 + + +def test_command_toolbar_suspension_waits_for_in_flight_writes(toolbar_app) -> None: + app, _, output = toolbar_app + writing = threading.Event() + + with app._command_toolbar_context(): + proxy = app._command_toolbar._proxy + proxy_write = proxy.write + + def slow_write(data: str) -> int: + # Widen the window in which suspending could close this proxy. A closed + # proxy accepts writes and discards them, so the output would vanish. + writing.set() + time.sleep(0.1) + return proxy_write(data) + + proxy.write = slow_write + thread = threading.Thread(target=lambda: app.poutput("in flight")) + thread.start() + assert writing.wait(2) + + # A command reaches this at every finalization boundary while its own + # threads are still printing. + with app.suspend_bottom_toolbar(): + pass + thread.join() + + assert "in flight\n" in output.getvalue() + + +class TitleTerminal(Vt100_Output): + """A VT100 terminal which records the thread that wrote each window title.""" + + def __init__(self, stream: Terminal) -> None: + super().__init__(stream, lambda: Size(rows=24, columns=80), enable_cpr=False) + self.title_threads: dict[str, threading.Thread] = {} + self.title_written = threading.Event() + + def set_title(self, title: str) -> None: + self.title_threads[title] = threading.current_thread() + self.title_written.set() + super().set_title(title) + + +@pytest.fixture +def title_toolbar_app(): + # A real VT100 output, since window titles skip a DummyOutput in favor of the app's own stdout. + stream = Terminal() + with create_pipe_input() as pipe: + terminal = TitleTerminal(stream) + with create_app_session(input=pipe, output=terminal): + app = Cmd(allow_cli_args=False) + app.stdout = stream + app.main_session = PromptSession(input=pipe, output=terminal, bottom_toolbar="STATUS", refresh_interval=0.01) + yield app, terminal, stream + + +def test_command_toolbar_writes_window_titles_on_its_display_thread(title_toolbar_app) -> None: + app, terminal, stream = title_toolbar_app + with app._command_toolbar_context(): + display_thread = app._command_toolbar._thread + app.set_window_title("Working") + # Wait while the display is running, so its loop has the chance to write the title. + assert terminal.title_written.wait(2) + + # Written by the display, which renders the toolbar to the same terminal, rather than by the command. + assert terminal.title_threads["Working"] is display_thread + assert "\x1b]2;Working\x07" in stream.getvalue() + + +def test_command_toolbar_writes_a_queued_title_when_its_display_stops(title_toolbar_app, monkeypatch) -> None: + app, terminal, stream = title_toolbar_app + dropped = [] + with app._command_toolbar_context(): + loop = app._command_toolbar.app.loop + schedule = loop.call_soon_threadsafe + + # Simulate the display stopping before its loop runs the title callback. + def drop_title_callback(callback, *args, **kwargs): + if getattr(callback, "__func__", None) is Cmd._flush_pending_window_title_quietly: + dropped.append(callback) + return None + return schedule(callback, *args, **kwargs) + + monkeypatch.setattr(loop, "call_soon_threadsafe", drop_title_callback) + app.set_window_title("Queued") + assert "Queued" not in terminal.title_threads + + assert len(dropped) == 1 + # Stopping the display wrote the title once the display could no longer render. + assert terminal.title_threads["Queued"] is threading.main_thread() + assert stream.getvalue().endswith("\x1b]2;Queued\x07") + assert app._pending_window_title is None + assert app._window_title_callback_loop is None + + +def test_command_toolbar_typeahead(toolbar_app) -> None: + app, pipe, _ = toolbar_app + received = threading.Event() + with app._command_toolbar_context(): + toolbar = app._command_toolbar + + def key_processed(_): + if len(toolbar._keys) == len("next\n"): + received.set() + + toolbar.app.key_processor.after_key_press += key_processed + pipe.send_text("next\n") + assert received.wait(2) + + assert app._read_raw_input("Next: ", app.main_session) == "next" + + +def test_command_toolbar_typeahead_preserves_pending_input_order(toolbar_app) -> None: + app, pipe, _ = toolbar_app + exiting = threading.Event() + with app._command_toolbar_context(): + toolbar = app._command_toolbar + + def exit_after_first_key(_): + # Leave the remaining keys in prompt-toolkit's queue, as happens when + # input arrives just as a command finishes. + toolbar.app.exit() + exiting.set() + + toolbar.app.key_processor.after_key_press += exit_after_first_key + pipe.send_text("ab\n") + assert exiting.wait(2) + toolbar._thread.join(timeout=2) + assert not toolbar._thread.is_alive() + toolbar.app.key_processor.after_key_press -= exit_after_first_key + + assert app._read_raw_input("Next: ", app.main_session) == "ab" + + +@pytest.mark.parametrize("exception", [RuntimeError, KeyboardInterrupt, SystemExit]) +def test_command_toolbar_cleanup_on_exception(toolbar_app, exception) -> None: + app, _, output = toolbar_app + threads = [] + + def run_command(): + with app._command_toolbar_context(): + threads.append(app._command_toolbar._thread) + raise exception + + with pytest.raises(exception): + run_command() + assert len(threads) == 1 + assert not threads[0].is_alive() + assert app.stdout is output + assert app._command_toolbar is None + + +def test_command_toolbar_recovers_from_stop_failure(toolbar_app) -> None: + app, pipe, _ = toolbar_app + bindings = app.main_session.app.key_bindings + + context = app._command_toolbar_context() + context.__enter__() + toolbar = app._command_toolbar + real_stop = toolbar.stop + + def failing_stop() -> None: + # Tear down for real, then fail the way a broken stream close would. + real_stop() + raise RuntimeError("broken stop") + + toolbar.stop = failing_stop + with pytest.raises(RuntimeError, match="broken stop"): + context.__exit__(None, None, None) + + # A later command still gets a toolbar instead of being locked out by the dead one. + assert app._command_toolbar is None + assert app.main_session.app.layout is app.main_session.layout + assert app.main_session.app.key_bindings is bindings + with app._command_toolbar_context(): + assert app._command_toolbar is not None + assert app._command_toolbar is not toolbar + assert app._command_toolbar is None + assert app._read_raw_input("Next: ", app.main_session, pre_run=lambda: pipe.send_text("recovered\n")) == "recovered" + + +def test_command_toolbar_exit_after_result_is_set(toolbar_app) -> None: + app, _, _ = toolbar_app + exited_twice = threading.Event() + with app._command_toolbar_context(): + toolbar = app._command_toolbar + + def already_exiting(): + toolbar.app.exit() + # The result is set before run_async() has finished its cleanup. + assert toolbar.app.is_running + toolbar._exit() + exited_twice.set() + + toolbar.app.loop.call_soon_threadsafe(already_exiting) + assert exited_twice.wait(2) + assert app.main_session.app.layout is app.main_session.layout + + +def test_command_toolbar_failure_after_startup_is_reported(toolbar_app, capsys) -> None: + app, _, output = toolbar_app + + with app._command_toolbar_context(): + toolbar = app._command_toolbar + # Stop the display the way an unhandled error in its own thread would, after + # _resume() has already returned and can no longer raise for the command. + toolbar.app.loop.call_soon_threadsafe(lambda: toolbar.app.exit(exception=ValueError("broken display"))) + toolbar._thread.join(timeout=2) + assert not toolbar._thread.is_alive() + + # Output must still reach the terminal rather than a proxy nothing is draining. + assert all(stream.proxy is None for stream in toolbar._streams) + app.poutput("after failure") + + assert "broken display" in capsys.readouterr().err + assert "after failure\n" in output.getvalue() + + +def test_command_toolbar_stops_once_after_a_callback_error(toolbar_app, capsys) -> None: + """An error from the toolbar callback ends the display instead of being logged at every redraw.""" + app, _, output = toolbar_app + broken = threading.Event() + failures = [] + + def toolbar(): + if broken.is_set(): + failures.append(None) + raise ValueError("broken toolbar") + return "STATUS" + + app.main_session.bottom_toolbar = toolbar + with app._command_toolbar_context(): + display = app._command_toolbar + thread = display._thread + broken.set() + thread.join(timeout=2) + assert not thread.is_alive() + + # Output must still reach the terminal rather than a proxy nothing is draining. + assert all(stream.proxy is None for stream in display._streams) + app.poutput("after failure") + + # A display which failed is not restarted, so a later pause neither calls the + # callback again nor repeats the report. + seen = len(failures) + with app.suspend_bottom_toolbar(): + pass + assert display._thread is None + assert not display.is_active + assert len(failures) == seen + + err = capsys.readouterr().err + assert err.count("Bottom toolbar stopped after an error") == 1 + assert "broken toolbar" in err + assert "Traceback" not in err + assert "after failure\n" in output.getvalue() + assert app.main_session.app.layout is app.main_session.layout + + # The next command starts a display of its own. + broken.clear() + with app._command_toolbar_context(): + assert app._command_toolbar.is_active + + +def test_command_toolbar_reports_the_error_which_stopped_it(toolbar_app, capsys) -> None: + """Stopping draws a last frame. A failure there must not replace the error which caused the stop.""" + app, _, _ = toolbar_app + frames = [] + + def fail(ui): + frames.append(None) + raise ValueError(f"error {len(frames)}") + + with app._command_toolbar_context(): + display = app._command_toolbar + thread = display._thread + display.app.after_render += fail + try: + thread.join(timeout=2) + assert not thread.is_alive() + finally: + display.app.after_render -= fail + + err = capsys.readouterr().err + assert len(frames) == 2 + assert "ValueError('error 1')" in err + assert "error 2" not in err + + +def test_command_toolbar_reports_a_loop_error_without_an_exception(toolbar_app, capsys) -> None: + app, _, _ = toolbar_app + with app._command_toolbar_context(): + display = app._command_toolbar + thread = display._thread + loop = display.app.loop + loop.call_soon_threadsafe(loop.call_exception_handler, {"message": "loop misbehaved"}) + thread.join(timeout=2) + assert not thread.is_alive() + + assert "loop misbehaved" in capsys.readouterr().err + + +def test_command_toolbar_failing_to_resume_does_not_fail_the_command(toolbar_app, capsys) -> None: + """A display which cannot come back after a pause is reported, not raised into the command.""" + app, _, output = toolbar_app + broken = threading.Event() + + def toolbar(): + if broken.is_set(): + raise ValueError("broken toolbar") + return "STATUS" + + app.main_session.bottom_toolbar = toolbar + with app._command_toolbar_context(): + display = app._command_toolbar + with app.suspend_bottom_toolbar(): + broken.set() + assert not display.is_active + app.poutput("after failure") + + # Command finalization pauses the display as well, at the end of every command. + assert app._run_cmdfinalization_hooks(False, None) is False + + err = capsys.readouterr().err + assert err.count("Bottom toolbar stopped after an error") == 1 + assert "broken toolbar" in err + assert "after failure\n" in output.getvalue() + assert app.main_session.app.layout is app.main_session.layout + assert app.stdout is output + assert app._command_toolbar is None + + +def test_command_toolbar_input_eof_is_not_reported(toolbar_app, capsys) -> None: + app, pipe, output = toolbar_app + + with app._command_toolbar_context(): + toolbar = app._command_toolbar + # Losing the terminal's input ends the display with EOFError. That is an + # ordinary shutdown, not a failure the running command should hear about. + pipe.close() + toolbar._thread.join(timeout=2) + assert not toolbar._thread.is_alive() + assert toolbar._error is None + + # Output must still reach the terminal rather than a proxy nothing is draining. + assert all(stream.proxy is None for stream in toolbar._streams) + app.poutput("after eof") + + assert capsys.readouterr().err == "" + assert "after eof\n" in output.getvalue() + assert app.stdout is output + assert app._command_toolbar is None + + +def test_command_toolbar_startup_failure_still_runs_the_command(toolbar_app, capsys) -> None: + app, _, output = toolbar_app + + def broken_toolbar(): + raise ValueError("broken toolbar") + + app.main_session.bottom_toolbar = broken_toolbar + ran = [] + # The toolbar is cosmetic. A display that cannot start must not take the command + # with it, and must not escape cmdloop() and leave signal handlers installed. + with app._command_toolbar_context(): + ran.append(True) + app.poutput("command output") + + assert ran == [True] + assert "broken toolbar" in capsys.readouterr().err + assert "command output\n" in output.getvalue() + assert app.stdout is output + assert app._command_toolbar is None + + +def test_command_toolbar_is_not_retried_after_a_startup_failure(toolbar_app, capsys) -> None: + app, _, _ = toolbar_app + + def broken_toolbar(): + raise ValueError("broken toolbar") + + app.main_session.bottom_toolbar = broken_toolbar + with app._command_toolbar_context(): + pass + assert "broken toolbar" in capsys.readouterr().err + + # Without this, every later command repeats the same failure and the same message. + app.main_session.bottom_toolbar = "STATUS" + with mock.patch("cmd2.command_toolbar.CommandToolbar") as toolbar, app._command_toolbar_context(): + toolbar.assert_not_called() + assert capsys.readouterr().err == "" + + +def test_cmdloop_restores_signal_handlers_when_the_loop_fails(toolbar_app, monkeypatch) -> None: + import signal + + app, _, _ = toolbar_app + original = signal.getsignal(signal.SIGINT) + monkeypatch.setattr(app, "_cmdloop", mock.Mock(side_effect=RuntimeError("loop failed"))) + + with pytest.raises(RuntimeError, match="loop failed"): + app.cmdloop() + + # cmd2's handlers must not outlive the loop in the host process. + assert signal.getsignal(signal.SIGINT) is original + + +@pytest.mark.parametrize("enabled", [False, True]) +def test_command_toolbar_headless(enabled) -> None: + app = Cmd(allow_cli_args=False, enable_bottom_toolbar=enabled) + with mock.patch("cmd2.command_toolbar.CommandToolbar") as toolbar, app._command_toolbar_context(): + toolbar.assert_not_called() + + +def test_cmdloop_runs_commands_with_toolbar(toolbar_app, monkeypatch) -> None: + app, _, _ = toolbar_app + monkeypatch.setattr(app, "_read_command_line", lambda _: "quit") + commands = [] + + def command(line, **kwargs): + assert threading.current_thread() is threading.main_thread() + assert app._command_toolbar.app.is_running + commands.append(line) + return line == "quit" + + app._startup_commands = ["startup"] + monkeypatch.setattr(app, "onecmd_plus_hooks", command) + app._cmdloop() + assert commands == ["startup", "quit"] + + +@pytest.mark.parametrize( + ("layout", "message"), + [ + (Layout(Window()), "Unsupported PromptSession layout"), + (Layout(HSplit([Window()])), "Cannot locate PromptSession bottom toolbar"), + ], +) +def test_command_toolbar_requires_the_prompt_toolbar(toolbar_app, capsys, layout, message) -> None: + app, _, output = toolbar_app + # The display reuses the prompt's own toolbar container. If a future prompt-toolkit + # release moves it, say so and keep running without a toolbar. + with mock.patch.object(app.main_session, "layout", layout), app._command_toolbar_context(): + app.poutput("command output") + assert message in capsys.readouterr().err + assert app._command_toolbar is None + assert "command output\n" in output.getvalue() + assert app.stdout is output + + +def test_command_toolbar_reuses_prompt_application(toolbar_app) -> None: + app, pipe, _ = toolbar_app + session = app.main_session + layout, bindings, erase = session.app.layout, session.app.key_bindings, session.app.erase_when_done + with app._command_toolbar_context(): + toolbar = app._command_toolbar + assert toolbar.app is session.app + assert toolbar.toolbar is session.layout.container.children[-1] + with app.suspend_bottom_toolbar(): + assert session.app.layout is layout + assert session.app.key_bindings is bindings + assert session.app.erase_when_done is erase + assert session.app.layout is toolbar._layout + assert session.app.layout is layout + assert session.app.key_bindings is bindings + assert session.app.erase_when_done is erase + assert app._read_raw_input("Next: ", session, pre_run=lambda: pipe.send_text("answer\n")) == "answer" + + +def test_external_pager_suspends_shared_application(toolbar_app, monkeypatch) -> None: + app, _, _ = toolbar_app + monkeypatch.setattr(app, "stdin", Terminal()) + monkeypatch.setenv("TERM", "xterm") + + def external(*args, **kwargs): + assert not app.main_session.app.is_running + assert app.main_session.app.layout is app.main_session.layout + return mock.Mock() + + with mock.patch("subprocess.Popen", side_effect=external), app._command_toolbar_context(): + app.ppaged("external pager") + assert app._command_toolbar.is_active diff --git a/tests/test_pipeline_job_control.py b/tests/test_pipeline_job_control.py index fa9ab6868..0cf69d562 100644 --- a/tests/test_pipeline_job_control.py +++ b/tests/test_pipeline_job_control.py @@ -511,6 +511,130 @@ def wait_until(predicate): process.wait(timeout=5) +def suspend_and_resume(tmp_path, command_source, command, waiting, finish) -> None: + """Start a command under an interactive bash, stop it with Ctrl-Z, resume it with fg, and let it finish. + + The display thread sends the stop signal, which the kernel may hand to the main + thread. Unless the sending thread stops synchronously too, it restores raw mode + before the job has stopped, the shell puts its own modes back on fg, and every + cursor-position query afterwards is echoed as ^[[row;colR. + + :param command_source: source of the application's ``do_`` method for the command + :param command: the command to type + :param waiting: returns whether the screen it is given shows the command waiting + :param finish: given ``send``, makes the waiting command finish + """ + import fcntl + import pty + import struct + import termios + + shell = shutil.which("bash") + if shell is None: + pytest.skip("requires an interactive bash shell") + application = tmp_path / "application.py" + application.write_text( + "from cmd2 import Cmd\n" + "class App(Cmd):\n" + f"{command_source}" + # A refreshing toolbar, as in the examples: its periodic redraws are what turn a cooked terminal into a stream of echoed + # cursor reports. + "app = App(enable_bottom_toolbar=True, refresh_interval=0.5)\n" + "app.prompt = 'TEST> '\n" + "app.main_session.bottom_toolbar = 'STATUS'\n" + "app.cmdloop()\n", + encoding="utf-8", + ) + master, slave = pty.openpty() + fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", 24, 80, 0, 0)) + bootstrap = ( + "import os, fcntl, termios; os.setsid(); " + "fcntl.ioctl(0, termios.TIOCSCTTY, 0); " + "os.execv(os.environ['TEST_SHELL'], ['bash', '--noprofile', '--norc', '-i'])" + ) + env = dict(os.environ, TERM="xterm-256color", PS1="OUTER> ", TEST_SHELL=shell, SHELL=shell) + env["PYTHONPATH"] = str(Path(__file__).resolve().parents[1]) + process = subprocess.Popen([sys.executable, "-c", bootstrap], stdin=slave, stdout=slave, stderr=slave, env=env) + os.close(slave) + screen = pyte.Screen(80, 24) + screen.write_process_input = lambda data: os.write(master, data.encode()) + stream = pyte.Stream(screen) + decoder = codecs.getincrementaldecoder("utf-8")("replace") + transcript = "" + + def send(data): + os.write(master, data.encode()) + + def pump(seconds, predicate=lambda: False): + nonlocal transcript + deadline = time.monotonic() + seconds + while time.monotonic() < deadline: + if select.select([master], [], [], 0.05)[0]: + data = decoder.decode(os.read(master, 65536)) + transcript += data + stream.feed(data) + if predicate(): + return True + return predicate() + + def command_waiting(): + return waiting(screen) + + try: + assert pump(10, lambda: "OUTER> " in transcript) + send(f"{shlex.quote(sys.executable)} {shlex.quote(str(application))}\n") + assert pump(10, lambda: "TEST>" in "\n".join(screen.display)), transcript + # Let the prompt finish its cursor-position handshake before typing at it. + pump(0.5) + send(f"{command}\n") + assert pump(10, command_waiting), transcript + start = len(transcript) + send("\x1a") + assert pump(10, lambda: "OUTER> " in transcript[start:]), transcript + start = len(transcript) + send("fg\n") + assert pump(10, command_waiting), transcript[start:] + # Give a broken resume time to start looping before judging the transcript. + pump(1.5) + resumed = transcript[start:] + echoed = re.findall(r"\^\[\[\d+;\d+R", resumed) + assert not echoed, f"cursor position reports were echoed after fg: {echoed[:5]}\n{resumed}" + assert command_waiting(), "\n".join(screen.display) + start = len(transcript) + finish(send) + assert pump(10, lambda: "TEST>" in transcript[start:]), f"the command did not finish after fg:\n{transcript[start:]}" + send("quit\n") + pump(5, lambda: os.tcgetpgrp(master) == process.pid) + finally: + os.close(master) + process.kill() + process.wait(timeout=5) + + +def test_command_resumes_with_raw_terminal_after_suspend(tmp_path) -> None: + """Ctrl-Z while a command runs under the toolbar, then fg, must leave the terminal raw. + + The command keeps printing, and the display asks the terminal where its cursor is as it + puts each line above the toolbar. A terminal left cooked would echo every answer. + """ + release = tmp_path / "release" + + def printing(screen): + return any(line.startswith("waiting") for line in screen.display) + + suspend_and_resume( + tmp_path, + " def do_wait(self, statement):\n" + " import os, time\n" + f" while not os.path.exists({str(release)!r}):\n" + " self.poutput('waiting')\n" + " time.sleep(0.2)\n", + "wait", + printing, + lambda send: release.touch(), + ) + + @pytest.mark.parametrize("parent_delay", [False, True]) def test_pipeline_pager_can_set_terminal_modes_at_startup(tmp_path, parent_delay) -> None: """A pager such as less puts the terminal in raw mode as it starts, before reading its pipe.