Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
55 commits
Select commit Hold shift + click to select a range
76dcc78
Implemented: enable_bottom_toolbar=True now keeps the toolbar visible…
tleonhardt Sep 5, 2026
1c491b1
Various bug fixes
tleonhardt Sep 5, 2026
1702654
Fix Windows CI failures in command toolbar tests
tleonhardt Sep 5, 2026
aac8a4e
Working prototype for one application with interchangeable layouts an…
tleonhardt Sep 5, 2026
6cb419d
Cover the toolbar's EOF shutdown path
tleonhardt Sep 5, 2026
a715034
Merge persistent-bottom-bar fixes into consolidated_toolbar
tleonhardt Sep 5, 2026
0dac278
Merge toolbar EOF regression coverage from persistent-bottom-bar
tleonhardt Sep 5, 2026
7340427
Added unit tests to completely cover code added for command_toolbar.p…
tleonhardt Sep 5, 2026
4915ea7
Measure paged output before building a pager
tleonhardt Sep 6, 2026
cc6ea8b
Fixed 4 issues found during automated code review
tleonhardt Sep 6, 2026
f759c1d
Fixed the pager to strip OSC sequences before ANSI parsing, preservin…
tleonhardt Sep 6, 2026
a0b2d9e
Moved tests for pager.py to new test_pager.py file from test_command_…
tleonhardt Sep 6, 2026
379a473
Fix tests that were failing on Windows
tleonhardt Sep 6, 2026
a0a742c
Fix Windows test hang from mocking the event loop's call_soon_threadsafe
tleonhardt Sep 6, 2026
2d23c35
Add CLAUDE.md file to give Claude Code guidance
tleonhardt Sep 6, 2026
dfdeb8a
Merge branch 'main' into consolidated_toolbar
tleonhardt Sep 6, 2026
a0b52d2
Added info on new embedded pager to CHANGELOG and docs
tleonhardt Sep 6, 2026
2bb4f87
Merge branch 'main' into consolidated_toolbar
tleonhardt Sep 6, 2026
711c7fd
Merge branch 'main' into consolidated_toolbar
tleonhardt Sep 6, 2026
c9395ea
Test additional keyboard shortcuts in embedded pager tests
tleonhardt Sep 6, 2026
c77e08a
Added examples/pager_diag.py for diagnosing embedded pager issues on …
tleonhardt Sep 6, 2026
b1fb5ee
Remove pager_diag.py example which was used temporarily for troublesh…
tleonhardt Sep 6, 2026
7663cd7
Expanded pager tests to ensure the keyboard shortcuts behave as expected
tleonhardt Sep 6, 2026
68932ec
Merge branch 'main' into consolidated_toolbar
tleonhardt Sep 6, 2026
dee4c9b
feat: keep the bottom toolbar visible during nested prompts (#1750)
tleonhardt Sep 6, 2026
eeef9fa
Make the test suite environment-independent, fix UTF-8 redirection, a…
tleonhardt Sep 7, 2026
9460838
Describe the redirection bug's actual reach in the changelog
tleonhardt Sep 7, 2026
1fb5668
Merge branch 'main' into stage2-nonerasing-commit
tleonhardt Sep 8, 2026
35c9067
Merge branch 'main' into reserved_row_toolbar
tleonhardt Sep 8, 2026
2e3d2d5
Merge branch 'stage2-nonerasing-commit' into reserved_row_toolbar
tleonhardt Sep 8, 2026
60bbad9
Merge branch 'main' into consolidated_toolbar
tleonhardt Oct 17, 2026
b7bb6be
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 3, 2026
13c9ea7
Write window titles on the command toolbar's event loop
tleonhardt Nov 3, 2026
8200dc3
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 14, 2026
114364f
Suspend the toolbar while the editor runs
tleonhardt Nov 14, 2026
189ab53
Hold the display thread until a Ctrl-Z stop has taken it
tleonhardt Nov 14, 2026
4730823
Stop the command toolbar after its first display error
tleonhardt Nov 14, 2026
b511661
Document the toolbar callback's locking and failure rules
tleonhardt Nov 14, 2026
fb4a2d9
Keep unfinished lines of command output above the toolbar
tleonhardt Nov 14, 2026
809a1d5
Report the error which stopped the toolbar, not one from its last frame
tleonhardt Nov 14, 2026
ac0cc0b
Count the rows of an unfinished line by the width Windows wraps at
tleonhardt Nov 15, 2026
cbfb566
Leave an unfinished line ended once its first row has scrolled away
tleonhardt Nov 15, 2026
939ce21
Count the row a legacy Windows console has already wrapped to
tleonhardt Nov 15, 2026
2f4b5dd
Remember the toolbar's rows until it has been drawn for the command
tleonhardt Nov 15, 2026
7747214
Test Ctrl-Z during an ordinary command, not only in the pager
tleonhardt Nov 15, 2026
ead92b0
Take the built-in pager out, to be proposed on its own
tleonhardt Nov 15, 2026
87c3b8a
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 15, 2026
8bf2331
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 16, 2026
1baf4de
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 17, 2026
d42d800
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 17, 2026
47e675a
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 17, 2026
b7dd0fd
Describe the Textual toolbar example as an alternative to cmd2's own …
tleonhardt Nov 17, 2026
dc81606
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 17, 2026
ac92679
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 17, 2026
4c97d59
Merge branch 'main' into consolidated_toolbar
tleonhardt Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,14 @@
## 4.5.0 (TBD)

- Enhancements
- `enable_bottom_toolbar=True` now keeps the toolbar visible and refreshing during command
execution. Command output appears above it. A line of output left unfinished when a command
ends is ended there, so the next prompt starts on a new line while the toolbar is enabled.
- `Cmd.read_input()` and `Cmd.read_secret()` now keep the bottom toolbar visible while they wait
for input, refreshing at the same `refresh_interval` as the main prompt, instead of the
toolbar disappearing for the duration of the nested prompt. `Cmd.select()` is unchanged, since
prompt-toolkit's `choice()` offers no way to configure a refresh interval

## 4.4.3 (2026-11-16)

- Bug Fixes
Expand Down
143 changes: 125 additions & 18 deletions cmd2/cmd2.py

Large diffs are not rendered by default.

575 changes: 575 additions & 0 deletions cmd2/command_toolbar.py

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions cmd2/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -1534,8 +1534,8 @@ def __init__(
self.saved_pipe_proc_reader = pipe_proc_reader
self.saved_redirecting = saved_redirecting

# Holds what a pipe needs until its pipe process has been reaped: on Windows a UTF-8 console, and for a terminal
# pipeline its job control
# Holds what a pipe needs until its pipe process has been reaped: the bottom toolbar's suspension while the pipe
# process owns the terminal, on Windows a UTF-8 console, and for a terminal pipeline its job control
self.pipe_context: contextlib.ExitStack | None = None


Expand Down
17 changes: 11 additions & 6 deletions docs/examples/embedding_in_textual.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,9 +120,12 @@ The example handles several details which are easy to miss when building somethi

## A Bottom Toolbar Which Stays While Commands Run

A [bottom toolbar](../features/prompt.md#bottom-toolbar) is drawn by `prompt-toolkit` as part of the
prompt, so it is only on the screen while the prompt is. The same embedding technique gives you one
which stays, and keeps refreshing, while a command runs. The
`cmd2` can keep its own [bottom toolbar](../features/prompt.md#bottom-toolbar) on the screen while a
command runs. It draws that toolbar in the terminal which the command is using, so it has to hide it
whenever something else
[takes over the terminal](../features/prompt.md#commands-that-take-over-the-terminal), as a shell
command does. The same embedding technique gives you a toolbar which is drawn outside that terminal,
so it stays, and keeps refreshing, whatever runs there. The
[textual_tty_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_toolbar.py)
example is a Textual application which is nothing but a terminal pane running a `cmd2` application
and a toolbar docked below it, so it looks like the `cmd2` application running on its own:
Expand All @@ -131,8 +134,9 @@ and a toolbar docked below it, so it looks like the `cmd2` application running o
uv run examples/textual_tty_toolbar.py
```

Try `slow`, `burst 2000 1`, or resizing the window while a command runs. Pass `--cmd2-only` to see
what `cmd2` does without Textual, where the toolbar disappears for as long as a command runs.
Try `slow`, `burst 2000 1`, `shell sleep 5`, or resizing the window while a command runs. Pass
`--cmd2-only` to compare it with the toolbar `cmd2` draws itself, without Textual, which is hidden
for as long as the shell command runs.

Here the `cmd2` application doesn't draw the toolbar at all. It passes `enable_bottom_toolbar=False`
to [cmd2.Cmd.__init__][] when it is running inside the Textual application, and sends what
Expand Down Expand Up @@ -166,7 +170,8 @@ in the middle of the command's output. So this example uses a Unix socket instea
- `get_bottom_toolbar()` is therefore called on that thread while a command is running on the main
thread, so it must only read state which is safe to read from another thread.

This approach has costs which are easy to overlook, and they are why `cmd2` doesn't do it for you:
This approach has costs which are easy to overlook, and they are why `cmd2` draws its own toolbar in
the user's terminal instead:

- There is no scrollback. The terminal pane keeps none, so output which scrolls off its top is gone,
and Textual uses the terminal's alternate screen, so none of the session is in the scrollback of
Expand Down
7 changes: 6 additions & 1 deletion docs/features/os.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,12 @@ system.

## Terminal pagers

Output of any command can be displayed one page at a time using the [cmd2.Cmd.ppaged][] method.
Output of any command can be displayed one page at a time using the [cmd2.Cmd.ppaged][] method. A
pager is only used when the terminal is interactive. Inside a script, or when the command's output
is redirected or piped, `ppaged()` falls back to `poutput()`.

While the [bottom toolbar](./prompt.md#bottom-toolbar) is running, a pager temporarily hides it,
because the pager takes over the terminal. The toolbar comes back when the pager exits.

The pager is the command in `self.pager`, or `self.pager_chop` when chopping long lines: `less` on
POSIX systems and `more` on Windows by default. If that program cannot be run, for example because
Expand Down
66 changes: 58 additions & 8 deletions docs/features/prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,8 @@ example for a demonstration.
## Bottom Toolbar

`cmd2` supports an optional, persistent bottom toolbar that is always visible at the bottom of the
terminal window while the application is idle and waiting for input.
terminal window while the application is waiting for input and while commands execute. Command
output appears above the toolbar.

### Enabling the Toolbar

Expand Down Expand Up @@ -112,10 +113,10 @@ def get_bottom_toolbar(self) -> AnyFormattedText:

### Refreshing the Toolbar

Since the toolbar is rendered by `prompt-toolkit` as part of the prompt, it is naturally redrawn
whenever the prompt is refreshed. If you want the toolbar to update automatically (for example, to
display a clock), you can set `refresh_interval` in the [cmd2.Cmd.__init__][] constructor to a value
greater than 0.0.
The toolbar is rendered by `prompt-toolkit` and is naturally redrawn whenever the prompt is
refreshed. If you want the toolbar to update automatically during input and command execution (for
example, to display a clock), you can set `refresh_interval` in the [cmd2.Cmd.__init__][]
constructor to a value greater than 0.0.

```py
class App(cmd2.Cmd):
Expand All @@ -125,7 +126,23 @@ class App(cmd2.Cmd):

See the
[getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)
example for a demonstration of this technique.
example for a demonstration of this technique. Run its `work 5` command to see the clock update
while the command prints output.

During command execution, `get_bottom_toolbar()` runs in a background UI thread. Keep the callback
fast and use a lock when reading state that a command or another thread modifies.

!!! warning

A command must not hold a lock which `get_bottom_toolbar()` acquires while it calls anything
that pauses the toolbar: `read_input()`, `read_secret()`, `select()`, `ppaged()`, `do_shell()`,
`run_editor()`, an embedded Python shell, or `suspend_bottom_toolbar()`. To pause the toolbar,
`cmd2` waits for the refresh in progress to finish. A callback blocked on a lock the command is
holding never finishes, so the application hangs. Copy what you need while holding the lock,
release it, and then prompt or page.

If `get_bottom_toolbar()` raises an exception while a command is running, `cmd2` reports the error
once and the command carries on without the toolbar.

!!! tip

Expand All @@ -134,7 +151,40 @@ example for a demonstration of this technique.
widgets which display that information. See
[Embedding in Textual](../examples/embedding_in_textual.md).

The same technique can keep a toolbar on the screen while a command runs, which this one is
not: it is part of the prompt. See
The same technique can also draw the toolbar itself, in a widget of the Textual application. See
[A Bottom Toolbar Which Stays While Commands Run](../examples/embedding_in_textual.md#a-bottom-toolbar-which-stays-while-commands-run)
for an example, and for what it costs.

### Commands That Take Over the Terminal

cmd2 temporarily hides the toolbar for pagers, Python environments, and shell commands. It also
hides it while a command's output is piped to another process, since that process may be
interactive, as `less` and `fzf` are. It restores the toolbar when those operations finish.

[cmd2.Cmd.read_input][] and [cmd2.Cmd.read_secret][] keep the toolbar visible, and it continues to
refresh at the same `refresh_interval` as the main prompt, so a clock or status display does not go
stale while your command waits for input. [cmd2.Cmd.select][] does not yet show one, because
prompt-toolkit's `choice()` has no way to configure a refresh interval and its toolbar would go
stale while the selection sits idle.

For custom terminal UIs, calls to `input()`, or subprocesses your own command code starts, use
[cmd2.Cmd.suspend_bottom_toolbar][]:

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

Suspending matters for subprocesses even when they only print. While the toolbar is displayed, the
terminal is in raw mode, so the kernel generates no signals from keystrokes. cmd2 sends `Ctrl-C` on
to its own process group, which reaches a subprocess your command started and waits on, but `Ctrl-\`
(`SIGQUIT`) does nothing, exactly as at the main prompt.

Output which stops in the middle of a line, such as `Working...` or a progress line redrawn with
carriage returns, stays on the screen and is continued by the output which follows it. A line still
unfinished when the command ends, or when the toolbar is hidden for one of the operations above, is
ended there, so whatever comes next starts on a new line.

The command toolbar is used by the interactive command loop, including startup commands and scripts
launched from that loop. It is disabled for non-interactive input. Calls to `onecmd_plus_hooks()`
outside the command loop do not start a toolbar.
15 changes: 14 additions & 1 deletion examples/getting_started.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
import pathlib
import sys
import threading
import time
from typing import Annotated

from prompt_toolkit.application import get_app
Expand All @@ -37,7 +38,7 @@
Color,
stylize,
)
from cmd2.annotated import Option
from cmd2.annotated import Argument, Option


class BasicApp(cmd2.Cmd):
Expand Down Expand Up @@ -164,6 +165,18 @@ def get_rprompt(self) -> AnyFormattedText:
text = f"cwd={current_working_directory}"
return [(style, text)]

@cmd2.with_annotated
def do_work(
self,
seconds: Annotated[ # Optional positional argument, so both "work" and "work 5" are valid
int, Argument(nargs="?", help_text="number of seconds to work for")
] = 5,
) -> None:
"""Simulate work while the bottom toolbar clock keeps updating."""
for second in range(seconds):
self.poutput(f"Working: {second + 1}/{seconds}")
time.sleep(1)

@cmd2.with_annotated
def do_cat(
self,
Expand Down
19 changes: 10 additions & 9 deletions examples/textual_tty_toolbar.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
#!/usr/bin/env python3
"""Keep a bottom toolbar on the screen while commands run, by letting Textual draw it using textual-tty.

cmd2's bottom toolbar is drawn by prompt-toolkit as part of the prompt, so it is only there while the prompt is.
This example shows a way to have one which stays, and keeps refreshing, while a command runs: the cmd2
application doesn't draw the toolbar at all. A small Textual application owns the terminal instead. It shows the
cmd2 application in a terminal pane which fills the screen except for the bottom, where it draws the toolbar.
cmd2 can keep its own bottom toolbar on the screen while a command runs. It draws that toolbar in the terminal
which the command is using, so it has to hide it whenever something else takes over the terminal, as a shell
command does. This example shows a way to have one which stays, and keeps refreshing, whatever runs there: the
cmd2 application doesn't draw the toolbar at all. A small Textual application owns the terminal instead. It shows
the cmd2 application in a terminal pane which fills the screen except for the bottom, where it draws the toolbar.

How it works:
- [textual-tty](https://github.com/ttygroup/textual-tty) provides the ``Terminal`` widget, a terminal
Expand All @@ -22,7 +23,7 @@
output. A toolbar which refreshes during a command is sent from another thread, and a window title written into
the terminal's stream from another thread could land in the middle of the command's output.

Things this approach gives up, which is why cmd2 doesn't do it for you:
Things this approach gives up, which is why cmd2 draws its own toolbar in your terminal instead:
- Scrollback. The terminal pane keeps none, so output which scrolls off its top is gone, and Textual uses
the terminal's alternate screen, so none of the session is in your terminal's own scrollback either.
Pipe long output to a pager.
Expand All @@ -38,8 +39,9 @@
Otherwise, install textual-tty into your own environment with ``pip install textual-tty`` and then run
``python examples/textual_tty_toolbar.py``.

Things to try: ``slow``, ``burst 2000 1``, ``page``, ``ask``, resizing the window while a command runs, and
Ctrl-C during ``slow``. To compare with what cmd2 does on its own, run just the cmd2 application, on any platform:
Things to try: ``slow``, ``burst 2000 1``, ``page``, ``ask``, ``shell sleep 5``, resizing the window while a
command runs, and Ctrl-C during ``slow``. To compare with the toolbar cmd2 draws itself, run just the cmd2
application, on any platform:

python examples/textual_tty_toolbar.py --cmd2-only

Expand Down Expand Up @@ -171,8 +173,7 @@ def __init__(self, toolbar_socket: str | None) -> None:
"""Initialize the cmd2 application.

:param toolbar_socket: the Unix socket of the Textual application which draws the toolbar, or None if this
application isn't running inside one. Then prompt-toolkit draws the toolbar as usual,
which means only while the prompt is on the screen.
application isn't running inside one. Then cmd2 draws the toolbar itself.
"""
refresh_interval = 0.5
super().__init__(
Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ plugins:
filters:
- "!^_"
- "get_bottom_toolbar"
- "suspend_bottom_toolbar"
merge_init_into_class: true
docstring_style: sphinx
docstring_section_style: spacy
Expand Down
50 changes: 50 additions & 0 deletions tests/conftest.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
"""Cmd2 unit/functional testing"""

import io
import os
import subprocess
import sys
Expand All @@ -18,6 +19,11 @@
)

import pytest
from prompt_toolkit.application import create_app_session
from prompt_toolkit.data_structures import Size
from prompt_toolkit.input import create_pipe_input
from prompt_toolkit.output import DummyOutput
from prompt_toolkit.shortcuts import PromptSession

import cmd2
from cmd2 import rich_utils as ru
Expand Down Expand Up @@ -253,3 +259,47 @@ def autoload_command_sets_app():
@pytest.fixture
def manual_command_sets_app():
return WithCommandSets(auto_load_commands=False)


class Terminal(io.StringIO):
"""An in-memory stream that claims to be a terminal."""

def isatty(self) -> bool:
return True


class RecordingOutput(DummyOutput):
"""A prompt-toolkit output that records everything written to a Terminal."""

def __init__(self, stream: Terminal) -> None:
self.stdout = stream
self.size = Size(rows=24, columns=80)

def get_size(self) -> Size:
return self.size

def write(self, data: str) -> None:
self.stdout.write(data)

def write_raw(self, data: str) -> None:
self.stdout.write(data)


@pytest.fixture
def toolbar_app():
app = cmd2.Cmd(allow_cli_args=False)
output = Terminal()
app.stdout = output
with create_pipe_input() as pipe:
terminal = RecordingOutput(output)
# Bind the ambient app session to this terminal. Without it, prompt-toolkit
# builds a real one on demand for calls such as patch_stdout() in
# _read_raw_input(), which needs a console that Windows CI does not provide.
with create_app_session(input=pipe, output=terminal):
app.main_session = PromptSession(
input=pipe,
output=terminal,
bottom_toolbar="STATUS",
refresh_interval=0.01,
)
yield app, pipe, output
Loading
Loading