diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 5adb6ba6a..b62929a1c 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -111,6 +111,7 @@ argparse_utils, constants, plugin, + textual_toolbar, utils, ) from . import rich_utils as ru @@ -843,7 +844,8 @@ def _create_main_session( # Base configuration kwargs: dict[str, Any] = { "auto_suggest": AutoSuggestFromHistory() if auto_suggest else None, - "bottom_toolbar": self.get_bottom_toolbar if enable_bottom_toolbar else None, + # PROTOTYPE: inside a Textual host, the host draws the toolbar. See textual_toolbar.py. + "bottom_toolbar": self.get_bottom_toolbar if enable_bottom_toolbar and not textual_toolbar.is_hosted() else None, "color_depth": pt_resolve_color_depth(), "complete_style": CompleteStyle.MULTI_COLUMN, "complete_in_thread": complete_in_thread, diff --git a/cmd2/textual_toolbar.py b/cmd2/textual_toolbar.py new file mode 100644 index 000000000..62bfc7433 --- /dev/null +++ b/cmd2/textual_toolbar.py @@ -0,0 +1,511 @@ +"""PROTOTYPE: a bottom toolbar drawn by Textual instead of prompt-toolkit. + +A third way to keep the bottom toolbar on the screen while a command runs. The other two have +prompt-toolkit draw it, in a terminal which cmd2 is also writing command output to. Here cmd2 +does not draw the toolbar at all: + +- A small Textual application, the *host*, owns the real terminal. It shows a terminal emulator + (the ``Terminal`` widget of textual-tty) with a one-widget toolbar docked below it. +- The cmd2 application runs as a child process inside that emulator, exactly as it would in + any terminal. It is the same program run again, with an environment variable to tell it so. +- The child sends the content of ``Cmd.get_bottom_toolbar()`` to the host over a Unix socket, + from a thread, so it keeps coming while a command has the main thread. + +Since the emulator and the toolbar are different widgets, command output cannot reach the +toolbar's rows, and Textual redraws only what changed. + +The host's terminal is not the user's: the session is on the alternate screen, so none of it +reaches the real terminal's scrollback. The emulator widget keeps a scrollback of its own +instead (see :func:`scrollback_terminal_class`), looked at with the mouse wheel, or with Shift +and Page Up, Page Down, Home or End where the real terminal passes those keys on. + +Use :func:`run` in place of ``sys.exit(MyApp().cmdloop())``:: + + if __name__ == "__main__": + sys.exit(cmd2.textual_toolbar.run(MyApp)) + +Neither textual nor textual-tty is a dependency of cmd2. Without them, on Windows, or when +stdin or stdout is not a terminal, :func:`run` runs the application as it always did. +""" + +import contextlib +import importlib.util +import io +import json +import os +import re +import shutil +import socket +import sys +import tempfile +import threading +from collections.abc import Callable +from typing import TYPE_CHECKING, Any, Self + +from prompt_toolkit.data_structures import Size +from prompt_toolkit.formatted_text import AnyFormattedText, to_formatted_text +from prompt_toolkit.output import ColorDepth +from prompt_toolkit.output.vt100 import Vt100_Output +from prompt_toolkit.renderer import print_formatted_text +from prompt_toolkit.styles import DynamicStyle, default_ui_style, merge_styles + +from .plugin import CommandFinalizationData, PostparsingData +from .theme import get_pt_theme + +if TYPE_CHECKING: # pragma: no cover + from .cmd2 import Cmd + +#: Set in the environment of a cmd2 application which a host is running, to the path of the +#: Unix socket the host listens on for its toolbar. +HOST_SOCKET_ENV = "CMD2_TEXTUAL_TOOLBAR" + +#: Control sequences other than "select graphic rendition", which is how a style is written. +_NOT_A_STYLE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-ln-~]") + +#: How often the toolbar's content is looked at when the application has no refresh interval. +DEFAULT_INTERVAL = 0.5 + + +def is_hosted() -> bool: + """Return whether this process is a cmd2 application running inside a Textual host.""" + return bool(os.environ.get(HOST_SOCKET_ENV)) + + +def can_host() -> bool: + """Return whether a Textual host can be started here for this program.""" + return ( + sys.platform != "win32" + and sys.stdin.isatty() + and sys.stdout.isatty() + and importlib.util.find_spec("textual") is not None + and importlib.util.find_spec("textual_tty") is not None + ) + + +def render_ansi(content: AnyFormattedText) -> str: + """Render a toolbar's content as text with ANSI style sequences, for the host to draw. + + prompt-toolkit does the rendering, so anything ``get_bottom_toolbar()`` may return is + understood, and style classes mean what cmd2's theme says they mean. + + :param content: what ``get_bottom_toolbar()`` returned + :return: the text, with a newline between rows + """ + stream = io.StringIO() + output = Vt100_Output( + stream, + lambda: Size(rows=1, columns=10_000), + term="xterm-256color", + default_color_depth=ColorDepth.TRUE_COLOR, + enable_bell=False, + enable_cpr=False, + ) + # The theme over prompt-toolkit's default style, as an application has them: is only + # bold because the default style says so. + style = merge_styles([default_ui_style(), DynamicStyle(get_pt_theme)]) + print_formatted_text(output, to_formatted_text(content), style, color_depth=ColorDepth.TRUE_COLOR) + # Only the styles are the host's business, not what else the renderer sets up around them. + return _NOT_A_STYLE.sub("", stream.getvalue()).replace("\r\n", "\n") + + +class ToolbarReporter: + """Sends a toolbar's content to the host whenever it changes. + + Runs in the cmd2 application, on a thread of its own, so the toolbar goes on being + refreshed while a command is running. + """ + + def __init__( + self, get_toolbar: Callable[[], AnyFormattedText], interval: float = DEFAULT_INTERVAL, path: str | None = None + ) -> None: + """Prepare to report a toolbar. + + :param get_toolbar: returns the toolbar's content, as ``Cmd.get_bottom_toolbar()`` does + :param interval: seconds between looks at the content + :param path: the host's socket, which is otherwise found in the environment + """ + self._get_toolbar = get_toolbar + self._path = path + self._interval = interval if interval > 0 else DEFAULT_INTERVAL + self._socket: socket.socket | None = None + self._thread: threading.Thread | None = None + self._wake = threading.Event() + self._stopping = False + self._last: str | None = None + + def start(self) -> None: + """Connect to the host and start reporting.""" + connection = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + connection.connect(self._path or os.environ[HOST_SOCKET_ENV]) + self._socket = connection + self._report() + self._thread = threading.Thread(target=self._run, name="cmd2-textual-toolbar", daemon=True) + self._thread.start() + + def poke(self) -> None: + """Look at the content now, without waiting for the interval: something has changed.""" + self._wake.set() + + def stop(self) -> None: + """Stop reporting and close the connection.""" + self._stopping = True + self._wake.set() + if self._thread is not None: + self._thread.join(timeout=2) + self._thread = None + if self._socket is not None: + self._socket.close() + self._socket = None + + def __enter__(self) -> Self: + """Start reporting.""" + self.start() + return self + + def __exit__(self, *_: object) -> None: + """Stop reporting.""" + self.stop() + + def _run(self) -> None: + while not self._stopping: + self._wake.wait(self._interval) + self._wake.clear() + if self._stopping or not self._report(): + return + + def _report(self) -> bool: + """Send the content if it has changed. + + :return: whether the host is still there + """ + try: + rendered = render_ansi(self._get_toolbar()) + except Exception: # noqa: BLE001 - a toolbar callback must not end the application + # The last good content stays on the screen. + return True + if rendered == self._last or self._socket is None: + return True + try: + self._socket.sendall(json.dumps({"toolbar": rendered}).encode() + b"\n") + except OSError: + return False + self._last = rendered + return True + + +def run(app_factory: Callable[[], "Cmd"]) -> int: + """Run a cmd2 application with its bottom toolbar drawn by a Textual host. + + Called first by the program the user started. That one starts the host, which runs the same + program again inside itself, and there this function creates the application and runs its + command loop. So the application is only ever created in the process which uses it. + + :param app_factory: creates the cmd2 application, usually its class + :return: the application's exit code + """ + if not is_hosted(): + if not can_host(): + return app_factory().cmdloop() + return run_host([sys.executable, *sys.orig_argv[1:]]) + + app = app_factory() + # The application has been built knowing it is hosted. Programs it runs are not: one of + # them could be another cmd2 application, and would take this one's toolbar. + path = os.environ.pop(HOST_SOCKET_ENV) + reporter = ToolbarReporter(app.get_bottom_toolbar, getattr(app.main_session, "refresh_interval", 0) or 0, path) + + # A command starting or ending is when a toolbar most often changes. Don't wait for it. + def command_started(data: PostparsingData) -> PostparsingData: + reporter.poke() + return data + + def command_finished(data: CommandFinalizationData) -> CommandFinalizationData: + reporter.poke() + return data + + app.register_postparsing_hook(command_started) + app.register_cmdfinalization_hook(command_finished) + with reporter: + return app.cmdloop() + + +def run_host(command: list[str]) -> int: + """Run a program in a terminal emulator with a toolbar below it, until the program exits. + + :param command: the program and its arguments + :return: the program's exit code + """ + directory = tempfile.mkdtemp(prefix="cmd2-toolbar-") + path = os.path.join(directory, "toolbar.sock") + listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + try: + # Listening before the program is started, so its connection is never refused. + listener.bind(path) + listener.listen(1) + # The emulator copies the environment when it is first imported, so this comes first. + os.environ[HOST_SOCKET_ENV] = path + try: + app = build_host_app(command, listener) + app.run() + return int(app.program_exit_code) + finally: + del os.environ[HOST_SOCKET_ENV] + finally: + listener.close() + shutil.rmtree(directory, ignore_errors=True) + + +def _host_import(module: str) -> Any: + """Import a module which only a host needs. + + Not an import statement, so that the type checkers do not need Textual to check this module: + it is not a dependency of cmd2, and what comes from it is treated as untyped. + """ + return importlib.import_module(module) + + +#: How many rows which have scrolled off the top of the program's screen are kept. +SCROLLBACK_ROWS = 10_000 + +#: Rows the mouse wheel moves the view by. +WHEEL_ROWS = 3 + + +def scrollback_terminal_class() -> Any: + """Build a terminal widget which keeps the rows that scroll off the top of its screen. + + textual-tty's ``Terminal`` shows a screen and nothing else: a row which scrolls off the top + is gone. This adds what a terminal emulator calls scrollback. The emulator scrolls in one + place, so that is where the rows leaving the top of the primary screen are kept, and the + widget draws from them when the view has been moved back with the mouse wheel or with + Shift and Page Up. The program's own screen is never changed by looking back. + + Built on request because textual-tty is only imported when a host is started. + """ + from collections import deque + + from rich.segment import Segment + + Message: Any = _host_import("textual.message").Message # noqa: N806 + Strip: Any = _host_import("textual.strip").Strip # noqa: N806 + Terminal: Any = _host_import("textual_tty").Terminal # noqa: N806 + + class ScrollbackTerminal(Terminal): # type: ignore[misc] + """A terminal emulator widget with scrollback.""" + + class Scrolled(Message): # type: ignore[misc] + """The view moved: how many rows back it is, of how many kept.""" + + def __init__(self, back: int, kept: int) -> None: + self.back = back + self.kept = kept + super().__init__() + + def __init__(self, *args: Any, **kwargs: Any) -> None: + super().__init__(*args, **kwargs) + self.scrollback: deque[list[Any]] = deque(maxlen=SCROLLBACK_ROWS) + self.back = 0 + blitter = self.board.blitter + scroll = blitter.scroll + + def scroll_keeping_rows(lines: int) -> None: + # Rows leave the top for good only when the whole width scrolls up from the first + # row, on the primary screen. A region lower down, or a full-screen program on + # the alternate screen, scrolls within itself. + if ( + lines > 0 + and blitter.scroll_top == 0 + and not blitter.in_alt_screen + and blitter.left_margin == 0 + and blitter.right_margin == self.board.width - 1 + ): + self._keep(blitter.current_buffer.grid[: min(lines, blitter.scroll_bottom + 1)]) + scroll(lines) + + blitter.scroll = scroll_keeping_rows + + def _keep(self, rows: list[list[Any]]) -> None: + """Take rows which are about to leave the top of the screen.""" + dropped = max(0, len(self.scrollback) + len(rows) - SCROLLBACK_ROWS) + self.scrollback.extend(rows) + if self.back: + # Someone is reading: keep the same rows in view while output goes on below. + self.back = max(0, min(self.back + len(rows) - dropped, len(self.scrollback))) + self.post_message(self.Scrolled(self.back, len(self.scrollback))) + + def look(self, rows: int) -> None: + """Move the view back by that many rows, or forward if negative.""" + back = max(0, min(self.back + rows, len(self.scrollback))) + if back != self.back: + self.back = back + self.refresh() + self.post_message(self.Scrolled(back, len(self.scrollback))) + + # --- drawing --- # + + def render_line(self, y: int) -> Any: + if not self.back: + return super().render_line(y) + # The view is a window on the kept rows followed by the screen's own. + row = len(self.scrollback) - self.back + y + if row >= len(self.scrollback): + return super().render_line(row - len(self.scrollback)) + width = self.size.width + segments = [] + run: list[str] = [] + run_style = None + for style, char in self.scrollback[row][:width]: + if style is not run_style and style != run_style: + if run: + segments.append(Segment("".join(run), self._to_rich(run_style))) + run = [] + run_style = style + run.append(char) + if run: + segments.append(Segment("".join(run), self._to_rich(run_style))) + return Strip(segments).adjust_cell_length(width) + + def _tick(self) -> None: + # The widget repaints the rows of the screen which changed, by their place on the + # screen. Looking back, they are somewhere else, so everything is repainted. + changed = self._dirty and not self._sync + super()._tick() + if changed and self.back: + self.refresh() + + def _cursor_shown(self) -> bool: + return not self.back and bool(super()._cursor_shown()) + + # --- sizing --- # + + def on_resize(self, event: Any) -> None: + height = event.size.height + blitter = self.board.blitter + below = self.board.cursor.y - (height - 1) + if height and below > 0 and not blitter.in_alt_screen: + # The emulator cuts a shorter screen off at the bottom. A terminal keeps the + # cursor's row on it instead, and the rows above go to its scrollback. + page = blitter.current_buffer + self._keep(page.grid[:below]) + page.scroll_up(below) + self.board.cursor.y -= below + super().on_resize(event) + + # --- input --- # + + def on_key(self, event: Any) -> None: + page = max(1, self.size.height - 1) + moves = { + "shift+pageup": page, + "shift+pagedown": -page, + "shift+home": len(self.scrollback), + "shift+end": -self.back, + } + if event.key in moves: + self.look(moves[event.key]) + event.stop() + event.prevent_default() + return + # Anything typed is for the program, which is at the bottom. + self.look(-self.back) + super().on_key(event) + + def _wheel(self, event: Any, button: int, arrow: str) -> None: + if self.mouse_mode != "off" or self.board.blitter.in_alt_screen: + # The program wants the wheel itself, or is full-screen and has no rows above. + super()._wheel(event, button, arrow) + return + self.look(WHEEL_ROWS if arrow == "up" else -WHEEL_ROWS) + event.stop() + + return ScrollbackTerminal + + +def build_host_app(command: list[str], listener: socket.socket) -> Any: + """Build the Textual application which hosts a program. Textual is only imported here. + + :param command: the program and its arguments + :param listener: a listening Unix socket, whose path the program has in its environment + :return: the application, whose ``program_exit_code`` is the program's once it has run + """ + import asyncio + + from rich.text import Text + + App: Any = _host_import("textual.app").App # noqa: N806 + Message: Any = _host_import("textual.message").Message # noqa: N806 + Static: Any = _host_import("textual.widgets").Static # noqa: N806 + Terminal: Any = scrollback_terminal_class() # noqa: N806 + + class ToolbarChanged(Message): # type: ignore[misc] + """The program has new content for its toolbar.""" + + def __init__(self, rendered: str) -> None: + self.rendered = rendered + super().__init__() + + class ToolbarHost(App[None]): # type: ignore[misc] + """A terminal emulator running the program, and its toolbar.""" + + CSS = """ + #program { + height: 1fr; + } + #toolbar { + dock: bottom; + height: auto; + min-height: 1; + background: $foreground; + color: $background; + } + """ + ENABLE_COMMAND_PALETTE = False + + def __init__(self) -> None: + super().__init__() + self.program_exit_code = 0 + self._server: asyncio.Server | None = None + self._toolbar = Text() + self._looking_back = "" + + def compose(self) -> Any: + yield Terminal(command=command, id="program") + yield Static("", id="toolbar") + + async def on_mount(self) -> None: + self._server = await asyncio.start_unix_server(self._toolbar_connection, sock=listener) + self.query_one(Terminal).focus() + + async def on_unmount(self) -> None: + if self._server is not None: + self._server.close() + + async def _toolbar_connection(self, reader: asyncio.StreamReader, _writer: asyncio.StreamWriter) -> None: + """Read toolbar content from the program, one JSON document to a line.""" + while line := await reader.readline(): + with contextlib.suppress(ValueError, TypeError): + document = json.loads(line) + if isinstance(document, dict) and isinstance(document.get("toolbar"), str): + self.post_message(ToolbarChanged(document["toolbar"])) + + def on_toolbar_changed(self, message: ToolbarChanged) -> None: + self._toolbar = Text.from_ansi(message.rendered) + self._show_toolbar() + + def on_scrollback_terminal_scrolled(self, message: Any) -> None: + """Say so when the view is not at the bottom, since the prompt is then out of sight.""" + self._looking_back = f" [{message.back} of {message.kept} rows back]" if message.back else "" + self._show_toolbar() + + def _show_toolbar(self) -> None: + toolbar = self._toolbar.copy() + toolbar.append(self._looking_back, style="bold") + self.query_one("#toolbar", Static).update(toolbar) + + def on_terminal_process_exited(self, event: Any) -> None: + code = event.exit_code + # A process killed by a signal has the negated signal number. Shells say 128 + signal. + self.program_exit_code = 128 - code if code < 0 else code + self.exit() + + return ToolbarHost() diff --git a/examples/README.md b/examples/README.md index 955e8cbd4..6338dedfe 100644 --- a/examples/README.md +++ b/examples/README.md @@ -95,6 +95,9 @@ each: - Example of using Rich Tables within a cmd2 application for displaying tabular data - [rich_theme.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_theme.py) - Demonstrates how to create a custom theme for a cmd2 application +- [textual_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_toolbar.py) + - PROTOTYPE: a bottom toolbar which stays on the screen while commands run, drawn by a small + Textual application which runs the cmd2 application inside a terminal emulator widget - [textual_tty_embed.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_embed.py) - Shows how to embed a `cmd2` application in a [Textual](https://textual.textualize.io/) application using [textual-tty](https://github.com/ttygroup/textual-tty), with a realtime diff --git a/examples/textual_toolbar.py b/examples/textual_toolbar.py new file mode 100755 index 000000000..10ed95ec9 --- /dev/null +++ b/examples/textual_toolbar.py @@ -0,0 +1,99 @@ +#!/usr/bin/env python3 +"""PROTOTYPE: a bottom toolbar which stays on the screen while commands run, drawn by Textual. + +The toolbar is not drawn by prompt-toolkit, or by cmd2 at all. ``cmd2.textual_toolbar.run()`` starts a +small Textual application which owns the terminal, and runs this program again inside a terminal +emulator widget, with a toolbar widget below it. This program sends the toolbar's content to it. +See ``cmd2/textual_toolbar.py`` for how. + +Neither textual nor textual-tty are dependencies of cmd2. In a cmd2 checkout, textual-tty is part of the +development environment on POSIX systems, so run this example with: + + uv run examples/textual_toolbar.py + +Things to try: ``slow``, ``burst 2000 1``, ``page 500``, ``ask``, resizing the window while a command +runs, Ctrl-C during ``slow``, and ``quit``. After ``burst 500``, look back at what scrolled away with the +mouse wheel, or with Shift and Page Up if your terminal passes that on; typing returns to the bottom. Pass +``--plain`` to run the same application without Textual, where prompt-toolkit draws the toolbar and it is +only there at the prompt. +""" + +import os +import sys +import time + +import cmd2 +from cmd2 import textual_toolbar + + +class ToolbarDemo(cmd2.Cmd): + """A cmd2 application with a toolbar which says what it is doing.""" + + def __init__(self) -> None: + super().__init__(allow_cli_args=False, enable_bottom_toolbar=True, refresh_interval=0.5) + self.prompt = "demo> " + self.commands_run = 0 + self.running = "" + self.register_postparsing_hook(self._command_started) + self.register_cmdfinalization_hook(self._command_finished) + + def _command_started(self, data: cmd2.plugin.PostparsingData) -> cmd2.plugin.PostparsingData: + self.running = data.statement.command + return data + + def _command_finished(self, data: cmd2.plugin.CommandFinalizationData) -> cmd2.plugin.CommandFinalizationData: + if data.statement is not None: + self.commands_run += 1 + self.running = "" + return data + + def get_bottom_toolbar(self) -> list[tuple[str, str]]: + """Formatted text, as for prompt-toolkit: a list of (style, text).""" + state = ("fg:ansiyellow bold", f"running {self.running}") if self.running else ("fg:ansigreen bold", "idle") + return [ + ("", " "), + state, + ("", f" | commands run: {self.commands_run} | {time.strftime('%H:%M:%S')} "), + ] + + @cmd2.with_argument_list + def do_slow(self, args: list[str]) -> None: + """Print a line every quarter of a second: slow [COUNT].""" + for number in range(int(args[0]) if args else 12): + self.poutput(f"line {number}") + time.sleep(0.25) + self.poutput("slow done") + + @cmd2.with_argument_list + def do_burst(self, args: list[str]) -> None: + """Print numbered lines with a pause between them: burst COUNT [DELAY_MS].""" + count = int(args[0]) if args else 1000 + delay = int(args[1]) / 1000 if len(args) > 1 else 0 + started = time.perf_counter() + for number in range(count): + self.poutput(f"burst {number}") + if delay: + time.sleep(delay) + self.poutput(f"burst done in {time.perf_counter() - started:.2f} s") + + @cmd2.with_argument_list + def do_page(self, args: list[str]) -> None: + """Show numbered rows in a pager: page [COUNT].""" + self.ppaged("\n".join(f"row {number}" for number in range(int(args[0]) if args else 300))) + + def do_ask(self, _: cmd2.Statement) -> None: + """Ask for a line of input in the middle of a command.""" + self.poutput(f"got {self.read_input('Value: ')}") + + def do_fail(self, _: cmd2.Statement) -> None: + """End the application with exit code 3.""" + self.exit_code = 3 + return True # type: ignore[return-value] + + +if __name__ == "__main__": + if "--plain" in sys.argv: + # Without the launcher: this is what cmd2 does today. + os.environ.pop(textual_toolbar.HOST_SOCKET_ENV, None) + sys.exit(ToolbarDemo().cmdloop()) + sys.exit(textual_toolbar.run(ToolbarDemo)) diff --git a/tests/test_textual_toolbar.py b/tests/test_textual_toolbar.py new file mode 100644 index 000000000..16cde5a8d --- /dev/null +++ b/tests/test_textual_toolbar.py @@ -0,0 +1,387 @@ +"""Tests for the prototype of a bottom toolbar drawn by a Textual host.""" + +import asyncio +import json +import os +import re +import shutil +import socket +import sys +import tempfile +import threading + +import pytest +from prompt_toolkit.formatted_text import ANSI, HTML + +import cmd2 +from cmd2 import textual_toolbar +from cmd2.textual_toolbar import HOST_SOCKET_ENV, ToolbarReporter, render_ansi + +posix_only = pytest.mark.skipif(sys.platform == "win32", reason="the host needs Unix sockets and textual-tty") + + +@pytest.fixture +def host_socket(monkeypatch): + """A listening socket whose path a hosted application would find in its environment.""" + # Not pytest's temporary directory: a Unix socket's path is limited to about a hundred + # bytes, and that one is longer when the tests run in parallel. + directory = tempfile.mkdtemp(prefix="c2", dir="/tmp") + listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + try: + path = os.path.join(directory, "t.sock") + listener.bind(path) + listener.listen(1) + monkeypatch.setenv(HOST_SOCKET_ENV, path) + yield listener + finally: + listener.close() + shutil.rmtree(directory, ignore_errors=True) + + +def received(connection: socket.socket, count: int) -> list[str]: + """Read that many toolbar documents from a reporter.""" + reader = connection.makefile("r") + return [json.loads(reader.readline())["toolbar"] for _ in range(count)] + + +def plain(rendered: str) -> str: + """What is left of rendered content without its styles.""" + return re.sub(r"\x1b\[[0-9;]*m", "", rendered) + + +class TestRendering: + def test_plain_text_is_sent_as_it_is(self) -> None: + assert plain(render_ansi("hello")) == "hello" + assert set(re.findall(r"\x1b\[[0-9;]*m", render_ansi("hello"))) == {"\x1b[0m"} + + def test_nothing_renders_as_nothing_to_show(self) -> None: + assert plain(render_ansi(None)) == "" + + def test_styles_become_graphic_rendition_sequences(self) -> None: + rendered = render_ansi([("fg:ansigreen bold", "idle"), ("", " rest")]) + assert "\x1b[0;32;1midle\x1b[0m rest" in rendered + + def test_rows_are_separated_by_a_newline_alone(self) -> None: + assert plain(render_ansi("one\ntwo")) == "one\ntwo" + + @pytest.mark.parametrize( + ("content", "style"), + [(HTML("bold text"), "\x1b[0;1mbold"), (ANSI("\x1b[31mred\x1b[0m text"), "\x1b[0;31mred")], + ) + def test_anything_prompt_toolkit_formats_is_understood(self, content, style) -> None: + rendered = render_ansi(content) + assert plain(rendered).endswith(" text") + assert style in rendered + + def test_nothing_but_styles_is_sent(self) -> None: + """The renderer turns autowrap on as it starts, which is no business of the host's.""" + assert "\x1b[?7h" not in render_ansi("hello") + + +@posix_only +class TestReporter: + def test_content_is_sent_at_once_and_then_when_it_changes(self, host_socket) -> None: + content = ["first"] + with ToolbarReporter(lambda: content[0], interval=0.01) as reporter: + connection, _ = host_socket.accept() + with connection: + assert received(connection, 1) == [render_ansi("first")] + content[0] = "second" + reporter.poke() + assert received(connection, 1) == [render_ansi("second")] + + def test_unchanged_content_is_not_sent_again(self, host_socket) -> None: + calls = threading.Event() + count = [0] + + def content() -> str: + count[0] += 1 + if count[0] >= 4: + calls.set() + return "same" if count[0] < 6 else "different" + + with ToolbarReporter(content, interval=0.01): + connection, _ = host_socket.accept() + with connection: + assert calls.wait(5) + assert received(connection, 2) == [render_ansi("same"), render_ansi("different")] + + def test_a_failing_callback_keeps_the_last_content(self, host_socket) -> None: + state = ["good"] + + def content() -> str: + if state[0] == "bad": + raise RuntimeError("toolbar callback failed") + return state[0] + + with ToolbarReporter(content, interval=0.01) as reporter: + connection, _ = host_socket.accept() + with connection: + assert received(connection, 1) == [render_ansi("good")] + state[0] = "bad" + reporter.poke() + state[0] = "better" + reporter.poke() + assert received(connection, 1) == [render_ansi("better")] + + def test_a_host_which_has_gone_ends_the_reporting(self, host_socket) -> None: + content = ["first"] + reporter = ToolbarReporter(lambda: content[0], interval=0.01) + reporter.start() + connection, _ = host_socket.accept() + connection.close() + host_socket.close() + # Sending to a closed connection fails within a write or two. + for number in range(200): + content[0] = f"change {number}" + reporter.poke() + if reporter._thread is not None and not reporter._thread.is_alive(): + break + threading.Event().wait(0.01) + assert reporter._thread is not None + assert not reporter._thread.is_alive() + reporter.stop() + + def test_an_interval_of_zero_uses_the_default(self) -> None: + assert ToolbarReporter(lambda: "", interval=0)._interval == textual_toolbar.DEFAULT_INTERVAL + + +class TestHostedApplication: + def test_prompt_toolkit_draws_no_toolbar_when_hosted(self, monkeypatch) -> None: + monkeypatch.setenv(HOST_SOCKET_ENV, "/nowhere") + assert textual_toolbar.is_hosted() + app = cmd2.Cmd(allow_cli_args=False, enable_bottom_toolbar=True) + assert app.main_session.bottom_toolbar is None + + def test_prompt_toolkit_draws_the_toolbar_otherwise(self, monkeypatch) -> None: + monkeypatch.delenv(HOST_SOCKET_ENV, raising=False) + assert not textual_toolbar.is_hosted() + app = cmd2.Cmd(allow_cli_args=False, enable_bottom_toolbar=True) + assert app.main_session.bottom_toolbar is not None + + def test_without_a_terminal_the_application_runs_as_it_always_did(self, monkeypatch) -> None: + monkeypatch.delenv(HOST_SOCKET_ENV, raising=False) + assert not textual_toolbar.can_host() # pytest has taken stdin and stdout + + class App(cmd2.Cmd): + def cmdloop(self, intro="") -> int: + return 7 + + assert textual_toolbar.run(lambda: App(allow_cli_args=False)) == 7 + + @posix_only + def test_a_hosted_application_reports_its_toolbar_while_its_loop_runs(self, host_socket) -> None: + seen: list[str] = [] + + class App(cmd2.Cmd): + def get_bottom_toolbar(self) -> str: + return "from the application" + + def cmdloop(self, intro="") -> int: + connection, _ = host_socket.accept() + with connection: + seen.extend(received(connection, 1)) + return 5 + + assert textual_toolbar.run(lambda: App(allow_cli_args=False, enable_bottom_toolbar=True)) == 5 + assert seen == [render_ansi("from the application")] + # Programs the application runs must not think they are hosted too. + assert HOST_SOCKET_ENV not in os.environ + + +@posix_only +class TestHost: + def test_the_host_shows_the_program_s_toolbar_and_returns_its_exit_code(self, host_socket) -> None: + pytest.importorskip("textual_tty") + from textual.widgets import Static + + # A program which reports a toolbar as a hosted cmd2 application does, waits to be told to go, and exits with 3. + program = ( + "import json, os, socket, sys\n" + "s = socket.socket(socket.AF_UNIX)\n" + f"s.connect({host_socket.getsockname()!r})\n" + "s.sendall(json.dumps({'toolbar': '\\x1b[0;1mSTATUS\\x1b[0m line'}).encode() + b'\\n')\n" + "print('program output', flush=True)\n" + "sys.stdin.readline()\n" + "sys.exit(3)\n" + ) + app = textual_toolbar.build_host_app([sys.executable, "-c", program], host_socket) + + async def drive() -> str: + async with app.run_test() as pilot: + toolbar = app.query_one("#toolbar", Static) + for _ in range(200): + await pilot.pause(0.02) + if "STATUS" in str(toolbar.render()): + break + shown = str(toolbar.render()) + await pilot.press("enter") + for _ in range(200): + await pilot.pause(0.02) + if not app.is_running: + break + return shown + + assert asyncio.run(drive()) == "STATUS line" + assert app.program_exit_code == 3 + + def test_a_toolbar_of_two_rows_takes_two_rows_from_the_program(self, host_socket) -> None: + """The toolbar is as tall as its content, and the terminal the program sees shrinks to make room.""" + pytest.importorskip("textual_tty") + from textual.widgets import Static + + program = ( + "import json, os, socket, sys, time\n" + "s = socket.socket(socket.AF_UNIX)\n" + f"s.connect({host_socket.getsockname()!r})\n" + "sys.stdin.readline()\n" + "s.sendall(json.dumps({'toolbar': 'one\\ntwo'}).encode() + b'\\n')\n" + "sys.stdin.readline()\n" + ) + app = textual_toolbar.build_host_app([sys.executable, "-c", program], host_socket) + + async def drive() -> tuple[int, int, int, int]: + async with app.run_test(size=(80, 24)) as pilot: + await pilot.pause(0.2) + toolbar = app.query_one("#toolbar", Static) + before = (toolbar.size.height, app.query_one("#program").size.height) + await pilot.press("enter") + for _ in range(200): + await pilot.pause(0.02) + if toolbar.size.height == 2: + break + after = (toolbar.size.height, app.query_one("#program").size.height) + await pilot.press("enter") + for _ in range(200): + await pilot.pause(0.02) + if not app.is_running: + break + return (*before, *after) + + assert asyncio.run(drive()) == (1, 23, 2, 22) + + +@posix_only +class TestScrollback: + """The rows which scroll off the top of the program's screen are kept, and can be looked back at.""" + + @staticmethod + def host(host_socket, lines: int): + program = ( + "import sys\n" + f"for number in range({lines}):\n" + " print('row', number)\n" + "print('printed', flush=True)\n" + "sys.stdin.readline()\n" + ) + return textual_toolbar.build_host_app([sys.executable, "-c", program], host_socket) + + @staticmethod + def shown(terminal) -> list[str]: + return [terminal.render_line(y).text.rstrip() for y in range(terminal.size.height)] + + async def until(self, pilot, predicate) -> bool: + for _ in range(300): + await pilot.pause(0.02) + if predicate(): + return True + return False + + def test_rows_which_scroll_off_are_kept_and_shown_when_looking_back(self, host_socket) -> None: + pytest.importorskip("textual_tty") + app = self.host(host_socket, 100) + + async def drive() -> None: + async with app.run_test(size=(80, 24)) as pilot: + terminal = app.query_one("#program") + assert await self.until(pilot, lambda: "printed" in self.shown(terminal)) + # 23 rows of screen: the last 21 rows of output, "printed", and the row the cursor is on. + assert self.shown(terminal)[:2] == ["row 79", "row 80"] + assert len(terminal.scrollback) == 79 + assert [row for row in self.shown(terminal) if row.startswith("row")][-1] == "row 99" + + await pilot.press("shift+pageup") + assert terminal.back == 22 + assert self.shown(terminal)[0] == "row 57" + assert self.shown(terminal)[-1] == "row 79" + + await pilot.press("shift+home") + assert terminal.back == 79 + assert self.shown(terminal)[:2] == ["row 0", "row 1"] + + await pilot.press("shift+pagedown") + assert self.shown(terminal)[0] == "row 22" + + await pilot.press("shift+end") + assert terminal.back == 0 + assert self.shown(terminal)[0] == "row 79" + + terminal.look(3) + await pilot.pause() + assert self.shown(terminal)[0] == "row 76" + # Looking further back than there is stops at the oldest row. + terminal.look(1000) + assert terminal.back == 79 + await pilot.press("enter") + assert await self.until(pilot, lambda: not app.is_running) + + asyncio.run(drive()) + + def test_typing_returns_to_the_bottom(self, host_socket) -> None: + pytest.importorskip("textual_tty") + app = self.host(host_socket, 100) + + async def drive() -> None: + async with app.run_test(size=(80, 24)) as pilot: + terminal = app.query_one("#program") + assert await self.until(pilot, lambda: "printed" in self.shown(terminal)) + await pilot.press("shift+pageup") + assert terminal.back + assert "rows back]" in str(app.query_one("#toolbar").render()) + await pilot.press("x") + assert terminal.back == 0 + assert "rows back]" not in str(app.query_one("#toolbar").render()) + await pilot.press("enter") + assert await self.until(pilot, lambda: not app.is_running) + + asyncio.run(drive()) + + def test_a_shorter_screen_sends_its_top_rows_to_the_scrollback(self, host_socket) -> None: + """The emulator would cut the bottom rows off, the cursor's among them.""" + pytest.importorskip("textual_tty") + app = self.host(host_socket, 15) + + async def drive() -> None: + async with app.run_test(size=(80, 24)) as pilot: + terminal = app.query_one("#program") + assert await self.until(pilot, lambda: "printed" in self.shown(terminal)) + assert not terminal.scrollback + await pilot.resize_terminal(80, 12) + assert await self.until(pilot, lambda: terminal.size.height == 11) + # 17 rows were in use: 15 of output, "printed" and the cursor's. Eleven fit. + assert len(terminal.scrollback) == 6 + assert self.shown(terminal)[0] == "row 6" + assert "printed" in self.shown(terminal) + await pilot.press("shift+home") + assert self.shown(terminal)[0] == "row 0" + await pilot.press("enter") + assert await self.until(pilot, lambda: not app.is_running) + + asyncio.run(drive()) + + def test_no_more_rows_are_kept_than_the_limit(self, host_socket, monkeypatch) -> None: + pytest.importorskip("textual_tty") + monkeypatch.setattr(textual_toolbar, "SCROLLBACK_ROWS", 30) + app = self.host(host_socket, 100) + + async def drive() -> None: + async with app.run_test(size=(80, 24)) as pilot: + terminal = app.query_one("#program") + assert await self.until(pilot, lambda: "printed" in self.shown(terminal)) + assert len(terminal.scrollback) == 30 + await pilot.press("shift+home") + assert self.shown(terminal)[0] == "row 49" + await pilot.press("enter") + assert await self.until(pilot, lambda: not app.is_running) + + asyncio.run(drive())