Skip to content
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@
entries which are symbolic links to directories.
- `find_editor()` now finds the `edit` editor on Windows. It was the preferred default editor
there but could never be found because it was searched for without its `.exe` extension.
- `ppaged()` now prints its output when the configured pager program cannot be run, for example
where `less` is not installed. Previously only the shell's error was shown and the output was
lost. A pager command which could not be run is not tried again while the application is
running, so the shell's error is shown once for each pager command instead of every time.
- A command which prints through a `cmd2` console of its own, such as a `Cmd2GeneralConsole`
showing a Rich progress bar, no longer ends with a `BrokenPipeError` message when its output
is piped to something that exits early, as `head` does. `cmd2` now ends the command quietly
Expand Down
79 changes: 59 additions & 20 deletions cmd2/cmd2.py
Original file line number Diff line number Diff line change
Expand Up @@ -669,6 +669,9 @@ def __init__(
self.pager = "less -RXF"
self.pager_chop = "less -SRXF"

# Pager commands which the shell could not run. Each is tried, and reported by the shell, only once.
self._unrunnable_pagers: set[str] = set()

# This boolean flag stores whether cmd2 will allow clipboard related features
self.allow_clipboard = allow_clipboard

Expand Down Expand Up @@ -1961,6 +1964,31 @@ def pfeedback(
rich_print_kwargs=rich_print_kwargs,
)

@staticmethod
def _pager_failed_to_start(command: str, returncode: int) -> bool:
"""Return whether the shell could not run a pager at all, so that it showed nothing.

A pager which did run has had the output, whatever status it exited with.

:param command: the pager command given to the shell
:param returncode: the status the shell exited with
"""
if returncode == 0:
return False
if sys.platform.startswith("win"):
# cmd.exe exits with 1 for a command it cannot find, which a pager may also do for
# reasons of its own. Tell them apart by whether there is such a program.
import shlex
import shutil

try:
words = shlex.split(command, posix=False)
except ValueError:
return False
return bool(words) and shutil.which(words[0].strip('"')) is None
# What a POSIX shell exits with for a command it cannot find, or cannot execute.
return returncode in (126, 127)

def ppaged(
self,
*objects: Any,
Expand All @@ -1982,6 +2010,9 @@ 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`.

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.

: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
Expand All @@ -2007,11 +2038,12 @@ def ppaged(
# A pager application blocks, so only run one if not redirecting or running a script (either text or Python).
can_block = not (self._redirecting or self.in_pyscript() or self.in_script())

# Check if we are outputting to a pager.
if functional_terminal and can_block:
# Chopping overrides soft_wrap
if chop:
soft_wrap = True
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:
# Chopping overrides soft_wrap, but only for what the pager is given
pager_soft_wrap = soft_wrap or chop

# Generate the bytes to send to the pager
console = self._get_core_print_console(
Expand All @@ -2027,7 +2059,7 @@ def ppaged(
end=end,
style=style,
justify=justify,
soft_wrap=soft_wrap,
soft_wrap=pager_soft_wrap,
**(rich_print_kwargs if rich_print_kwargs is not None else {}),
)
# As for a pipe: the pager gets UTF-8, and on Windows the console is UTF-8 while it runs.
Expand All @@ -2039,7 +2071,7 @@ def ppaged(
import subprocess

pipe_proc = subprocess.Popen( # noqa: S602
self.pager_chop if chop else self.pager,
pager,
shell=True,
stdin=subprocess.PIPE,
stdout=self.stdout,
Expand All @@ -2064,19 +2096,26 @@ def ppaged(
except (OSError, termios.error):
pass

else:
self.poutput(
*objects,
sep=sep,
end=end,
style=style,
soft_wrap=soft_wrap,
justify=justify,
emoji=emoji,
markup=markup,
highlight=highlight,
rich_print_kwargs=rich_print_kwargs,
)
if not self._pager_failed_to_start(pager, pipe_proc.returncode):
return

# The shell has said why there is no pager. Remember that, so it is not asked every time.
# Nothing has been shown, so this once the objects are rendered a second time below.
self._unrunnable_pagers.add(pager)

# Nothing is paging the output, so print it.
self.poutput(
*objects,
sep=sep,
end=end,
style=style,
soft_wrap=soft_wrap,
justify=justify,
emoji=emoji,
markup=markup,
highlight=highlight,
rich_print_kwargs=rich_print_kwargs,
)

def ppretty(
self,
Expand Down
6 changes: 6 additions & 0 deletions docs/features/os.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,12 @@ system.

Output of any command can be displayed one page at a time using the [cmd2.Cmd.ppaged][] method.

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
it is not installed, the output is printed without paging. A pager command which could not be run is
not tried again while the application is running. `self.pager` and `self.pager_chop` are separate
commands, so the shell may report each of them once.

Alternatively, a terminal pager can be invoked directly using the ability to run shell commands with
the `!` shortcut like so:

Expand Down
134 changes: 134 additions & 0 deletions tests/test_cmd2.py
Original file line number Diff line number Diff line change
Expand Up @@ -4144,6 +4144,140 @@ def utf8_console():
assert events == ["utf-8 console", "pager started", "pager exited", "restored"]


class FakeTerminal(io.TextIOWrapper):
"""A real file which says it is a terminal, so that a pager's shell can be given it to write to."""

def isatty(self) -> bool:
return True


@pytest.fixture
def paging_app(outsim_app, monkeypatch, tmp_path):
"""An application which will page, and whatever reaches its terminal."""
stdin_mock = mock.MagicMock()
stdin_mock.isatty.return_value = True
monkeypatch.setattr(outsim_app, "stdin", stdin_mock)
if not sys.platform.startswith("win") and os.environ.get("TERM") is None:
monkeypatch.setenv("TERM", "simulated")
with FakeTerminal((tmp_path / "terminal").open("w+b"), encoding="utf-8") as terminal:
monkeypatch.setattr(outsim_app, "stdout", terminal)

def shown() -> str:
terminal.flush()
terminal.seek(0)
return terminal.read()

yield outsim_app, shown


@pytest.mark.parametrize("chop", [True, False])
def test_ppaged_shows_the_output_when_the_pager_cannot_be_run(paging_app, capfd, chop) -> None:
"""A pager which is not installed must not cost the user the output.

The shell reports the missing program and exits. Nothing has been shown by then, and
without the pager there is nobody else to show it.
"""
app, shown = paging_app
app.pager = app.pager_chop = "cmd2-no-such-pager-program --some-option"

app.ppaged("first line\nsecond line", chop=chop)

assert shown() == "first line\nsecond line\n"
# The shell said why there was no pager.
assert "cmd2-no-such-pager-program" in capfd.readouterr().err


def test_ppaged_without_a_pager_wraps_as_the_caller_asked(paging_app) -> None:
"""Chopping turns soft wrap on for a pager to scroll sideways. With no pager, the caller's choice stands."""
app, shown = paging_app
app.pager_chop = "cmd2-no-such-pager-program"

app.ppaged("word " * 400, chop=True, soft_wrap=False)

assert len(shown().splitlines()) > 1


def test_ppaged_does_not_repeat_output_after_a_pager_which_ran_and_failed(paging_app) -> None:
"""Only a pager which could not be started is made up for: one which ran has had the output."""
app, shown = paging_app
app.pager = f'"{sys.executable}" -c "import sys; sys.stdin.read(); sys.exit(1)"'

app.ppaged("first line\nsecond line")

assert shown() == ""


class RendersOnce:
"""A renderable which only has its lines to give the first time it is rendered."""

def __init__(self, *lines: str) -> None:
self._lines = iter(lines)

def __rich_console__(self, console, options):
yield from self._lines


def test_ppaged_does_not_try_again_a_pager_which_cannot_be_run(paging_app, capfd) -> None:
"""The shell says once that there is no such pager, not every time something is paged.

From then on nothing is rendered for a pager either, only for poutput().
"""
app, shown = paging_app
app.pager = "cmd2-no-such-pager-program"

app.ppaged("first")
assert "cmd2-no-such-pager-program" in capfd.readouterr().err

with mock.patch("subprocess.Popen") as popen_mock:
app.ppaged(RendersOnce("second"))

popen_mock.assert_not_called()
assert capfd.readouterr().err == ""
assert shown() == "first\nsecond\n"


def test_ppaged_tries_another_pager_after_one_which_cannot_be_run(paging_app) -> None:
"""Only the command which could not be run is given up on, so setting a pager which works is enough."""
app, shown = paging_app
app.pager = "cmd2-no-such-pager-program"
app.ppaged("unpaged")

app.pager = f'"{sys.executable}" -c "import sys; sys.stdout.write(sys.stdin.read().upper())"'
app.ppaged("paged")

assert shown() == "unpaged\nPAGED\n"


@pytest.mark.parametrize(
("platform", "command", "returncode", "found", "expected"),
[
pytest.param("linux", "less -RXF", 127, True, True, id="a POSIX shell found no such command"),
pytest.param("linux", "less -RXF", 126, True, True, id="a POSIX shell could not execute it"),
pytest.param("linux", "less -RXF", 1, False, False, id="a POSIX pager failed by itself"),
pytest.param("linux", "less -RXF", 0, False, False, id="a POSIX pager succeeded"),
pytest.param("win32", "less -RXF", 1, False, True, id="cmd.exe found no such command"),
pytest.param("win32", '"C:\\Program Files\\less.exe" -R', 1, False, True, id="cmd.exe found no such quoted path"),
pytest.param("win32", "more", 1, True, False, id="a Windows pager failed by itself"),
pytest.param("win32", "less -RXF", 0, False, False, id="a Windows pager succeeded"),
pytest.param("win32", 'less "unbalanced', 1, False, False, id="a Windows command which cannot be taken apart"),
pytest.param("win32", "", 1, False, False, id="no Windows command at all"),
],
)
def test_pager_failed_to_start(monkeypatch, platform, command, returncode, found, expected) -> None:
looked_for = []

def which(program: str) -> str | None:
looked_for.append(program)
return program if found else None

monkeypatch.setattr(sys, "platform", platform)
monkeypatch.setattr("shutil.which", which)

assert cmd2.Cmd._pager_failed_to_start(command, returncode) is expected
# A quoted program is looked for by its name, not with its quotes.
assert all(not program.startswith('"') for program in looked_for)


def test_ppaged_no_pager(outsim_app) -> None:
"""Since we're not in a fully-functional terminal, ppaged() will just call poutput()."""
msg = "testing..."
Expand Down
Loading