Persistent bottom toolbar during command execution

[tleonhardt]

Summary

Until now, enable_bottom_toolbar=True gave you a toolbar that existed only while prompt-toolkit owned the terminal — it vanished the moment you pressed Enter and came back when the next prompt was drawn. This PR makes the toolbar persistent: it stays pinned to the bottom of the terminal and keeps refreshing while commands run, with command output scrolling above it.

No API change is required to get this. Applications that already set enable_bottom_toolbar=True pick up the new behavior automatically.

How it works

A new internal module, cmd2/command_toolbar.py, runs a minimal prompt_toolkit.Application on a background thread while the command executes on the main thread:

• Output goes above the toolbar. Terminal streams (self.stdout, sys.stdout, sys.stderr) are wrapped in a ToolbarStream that routes writes through prompt-toolkit's stdout proxy. Only streams that are TTYs are wrapped, so redirected output and nested command redirection to a file are untouched.
• The display owns terminal input so it can receive cursor position reports. Keys typed during a command are stored as typeahead and replayed at the next prompt, matching normal terminal behavior.
• Ctrl-C behaves like it does at the prompt. Raw mode clears ISIG, so the toolbar forwards SIGINT to the foreground process group (_thread.interrupt_main() on Windows), which reaches a subprocess a command is waiting on. Ctrl-C also flushes pending typeahead so a cancelled keystroke never becomes the next command.
• Ctrl-Z still suspends where supported and self.enable_suspend is set; the toolbar restores cooked mode before stopping and redraws on resume.

Yielding the terminal

Anything that needs exclusive terminal access suspends the toolbar and restores it afterward. A @suspend_toolbar decorator handles cmd2's own cases: ppaged(), select(), _read_raw_input(), do_shell(), _run_python(), do_ipy(), and _run_cmdfinalization_hooks().

Piped output is handled specially: a pipe process may be interactive (less, fzf), so it now inherits the real terminal file descriptor rather than having its output captured and relayed. The toolbar suspension is held open in RedirectionSavedState.toolbar_suspension until _restore_output() reaps the process.

For application code, a new public context manager covers custom terminal UIs, bare input() calls, and subprocesses your commands start:

with self.suspend_bottom_toolbar():
    answer = input("Continue? ")

Scope

The command toolbar is started by the interactive command loop only — including startup commands and scripts launched from it. It is disabled for non-interactive input, and direct onecmd_plus_hooks() calls made outside the command loop do not start one. If the toolbar fails to start or dies mid-command, the error is reported via perror(), streams are restored, and the reference is cleared so the rest of the session isn't left without a toolbar.

Notes for toolbar authors

get_bottom_toolbar() now runs on a background UI thread during command execution. Keep it fast and guard any state a command or another thread mutates with a lock. Setting refresh_interval > 0 makes the toolbar update on a timer during command execution too, not just at the prompt.

Docs and example

• docs/features/prompt.md rewritten for the new behavior, including a section on commands that take over the terminal and the Ctrl-C / Ctrl-\ semantics under raw mode.
• examples/getting_started.py gains a work [seconds] command that prints output on a one-second cadence so you can watch the toolbar clock tick alongside it.
• suspend_bottom_toolbar added to the mkdocs API filter list; CHANGELOG entry opened under 4.3.0 (TBD).

Testing

tests/test_command_toolbar.py adds 26 tests (470 lines) built on a pseudo-terminal harness, covering output ordering, suspension and nesting, typeahead capture, Ctrl-C forwarding, redirection, and pipe handoff.

Full suite on macOS: 1882 passed, 2 skipped (both skips are pre-existing Windows-only tests in test_cmd2.py, unrelated to this change). Coverage of the new module is 100% (195/195 statements); cmd2/cmd2.py is at 99%. The Windows SIGINT path is not exercised by this run and would benefit from a check on Windows CI.

NOTES

This is one architectural approach to solving the problem. I marked it as draft because I am also working on a very different approach as well. Once both approaches are posted I will want other developers to review both approaches and we can decide which we like best from both a user experience and maintainability perspective.

TODO

• Fix on Windows
• Fully cover all new code with tests
• Improve documentation

Closes #1743

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.66%. Comparing base (ca0ddbe) to head (063deed).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1744      +/-   ##
==========================================
+ Coverage   99.64%   99.66%   +0.01%     
==========================================
  Files          23       24       +1     
  Lines        5973     6211     +238     
==========================================
+ Hits         5952     6190     +238     
  Misses         21       21              

Flag	Coverage Δ
unittests	99.66% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[tleonhardt]

This branch and PR was a first attempt at making the bottom bar more persistent. It solved some but not all of the problems. A better approach came after in PR #1745