diff --git a/CHANGELOG.md b/CHANGELOG.md index 9cbe3abe4..34f1bd971 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index c0c1be687..5adb6ba6a 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -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 @@ -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, @@ -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 @@ -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( @@ -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. @@ -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, @@ -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, diff --git a/docs/features/os.md b/docs/features/os.md index 444822fd6..7d6489bc4 100644 --- a/docs/features/os.md +++ b/docs/features/os.md @@ -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: diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py index 4840b6ecd..7e79174bb 100644 --- a/tests/test_cmd2.py +++ b/tests/test_cmd2.py @@ -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..."