Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,12 @@
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
- Added an embedded pager which `Cmd.ppaged()` uses while the bottom toolbar is running, so the
toolbar stays visible and refreshing instead of the terminal being handed to an external
pager. It supports vertical and horizontal scrolling, incremental search, and chopped lines on
every platform, including Windows where the default external pager (`more`) always wraps.
Output which already fits on the screen is printed directly rather than paged. Set
`self.use_builtin_pager = False` to keep using the external `pager`/`pager_chop` commands.

## 4.4.3 (2026-11-16)

Expand Down
40 changes: 30 additions & 10 deletions cmd2/cmd2.py
Original file line number Diff line number Diff line change
Expand Up @@ -662,6 +662,10 @@ def __init__(
if callargs:
self._startup_commands.extend(callargs)

# The embedded pager shares the main toolbar. Applications can opt back
# into their configured external pager by setting this to False.
self.use_builtin_pager = enable_bottom_toolbar

# Set the pager(s) for use when displaying output using a pager
if sys.platform.startswith("win"):
self.pager = self.pager_chop = "more"
Expand Down Expand Up @@ -2015,18 +2019,21 @@ def ppaged(
fits on the screen. A pager is not used inside a script (Python or text) or when output is
redirected or piped, and in these cases, output is sent to `poutput`.

The pager takes over the terminal, so the bottom toolbar is hidden while it is open and
comes back when it exits.
While the bottom toolbar is running, the built-in pager keeps it visible and refreshing.
Set ``use_builtin_pager=False`` to use the configured external ``pager`` or ``pager_chop``
command instead; external pagers temporarily hide the toolbar. Where no toolbar is
running, such as outside the command loop, the external pager is used regardless.

If the pager program cannot be run, for example because it is not installed, the output
is printed without one. That pager command is not tried again while the application runs.
If the external pager program cannot be run, for example because it is not installed, the
output is printed without one. That pager command is not tried again while the application
runs. The built-in pager is not affected.

:param chop: True -> causes lines longer than the screen width to be chopped (truncated) rather than wrapped
- truncated text is still accessible by scrolling with the right & left arrow keys
- chopping is ideal for displaying wide tabular data as is done in utilities like pgcli
False -> causes lines longer than the screen width to wrap to the next line
- wrapping is ideal when you want to keep users from having to use horizontal scrolling
WARNING: On Windows, the text always wraps regardless of what the chop argument is set to
WARNING: The default external pager on Windows always wraps; the built-in pager supports chopping.
:param soft_wrap: Enable soft wrap mode. If True, lines of text will not be word-wrapped or cropped to
fit the terminal width. Defaults to True.

Expand All @@ -2048,8 +2055,15 @@ def ppaged(

pager = self.pager_chop if chop else self.pager

# Check if we are outputting to a pager. One which the shell could not run is not tried again.
if functional_terminal and can_block and pager not in self._unrunnable_pagers:
# Page inside the toolbar's display only when the command loop is already
# running one. Starting one here would seize the terminal for commands run
# outside that loop, which the toolbar is documented not to do.
toolbar = self._command_toolbar
builtin_pager = toolbar if self.use_builtin_pager and toolbar is not None and toolbar.is_active else None

# Check if we are outputting to a pager. An external one which the shell could not run is not tried again,
# which is no reason to go without the built-in pager.
if functional_terminal and can_block and (builtin_pager is not None or pager not in self._unrunnable_pagers):
# Chopping overrides soft_wrap, but only for what the pager is given
pager_soft_wrap = soft_wrap or chop

Expand All @@ -2070,8 +2084,14 @@ def ppaged(
soft_wrap=pager_soft_wrap,
**(rich_print_kwargs if rich_print_kwargs is not None else {}),
)
output = capture.get()

if builtin_pager is not None:
builtin_pager.page(output, chop=chop)
return

# As for a pipe: the pager gets UTF-8, and on Windows the console is UTF-8 while it runs.
output_bytes = capture.get().encode("utf-8", "replace")
output_bytes = output.encode("utf-8", "replace")

# Prevent KeyboardInterrupts while in the pager. The pager application will
# still receive the SIGINT since it is in the same process group as us.
Expand Down Expand Up @@ -2190,8 +2210,8 @@ def get_bottom_toolbar(self) -> AnyFormattedText:
During command execution this callback runs in a background UI thread. Protect shared
state with a lock when necessary, but never hold that lock in a command while it prompts
for input, pages output, runs a shell command, or otherwise pauses the toolbar: pausing
waits for this callback to return. The toolbar is suspended while another prompt, a
pager, or an interactive shell owns the terminal.
waits for this callback to return. The built-in pager shares this toolbar. It is suspended
while another prompt, external pager, or interactive shell owns the terminal.

If this callback raises an exception during a command, the error is reported once and the
command carries on without the toolbar.
Expand Down
145 changes: 144 additions & 1 deletion cmd2/command_toolbar.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,38 @@
import threading
import time
from collections.abc import Callable, Generator
from concurrent.futures import Future
from concurrent.futures import TimeoutError as FutureTimeoutError
from typing import TYPE_CHECKING, Any, TextIO, TypeVar, cast

from prompt_toolkit.application import Application, create_app_session, run_in_terminal
from prompt_toolkit.enums import EditingMode
from prompt_toolkit.filters import Condition, to_filter
from prompt_toolkit.input.typeahead import get_typeahead, store_typeahead
from prompt_toolkit.key_binding import KeyBindings
from prompt_toolkit.key_binding.key_processor import KeyPress, KeyPressEvent
from prompt_toolkit.layout import HSplit, Layout, Window
from prompt_toolkit.layout.containers import ConditionalContainer
from prompt_toolkit.output.vt100 import Vt100_Output
from prompt_toolkit.patch_stdout import StdoutProxy
from prompt_toolkit.utils import get_cwidth, suspend_to_background_supported

from .pager import Pager, output_fits

if TYPE_CHECKING:
from .cmd2 import Cmd

# Control sequences, operating system commands, and two-character escapes: text which takes
# no room on the screen.
_ESCAPE_RE = re.compile(r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])")

# Erases what "erase down" does when the cursor is in the first column of a row, without
# erasing from the top-left corner of the screen: the row itself, then from its second column
# to the end of the screen, and back.
ERASE_DOWN_FROM_FIRST_COLUMN = "\x1b[K\x1b[C\x1b[J\x1b[D"

_F = TypeVar("_F", bound=Callable[..., Any])
_R = TypeVar("_R")


def suspend_process_group(suspend_group: bool = True) -> None:
Expand Down Expand Up @@ -72,6 +84,32 @@ def wrapped(self: "Cmd", *args: Any, **kwargs: Any) -> Any:
return cast(_F, wrapped)


@contextlib.contextmanager
def erasing_from_the_second_column(output: Any) -> Generator[None]:
"""Have a terminal erase its screen without iTerm2 keeping what was on it.

iTerm2 saves a screen which is erased from its top-left corner to its scrollback, as a
shell's ``clear`` expects, and the alternate screen is no exception. A renderer erases its
screen from there when it is reset, which a full-screen one is when it closes, when the
terminal is resized and when it lends the terminal. Each would leave a page in the
scrollback of the screen the pager was started from.

The renderer always erases from the first column of a row, which is what lets the same
cells be erased starting from the second. Only an output which writes escape sequences
itself is changed, and it is put back afterwards.

:param output: the output the pager is drawn on
"""
if not isinstance(output, Vt100_Output):
yield
return
vars(output)["erase_down"] = functools.partial(output.write_raw, ERASE_DOWN_FROM_FIRST_COLUMN)
try:
yield
finally:
vars(output).pop("erase_down", None)


def pipe_target(stream: Any) -> Any:
"""Return the stream a pipe process can inherit, or ``None`` if its output must be captured.

Expand Down Expand Up @@ -341,6 +379,7 @@ def suspend(event: KeyPressEvent) -> None:
event.app.suspend_to_background()

self._bindings = bindings
self._suspend_binding = suspend

@staticmethod
def _suspend_to_background(suspend_group: bool = True) -> None:
Expand Down Expand Up @@ -398,7 +437,7 @@ def _resume(self) -> None:
# has not seen with other bindings. It caches the bindings it merges for each focused
# window, application bindings included, and does not notice this attribute being
# reassigned, so reusing a window with different bindings would keep the old ones.
# This layout and the main prompt's have windows of their own.
# This layout, the main prompt's, and each pager's all have windows of their own.
for name, value in (("layout", self._layout), ("key_bindings", self._bindings), ("erase_when_done", True)):
stack.callback(setattr, self.app, name, getattr(self.app, name))
setattr(self.app, name, value)
Expand Down Expand Up @@ -553,6 +592,110 @@ def is_active(self) -> bool:
"""Whether the display currently owns the terminal."""
return self._proxy is not None and self.app.is_running

def _call_in_ui(self, func: Callable[[], _R]) -> _R:
"""Change UI state on its event loop, propagating failures to the command."""
result: Future[_R] = Future()

def call() -> None:
try:
value = func()
except BaseException as exc: # noqa: BLE001
result.set_exception(exc)
else:
result.set_result(value)

if self.app.loop is None:
raise RuntimeError("Toolbar is not running")
self.app.loop.call_soon_threadsafe(call)
while True:
try:
value = result.result(timeout=0.1)
except FutureTimeoutError:
if result.done():
# The callback finished while this poll was expiring, or raised a
# TimeoutError of its own -- indistinguishable here, because
# concurrent.futures.TimeoutError is TimeoutError on Python 3.11+.
# Ask the future for its outcome rather than re-raising this poll's
# timeout, which would report a failure for a call that succeeded.
return result.result()
self._check_running()
else:
return value

def _check_running(self) -> None:
if self._thread is None or not self._thread.is_alive():
if self._error is not None:
raise self._error
raise EOFError

def page(self, text: str, *, chop: bool) -> None:
"""Show a pager above the same toolbar without starting another input reader."""
size = self.app.output.get_size()
# Measuring the toolbar can invoke its callback; keep that work on the
# UI thread along with rendering and layout changes.
toolbar_height = self._call_in_ui(lambda: self.toolbar.preferred_height(size.columns, size.rows).preferred)
if output_fits(text, size.columns, max(0, size.rows - toolbar_height), chop=chop):
self.cmd.stdout.write(text)
self.cmd.stdout.flush()
return

pager = Pager(text, chop=chop)
pager.bindings.add(
"c-z",
filter=Condition(lambda: suspend_to_background_supported() and to_filter(self.cmd.main_session.enable_suspend)()),
)(self._suspend_binding)
layout = Layout(HSplit([pager.container, self.toolbar]), focused_element=pager.text)
previous = (self.app.layout, self.app.key_bindings, self.app.editing_mode, self.app.full_screen)
entered = False
# Open for as long as the pager has a screen of its own to erase.
own_screen = contextlib.ExitStack()

def enter() -> None:
nonlocal entered
entered = True
self.app.renderer.erase()
own_screen.enter_context(erasing_from_the_second_column(self.app.output))
self.app.layout = layout
self.app.key_bindings = pager.bindings
self.app.editing_mode = EditingMode.EMACS
self.app.full_screen = self.app.renderer.full_screen = True
self.app.invalidate()

def leave() -> None:
nonlocal entered
if not entered:
return
entered = False
try:
self.app.renderer.erase()
finally:
own_screen.close()
self.app.layout, self.app.key_bindings, self.app.editing_mode, self.app.full_screen = previous
self.app.renderer.full_screen = self.app.full_screen
self.app.renderer.request_absolute_cursor_position()
self.app.invalidate()

def close() -> None:
# Switch bindings before the next key is processed, preserving
# typeahead sent in the same terminal read as the pager's quit key.
leave()
pager.closed.set()

pager.on_close = close

try:
self._call_in_ui(enter)
while not pager.closed.wait(0.1):
self._check_running()
finally:
if self._thread is not None and self._thread.is_alive():
self._call_in_ui(leave)
else:
# The application's shutdown already reset the renderer.
own_screen.close()
self.app.layout, self.app.key_bindings, self.app.editing_mode, self.app.full_screen = previous
self.app.renderer.full_screen = self.app.full_screen

@contextlib.contextmanager
def suspend(self) -> Generator[None]:
"""Temporarily restore ordinary terminal access, including nested suspensions."""
Expand Down
Loading
Loading