From 67ca1c7a79cbddd0be1e03811d024d6c99e9b674 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 19:31:28 -0500 Subject: [PATCH 1/3] PROTOTYPE: draw the bottom toolbar with Textual instead of prompt-toolkit A third way to keep the bottom toolbar on the screen while a command runs (#1743), to compare with the two which have prompt-toolkit draw it. Not for merging as it is. Here cmd2 does not draw the toolbar at all. textual_toolbar.run() starts a small Textual application which owns the real terminal: a terminal emulator widget (textual-tty's Terminal) with a toolbar widget docked below it. The cmd2 application runs inside the emulator as a child process, the same program run again, and sends the content of get_bottom_toolbar() to the host over a Unix socket from a thread, so it keeps coming while a command has the main thread. Command output cannot reach the toolbar's rows, because they belong to a different widget. - cmd2/textual_toolbar.py: the launcher, the reporter which runs in the cmd2 application, and the host. Textual is imported only when a host is started. - cmd2.py: one condition, so prompt-toolkit draws no toolbar when hosted. - examples/textual_toolbar.py: an application to try it with. Without textual and textual-tty, on Windows, or when stdin or stdout is not a terminal, run() runs the application as it always did. What it gives up, as it stands: the pane has no scrollback, the session leaves nothing in the terminal's own scrollback, Ctrl-Z does nothing, and it does not run on Windows. --- cmd2/cmd2.py | 4 +- cmd2/textual_toolbar.py | 326 ++++++++++++++++++++++++++++++++++ examples/README.md | 3 + examples/textual_toolbar.py | 97 ++++++++++ tests/test_textual_toolbar.py | 261 +++++++++++++++++++++++++++ 5 files changed, 690 insertions(+), 1 deletion(-) create mode 100644 cmd2/textual_toolbar.py create mode 100755 examples/textual_toolbar.py create mode 100644 tests/test_textual_toolbar.py diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index e945f5252..487ec4ad1 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 @@ -840,7 +841,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..de7d2a8e9 --- /dev/null +++ b/cmd2/textual_toolbar.py @@ -0,0 +1,326 @@ +"""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. + +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 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 + from textual.app import App, ComposeResult + from textual.message import Message + from textual.widgets import Static + from textual_tty import Terminal # type: ignore[import-untyped] + + class ToolbarChanged(Message): + """The program has new content for its toolbar.""" + + def __init__(self, rendered: str) -> None: + self.rendered = rendered + super().__init__() + + class ToolbarHost(App[None]): + """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 + + def compose(self) -> ComposeResult: + 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.query_one("#toolbar", Static).update(Text.from_ansi(message.rendered)) + + 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 128080a32..67eeb8840 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..66ecd61c8 --- /dev/null +++ b/examples/textual_toolbar.py @@ -0,0 +1,97 @@ +#!/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``. 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..574af8b62 --- /dev/null +++ b/tests/test_textual_toolbar.py @@ -0,0 +1,261 @@ +"""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) From f153e1731aae1fd8012b35f48ff851e9faba6d83 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 19:56:39 -0500 Subject: [PATCH 2/3] PROTOTYPE: give the Textual host's terminal a scrollback The session runs on the alternate screen of the real terminal, so none of it reaches that terminal's scrollback, and textual-tty's Terminal widget keeps none of its own: a row which scrolled off the top was gone. The host now uses a subclass of that widget which keeps the rows as they leave the top of the program's primary screen, ten thousand of them, and draws from them when the view has been moved back. The emulator scrolls in one place, Blitter.scroll(), so that is where they are taken. The view moves with the mouse wheel, or with Shift and Page Up, Page Down, Home or End where the real terminal passes those on; typing returns to the bottom; and it holds still while output goes on below. The toolbar says how far back the view is. When the widget is made shorter, the emulator cuts rows off at the bottom, the cursor's among them. The rows above the cursor now go to the scrollback instead, as they do in a terminal. Not done: selecting text while looking back, rewrapping kept rows when the width changes, and clearing the scrollback when the program asks (ED 3). It reaches into bittty and textual-tty attributes which are not public. --- cmd2/textual_toolbar.py | 180 +++++++++++++++++++++++++++++++++- examples/textual_toolbar.py | 6 +- tests/test_textual_toolbar.py | 126 ++++++++++++++++++++++++ 3 files changed, 308 insertions(+), 4 deletions(-) diff --git a/cmd2/textual_toolbar.py b/cmd2/textual_toolbar.py index de7d2a8e9..93e9fb872 100644 --- a/cmd2/textual_toolbar.py +++ b/cmd2/textual_toolbar.py @@ -14,6 +14,11 @@ 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__": @@ -250,6 +255,163 @@ def run_host(command: list[str]) -> int: shutil.rmtree(directory, ignore_errors=True) +#: 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 + from textual import events + from textual.message import Message + from textual.strip import Strip + from textual_tty import Terminal # type: ignore[import-untyped] + + class ScrollbackTerminal(Terminal): # type: ignore[misc] + """A terminal emulator widget with scrollback.""" + + class Scrolled(Message): + """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) -> Strip: + if not self.back: + return super().render_line(y) # type: ignore[no-any-return] + # 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)) # type: ignore[no-any-return] + 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 super()._cursor_shown() + + # --- sizing --- # + + def on_resize(self, event: events.Resize) -> 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: events.Key) -> 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: events.MouseEvent, 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. @@ -263,7 +425,8 @@ def build_host_app(command: list[str], listener: socket.socket) -> Any: from textual.app import App, ComposeResult from textual.message import Message from textual.widgets import Static - from textual_tty import Terminal # type: ignore[import-untyped] + + Terminal = scrollback_terminal_class() # noqa: N806 class ToolbarChanged(Message): """The program has new content for its toolbar.""" @@ -293,6 +456,8 @@ 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) -> ComposeResult: yield Terminal(command=command, id="program") @@ -315,7 +480,18 @@ async def _toolbar_connection(self, reader: asyncio.StreamReader, _writer: async self.post_message(ToolbarChanged(document["toolbar"])) def on_toolbar_changed(self, message: ToolbarChanged) -> None: - self.query_one("#toolbar", Static).update(Text.from_ansi(message.rendered)) + 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 diff --git a/examples/textual_toolbar.py b/examples/textual_toolbar.py index 66ecd61c8..10ed95ec9 100755 --- a/examples/textual_toolbar.py +++ b/examples/textual_toolbar.py @@ -12,8 +12,10 @@ 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``. Pass ``--plain`` to run the same application without Textual, -where prompt-toolkit draws the toolbar and it is only there at the prompt. +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 diff --git a/tests/test_textual_toolbar.py b/tests/test_textual_toolbar.py index 574af8b62..16cde5a8d 100644 --- a/tests/test_textual_toolbar.py +++ b/tests/test_textual_toolbar.py @@ -259,3 +259,129 @@ async def drive() -> tuple[int, int, int, int]: 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()) From 46ddf1ed77f3ec49ad0bda66f3bdca8d1a399cec Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sun, 15 Nov 2026 20:39:01 -0500 Subject: [PATCH 3/3] PROTOTYPE: type-check the Textual host without Textual installed CI checks types in an environment which has cmd2's own dependencies and not the development ones, so it has no Textual, and the import statements for it failed there. What a host needs from Textual is now imported by name at run time and treated as untyped, which checks the same way whether or not Textual is installed. --- cmd2/textual_toolbar.py | 47 ++++++++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/cmd2/textual_toolbar.py b/cmd2/textual_toolbar.py index 93e9fb872..62bfc7433 100644 --- a/cmd2/textual_toolbar.py +++ b/cmd2/textual_toolbar.py @@ -255,6 +255,15 @@ def run_host(command: list[str]) -> int: 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 @@ -276,15 +285,15 @@ def scrollback_terminal_class() -> Any: from collections import deque from rich.segment import Segment - from textual import events - from textual.message import Message - from textual.strip import Strip - from textual_tty import Terminal # type: ignore[import-untyped] + + 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): + 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: @@ -334,13 +343,13 @@ def look(self, rows: int) -> None: # --- drawing --- # - def render_line(self, y: int) -> Strip: + def render_line(self, y: int) -> Any: if not self.back: - return super().render_line(y) # type: ignore[no-any-return] + 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)) # type: ignore[no-any-return] + return super().render_line(row - len(self.scrollback)) width = self.size.width segments = [] run: list[str] = [] @@ -365,11 +374,11 @@ def _tick(self) -> None: self.refresh() def _cursor_shown(self) -> bool: - return not self.back and super()._cursor_shown() + return not self.back and bool(super()._cursor_shown()) # --- sizing --- # - def on_resize(self, event: events.Resize) -> None: + def on_resize(self, event: Any) -> None: height = event.size.height blitter = self.board.blitter below = self.board.cursor.y - (height - 1) @@ -384,7 +393,7 @@ def on_resize(self, event: events.Resize) -> None: # --- input --- # - def on_key(self, event: events.Key) -> None: + def on_key(self, event: Any) -> None: page = max(1, self.size.height - 1) moves = { "shift+pageup": page, @@ -401,7 +410,7 @@ def on_key(self, event: events.Key) -> None: self.look(-self.back) super().on_key(event) - def _wheel(self, event: events.MouseEvent, button: int, arrow: str) -> None: + 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) @@ -422,20 +431,20 @@ def build_host_app(command: list[str], listener: socket.socket) -> Any: import asyncio from rich.text import Text - from textual.app import App, ComposeResult - from textual.message import Message - from textual.widgets import Static - Terminal = scrollback_terminal_class() # noqa: N806 + 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): + 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]): + class ToolbarHost(App[None]): # type: ignore[misc] """A terminal emulator running the program, and its toolbar.""" CSS = """ @@ -459,7 +468,7 @@ def __init__(self) -> None: self._toolbar = Text() self._looking_back = "" - def compose(self) -> ComposeResult: + def compose(self) -> Any: yield Terminal(command=command, id="program") yield Static("", id="toolbar")