From b804011d53c467ef5c7a012d487253d51470fd63 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:23:30 -0500 Subject: [PATCH 01/11] Document how to update output in place with the print methods Rich strips carriage returns and a few other control characters from the strings it renders, so a '\r' embedded in a string passed to poutput() is dropped. Explain this and show the supported alternatives: a Rich status or live display on a console writing to self.stdout, or passing the carriage return in the end parameter. --- docs/features/generating_output.md | 57 ++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index 0cb791dc3..dba724adf 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -69,6 +69,63 @@ def do_echo(self, args): self.poutput(args) ``` +## Updating Output in Place + +Countdowns, progress indicators, and status lines repeatedly overwrite the same line of the +terminal. The traditional way to do that with `print()` is to embed a carriage return (`\r`) in the +string, but that does not work with `poutput` or any of the other `cmd2` print methods. `rich` +removes the carriage return, backspace, bell, vertical tab, and form feed characters from every +string it renders because they would break its width calculations. Each update is then appended to +the line instead of overwriting it. + +The recommended approach is to let `rich` manage the cursor with a +[status](https://rich.readthedocs.io/en/stable/console.html#status) or +[live display](https://rich.readthedocs.io/en/stable/live.html) attached to a console which writes +to `self.stdout`: + +```py +import time + +from cmd2.rich_utils import Cmd2GeneralConsole + + +def do_countdown(self, _): + """Count down from 5 on a single line""" + console = Cmd2GeneralConsole(file=self.stdout) + with console.status("Starting...") as status: + for remaining in range(5, 0, -1): + status.update(f"Time remaining: {remaining}s") + time.sleep(1) + self.poutput("Done!") +``` + +The status line disappears when the `with` block exits, and nothing is written for it when the +output of the command is redirected to a file or piped to a shell command. Use +`rich.live.Live(console=console, transient=True)` in the same way to update any `rich` renderable in +place without a spinner. + +If you would rather write the escape sequences yourself, put the carriage return in the `end` +parameter, which is written exactly as given: + +```py +CLEAR_LINE = "\x1b[2K" + + +def do_countdown(self, _): + """Count down from 5 on a single line""" + for remaining in range(5, 0, -1): + self.poutput(f"{CLEAR_LINE}Time remaining: {remaining}s", end="\r") + time.sleep(1) + self.poutput(f"{CLEAR_LINE}Done!") +``` + +Unlike the `rich` status and live displays, this writes the escape sequences and carriage returns to +the file or pipe when the output of the command is redirected. + +The print methods flush the stream after every call, so there is no `flush` parameter to pass. +Strings written directly to `self.stdout` are not processed by `rich`, so control characters in them +are left alone. + ## Error Messages When an error occurs in your program, you can display it on `sys.stderr` by calling the From d665ac8e9f90c2b623c3d22e301076f2abfa685e Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:58:02 -0500 Subject: [PATCH 02/11] Add a Rich progress bar example and document it Add examples/rich_progress.py, which shows a status spinner, a progress bar with messages printed above it, several simultaneous bars with custom columns, and rich.progress.track() inside cmd2 commands. Split the 'Updating Output in Place' documentation into status message, progress bar, and carriage return subsections, and explain how to print while a bar is active and what is written when output is redirected. --- docs/features/generating_output.md | 61 ++++++++++++++-- examples/README.md | 3 + examples/rich_progress.py | 111 +++++++++++++++++++++++++++++ 3 files changed, 169 insertions(+), 6 deletions(-) create mode 100755 examples/rich_progress.py diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index dba724adf..fb37365a0 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -78,10 +78,17 @@ removes the carriage return, backspace, bell, vertical tab, and form feed charac string it renders because they would break its width calculations. Each update is then appended to the line instead of overwriting it. -The recommended approach is to let `rich` manage the cursor with a -[status](https://rich.readthedocs.io/en/stable/console.html#status) or -[live display](https://rich.readthedocs.io/en/stable/live.html) attached to a console which writes -to `self.stdout`: +`rich` can manage the cursor for you instead. Its status spinners, progress bars, and live displays +all work inside a command when you give them a console which writes to `self.stdout`. Create one +with [Cmd2GeneralConsole][cmd2.rich_utils.Cmd2GeneralConsole] so the display honors output +redirection, the [allow_style](./settings.md#allow_style) setting, and the `cmd2` theme. The +[rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py) example +demonstrates everything described below. + +### Status Messages + +For work of an unknown length, show a spinner and a message with a +[status](https://rich.readthedocs.io/en/stable/console.html#status): ```py import time @@ -104,6 +111,48 @@ output of the command is redirected to a file or piped to a shell command. Use `rich.live.Live(console=console, transient=True)` in the same way to update any `rich` renderable in place without a spinner. +### Progress Bars + +When you know how much work there is, show a +[progress bar](https://rich.readthedocs.io/en/stable/progress.html): + +```py +import time + +from rich.progress import Progress + +from cmd2.rich_utils import Cmd2GeneralConsole + + +def do_process(self, _): + """Process some files while showing a progress bar""" + files = [f"file_{i}.dat" for i in range(1, 11)] + console = Cmd2GeneralConsole(file=self.stdout) + with Progress(console=console) as progress: + task_id = progress.add_task("Processing files", total=len(files)) + for file in files: + time.sleep(0.4) + progress.console.print(f"Processed {file}") + progress.advance(task_id) + self.poutput("All files processed.") +``` + +A few things to know when using a progress bar in a command: + +- While the bar is active, print with `progress.console.print()` as shown above. The message then + appears above the bar. `poutput` does not know about the bar and writes on top of it. Once the + `with` block exits, `poutput` is safe to use again. +- The finished bar is left on the screen. Pass `transient=True` to `Progress` to erase it instead. +- Call `add_task` more than once to show several bars at the same time, and pass + [columns](https://rich.readthedocs.io/en/stable/progress.html#columns) to `Progress` to change + what is shown for each one. +- To add a bar to a simple loop, wrap the sequence being iterated over with + `rich.progress.track(sequence, console=console)`. +- When the output of the command is redirected to a file or piped to a shell command, the bar is not + animated. Only its final state is written, or nothing but a blank line if it is transient. + +### Carriage Returns + If you would rather write the escape sequences yourself, put the carriage return in the `end` parameter, which is written exactly as given: @@ -119,8 +168,8 @@ def do_countdown(self, _): self.poutput(f"{CLEAR_LINE}Done!") ``` -Unlike the `rich` status and live displays, this writes the escape sequences and carriage returns to -the file or pipe when the output of the command is redirected. +Unlike the `rich` displays, this writes the escape sequences and carriage returns to the file or +pipe when the output of the command is redirected. The print methods flush the stream after every call, so there is no `flush` parameter to pass. Strings written directly to `self.stdout` are not processed by `rich`, so control characters in them diff --git a/examples/README.md b/examples/README.md index 96a6291dc..128080a32 100644 --- a/examples/README.md +++ b/examples/README.md @@ -88,6 +88,9 @@ each: - [remove_settable.py](https://github.com/python-cmd2/cmd2/blob/main/examples/remove_settable.py) - Shows how to remove any of the built-in cmd2 `Settables` you do not want in your cmd2 application +- [rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py) + - Shows how to use Rich progress bars and status spinners to display the progress of + long-running commands - [rich_tables.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_tables.py) - Example of using Rich Tables within a cmd2 application for displaying tabular data - [rich_theme.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_theme.py) diff --git a/examples/rich_progress.py b/examples/rich_progress.py new file mode 100755 index 000000000..fe90f4bd4 --- /dev/null +++ b/examples/rich_progress.py @@ -0,0 +1,111 @@ +#!/usr/bin/env python3 +"""An example of using Rich to show the progress and status of long-running commands in a cmd2 application. + +Rich's spinners and progress bars repeatedly redraw the same lines of the terminal. To use them in a +cmd2 command, give them a console which writes to ``self.stdout``. They then honor output redirection, +the ``allow_style`` setting, and the cmd2 theme like the rest of your command's output. + +The commands in this example are: + +- ``status`` - a spinner with a status message, for work of an unknown length +- ``progress`` - a progress bar with messages printed above it while it is running +- ``downloads`` - several progress bars with custom columns updating at the same time +- ``track`` - the shortest way to add a progress bar to a loop + +Pressing Ctrl-C while any of them is running stops the display and restores the cursor. Redirect +their output to a file (e.g. ``progress > out.txt``) to see that the animation is left out of it. +""" + +import time + +from rich.progress import ( + BarColumn, + DownloadColumn, + Progress, + TextColumn, + TimeRemainingColumn, + TransferSpeedColumn, + track, +) + +import cmd2 +from cmd2.rich_utils import Cmd2GeneralConsole + +# Name, size in bytes, and bytes received per update for each simulated download +DOWNLOADS = [ + ("cmd2.tar.gz", 2_000_000, 50_000), + ("rich.tar.gz", 6_000_000, 100_000), + ("prompt_toolkit.tar.gz", 4_000_000, 40_000), +] + + +class ProgressApp(cmd2.Cmd): + """Example cmd2 application which shows the progress and status of long-running commands.""" + + def __init__(self) -> None: + super().__init__() + self.intro = "Run the status, progress, downloads, and track commands to see Rich progress displays." + + def _create_console(self) -> Cmd2GeneralConsole: + """Create a Rich console which writes to the same place as poutput().""" + return Cmd2GeneralConsole(file=self.stdout) + + def do_status(self, _: cmd2.Statement) -> None: + """Show a spinner and a status message while doing work of an unknown length.""" + console = self._create_console() + with console.status("Starting...") as status: + for step in ("Connecting to the server", "Authenticating", "Fetching data"): + status.update(f"{step}...") + time.sleep(1.5) + + # The status line is erased when the with block exits + self.poutput("Data fetched.") + + def do_progress(self, _: cmd2.Statement) -> None: + """Show a progress bar and print messages above it while it is running.""" + files = [f"file_{i}.dat" for i in range(1, 11)] + + with Progress(console=self._create_console()) as progress: + task_id = progress.add_task("Processing files", total=len(files)) + for file in files: + time.sleep(0.4) + + # While the progress bar is active, print through its console so the message + # appears above the bar. poutput() does not know about the bar and would write + # on top of it. + progress.console.print(f"Processed {file}") + progress.advance(task_id) + + # The finished bar is left on the screen. Once the with block exits, poutput() is safe again. + self.poutput("All files processed.") + + def do_downloads(self, _: cmd2.Statement) -> None: + """Show several progress bars with custom columns updating at the same time.""" + with Progress( + TextColumn("{task.description}", style=cmd2.Color.CYAN), + BarColumn(), + DownloadColumn(), + TransferSpeedColumn(), + TimeRemainingColumn(), + console=self._create_console(), + # Erase the progress bars when the with block exits + transient=True, + ) as progress: + chunk_sizes = {progress.add_task(name, total=size): chunk_size for name, size, chunk_size in DOWNLOADS} + + while not progress.finished: + time.sleep(0.05) + for task_id, chunk_size in chunk_sizes.items(): + progress.advance(task_id, chunk_size) + + self.poutput(f"Downloaded {len(DOWNLOADS)} files.") + + def do_track(self, _: cmd2.Statement) -> None: + """Add a progress bar to a loop with a single function call.""" + for _number in track(range(40), description="Crunching numbers", console=self._create_console()): + time.sleep(0.05) + + +if __name__ == "__main__": + app = ProgressApp() + app.cmdloop() From b65f19616843c00a47e2a7a4b0b4b92e69bafee9 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:23:06 -0500 Subject: [PATCH 03/11] Mention progress bars in the README --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ce9464121..6fc7e4b29 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,9 @@ to build a more complete application. arguments and subcommands, or plain type hints via [`@with_annotated`](https://cmd2.readthedocs.io/en/latest/features/annotated/). A single parser definition drives validation, help, and completion. -- Render Rich tables and other styled objects, with consistent helpers for +- Render Rich tables, + [progress bars](https://cmd2.readthedocs.io/en/latest/features/generating_output/#progress-bars), + and other styled objects, with consistent helpers for [normal output, errors, warnings, and paging](https://cmd2.readthedocs.io/en/latest/features/generating_output/). - Organize large applications into independently testable and dynamically loadable [CommandSets](https://cmd2.readthedocs.io/en/latest/features/modular_commands/), and customize the From 703ea49f933b765894973040f1e56a4745ee845e Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:34:47 -0500 Subject: [PATCH 04/11] Address review findings in the progress example and documentation - Stop advancing finished tasks in the downloads command, which showed more bytes received than the size of the file - Handle BrokenPipeError in the progress command when its output is piped to a command which exits early - Document how Rich status and progress displays differ from the print methods: animation depends on allow_style, their text is parsed as markup, and they do not handle broken pipes - Drop the Live recommendation, which truncates wrapped renderables on a soft-wrapping console - Note that the carriage return recipe is for strings without ANSI style sequences - Add a CHANGELOG entry for the new example and documentation --- CHANGELOG.md | 11 +++++++ docs/features/generating_output.md | 49 +++++++++++++++++++++--------- examples/rich_progress.py | 31 +++++++++++-------- 3 files changed, 64 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2046f23fc..ef01fec84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ +## 4.4.3 (TBD) + +- Enhancements + - Added the + [rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py) + example, which shows how to display the progress of long-running commands with Rich status + spinners and progress bars. See the new + [Updating Output in Place](docs/features/generating_output.md#updating-output-in-place) + documentation for details, including why a carriage return embedded in a string passed to + `poutput()` does not move the cursor. + ## 4.4.2 (November 11, 2026) - Security diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index fb37365a0..53a91d12d 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -75,13 +75,13 @@ Countdowns, progress indicators, and status lines repeatedly overwrite the same terminal. The traditional way to do that with `print()` is to embed a carriage return (`\r`) in the string, but that does not work with `poutput` or any of the other `cmd2` print methods. `rich` removes the carriage return, backspace, bell, vertical tab, and form feed characters from every -string it renders because they would break its width calculations. Each update is then appended to -the line instead of overwriting it. +string it renders because they would break its width calculations, so the cursor never returns to +the start of the line. -`rich` can manage the cursor for you instead. Its status spinners, progress bars, and live displays -all work inside a command when you give them a console which writes to `self.stdout`. Create one -with [Cmd2GeneralConsole][cmd2.rich_utils.Cmd2GeneralConsole] so the display honors output -redirection, the [allow_style](./settings.md#allow_style) setting, and the `cmd2` theme. The +`rich` can manage the cursor for you instead. Its status spinners and progress bars work inside a +command when you give them a console which writes to `self.stdout`. Create one with +[Cmd2GeneralConsole][cmd2.rich_utils.Cmd2GeneralConsole] so the display uses the `cmd2` theme and +follows the [allow_style](./settings.md#allow_style) setting. The [rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py) example demonstrates everything described below. @@ -106,10 +106,7 @@ def do_countdown(self, _): self.poutput("Done!") ``` -The status line disappears when the `with` block exits, and nothing is written for it when the -output of the command is redirected to a file or piped to a shell command. Use -`rich.live.Live(console=console, transient=True)` in the same way to update any `rich` renderable in -place without a spinner. +The status line disappears when the `with` block exits. ### Progress Bars @@ -148,13 +145,31 @@ A few things to know when using a progress bar in a command: what is shown for each one. - To add a bar to a simple loop, wrap the sequence being iterated over with `rich.progress.track(sequence, console=console)`. -- When the output of the command is redirected to a file or piped to a shell command, the bar is not - animated. Only its final state is written, or nothing but a blank line if it is transient. + +### Styles, Redirection, and Markup + +Status messages and progress bars differ from the print methods in a few ways: + +- **They are only animated where `allow_style` allows it.** With the default setting of `Terminal`, + they are animated on a terminal. When the output of the command is redirected to a file or piped + to a shell command, a status writes nothing and a progress bar writes only its final state, or + just a blank line if it is transient. With `Never`, that is what happens on a terminal too. With + `Always`, redirected output also contains the escape sequences which hide and show the cursor and + style the bar. +- **Their text is parsed as [console markup](https://rich.readthedocs.io/en/stable/markup.html).** + This applies to status messages and to the descriptions of progress bar tasks, even though markup + is off by default in the print methods. If the text could contain square brackets, as a file name + can, pass it through `rich.markup.escape()` first. Otherwise `report[draft].txt` is displayed as + `report.txt`, and an unmatched closing tag such as `[/b]` raises a `MarkupError`. +- **They do not handle broken pipes.** `poutput` quietly ignores the `BrokenPipeError` which occurs + when output is piped to a shell command that exits early, such as `head`. Anything written by a + console you created raises it instead. Catch `BrokenPipeError` around the `with` block if your + command prints through the console while it is running. ### Carriage Returns If you would rather write the escape sequences yourself, put the carriage return in the `end` -parameter, which is written exactly as given: +parameter, which `rich` does not strip: ```py CLEAR_LINE = "\x1b[2K" @@ -168,8 +183,12 @@ def do_countdown(self, _): self.poutput(f"{CLEAR_LINE}Done!") ``` -Unlike the `rich` displays, this writes the escape sequences and carriage returns to the file or -pipe when the output of the command is redirected. +Use the `style` parameter if you want to color text printed this way. A string which already +contains ANSI style sequences is parsed as ANSI text, which discards every other kind of escape +sequence in it, including the one that clears the line. + +Unlike the `rich` displays, this always writes the escape sequences and carriage returns, including +when the output of the command is redirected to a file or pipe. The print methods flush the stream after every call, so there is no `flush` parameter to pass. Strings written directly to `self.stdout` are not processed by `rich`, so control characters in them diff --git a/examples/rich_progress.py b/examples/rich_progress.py index fe90f4bd4..321be8dbd 100755 --- a/examples/rich_progress.py +++ b/examples/rich_progress.py @@ -65,16 +65,22 @@ def do_progress(self, _: cmd2.Statement) -> None: """Show a progress bar and print messages above it while it is running.""" files = [f"file_{i}.dat" for i in range(1, 11)] - with Progress(console=self._create_console()) as progress: - task_id = progress.add_task("Processing files", total=len(files)) - for file in files: - time.sleep(0.4) - - # While the progress bar is active, print through its console so the message - # appears above the bar. poutput() does not know about the bar and would write - # on top of it. - progress.console.print(f"Processed {file}") - progress.advance(task_id) + try: + with Progress(console=self._create_console()) as progress: + task_id = progress.add_task("Processing files", total=len(files)) + for file in files: + time.sleep(0.4) + + # While the progress bar is active, print through its console so the message + # appears above the bar. poutput() does not know about the bar and would write + # on top of it. + progress.console.print(f"Processed {file}") + progress.advance(task_id) + except BrokenPipeError: + # The output was piped to a shell command which exited before reading all of it + # (e.g. "progress | head -n 2"). poutput() ignores this error for you, but output + # printed through a console you created does not. + return # The finished bar is left on the screen. Once the with block exits, poutput() is safe again. self.poutput("All files processed.") @@ -95,8 +101,9 @@ def do_downloads(self, _: cmd2.Statement) -> None: while not progress.finished: time.sleep(0.05) - for task_id, chunk_size in chunk_sizes.items(): - progress.advance(task_id, chunk_size) + for task in progress.tasks: + if not task.finished: + progress.advance(task.id, chunk_sizes[task.id]) self.poutput(f"Downloaded {len(DOWNLOADS)} files.") From 01996ab8f5be537287827b7c177d517b0caabf49 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:56:33 -0500 Subject: [PATCH 05/11] Handle BrokenPipeError which escapes a piped command The print methods ignore the BrokenPipeError raised when a command's output is piped to a shell command which exits early, but a command which writes to self.stdout another way, such as with its own Rich console, let it escape and ended with an error message. Handle it in onecmd_plus_hooks() the way print_to() does, honoring broken_pipe_warning. This applies only while self.stdout is a pipe to a shell command, including for commands run by a piped command such as run_script, so a BrokenPipeError from something else a command did is still reported. --- CHANGELOG.md | 6 ++++ cmd2/cmd2.py | 24 ++++++++++++++ tests/test_cmd2.py | 79 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 109 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ef01fec84..c7d8337b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ ## 4.4.3 (TBD) +- Bug Fixes + - A `BrokenPipeError` which escapes a command whose output is piped to a shell command is now + handled the way `poutput()` handles it: it is ignored, or `broken_pipe_warning` is printed if + set. Previously a command which wrote to `self.stdout` without using one of the print methods, + with its own Rich console for instance, ended with a `BrokenPipeError` message when the shell + command exited early, as `head` does. - Enhancements - Added the [rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py) diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 2ae2937ce..6d13ca01f 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -610,6 +610,10 @@ def __init__( # Used to keep track of whether we are redirecting or piping output self._redirecting = False + # True while self.stdout is a pipe to a shell command, whether the current command set up that pipe + # or a command which is running it did + self._stdout_is_pipe = False + # Set text which prints right before all of the help tables are listed. self.doc_leader = "" @@ -3032,6 +3036,11 @@ def onecmd_plus_hooks( stop = False statement = None + # Whether the command's output goes to a pipe. Kept here as well as in self._stdout_is_pipe, + # which is back to what it was for the caller by the time an exception is handled. + piping = False + saved_stdout_is_pipe = self._stdout_is_pipe + try: # Convert the line into a Statement statement = self._input_line_to_statement(line) @@ -3062,6 +3071,11 @@ def onecmd_plus_hooks( redir_saved_state = self._redirect_output(statement) + # A command which does not redirect its output writes wherever its caller's goes + if redir_saved_state.redirecting: + self._stdout_is_pipe = self._cur_pipe_proc_reader is not None + piping = self._stdout_is_pipe + timestart = dt.datetime.now(tz=dt.timezone.utc) # precommand hooks @@ -3092,6 +3106,7 @@ def onecmd_plus_hooks( finally: # Get sigint protection while we restore stuff with self.sigint_protection: + self._stdout_is_pipe = saved_stdout_is_pipe if redir_saved_state is not None: self._restore_output(statement, redir_saved_state) @@ -3114,6 +3129,15 @@ def onecmd_plus_hooks( stop = True except PassThroughException as ex: raise ex.wrapped_ex from None + except BrokenPipeError as ex: + # The print methods handle this in print_to(). A command which writes to self.stdout + # some other way, such as with its own Rich console, lets it escape when the shell + # command its output is piped to exits early. Treat that the same way. Without a + # pipe, the error came from something else the command did and is reported as usual. + if not piping: + self.pexcept(ex) + elif self.broken_pipe_warning: + Cmd2GeneralConsole(file=sys.stderr).print(self.broken_pipe_warning) except Exception as ex: # noqa: BLE001 self.pexcept(ex) finally: diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py index 01efe8de7..2311d616d 100644 --- a/tests/test_cmd2.py +++ b/tests/test_cmd2.py @@ -967,6 +967,85 @@ def test_pipe_to_shell_and_redirect(redirection_app, running_pipe_process) -> No os.remove(filename) +class BrokenPipeApp(cmd2.Cmd): + """Commands which hit a broken pipe without going through one of cmd2's print methods.""" + + def do_own_console(self, _: str) -> None: + """Print through a console of its own until the consumer of its output exits.""" + console = ru.Cmd2GeneralConsole(file=self.stdout) + + # More than fits in a pipe, so the command is still writing when the consumer exits + for _line in range(4096): + console.print("x" * 1024) + self.perror("the pipe never broke") + + def do_raise_broken_pipe(self, _: str) -> None: + """Raise the error a write to a closed pipe or socket raises.""" + raise BrokenPipeError + + +@pytest.fixture +def broken_pipe_app() -> BrokenPipeApp: + return BrokenPipeApp() + + +@pytest.mark.skipif(sys.platform == "win32", reason="a write to a closed pipe raises a different OSError on Windows") +def test_broken_pipe_from_a_commands_own_console_is_ignored(broken_pipe_app) -> None: + """A consumer which exits early ends the command quietly, as it does for one which uses poutput().""" + consumer = f'{sys.executable} -c "import time; time.sleep(0.5)"' + out, err = run_cmd(broken_pipe_app, f"own_console | {consumer}") + assert not out + assert not err + + +def test_broken_pipe_raised_by_a_piped_command_is_ignored(broken_pipe_app, running_pipe_process) -> None: + out, err = run_cmd(broken_pipe_app, "raise_broken_pipe | sort") + assert not out + assert not err + + +def test_broken_pipe_raised_by_a_piped_command_prints_the_warning(broken_pipe_app, running_pipe_process) -> None: + broken_pipe_app.broken_pipe_warning = "The pipe broke" + out, err = run_cmd(broken_pipe_app, "raise_broken_pipe | sort") + assert not out + assert err == ["The pipe broke"] + + +def test_broken_pipe_raised_by_a_command_in_a_piped_script_is_ignored(broken_pipe_app, tmp_path, running_pipe_process) -> None: + """A command which does not redirect its own output writes to the pipe of the command running it.""" + script = tmp_path / "script.txt" + script.write_text("raise_broken_pipe\n") + out, err = run_cmd(broken_pipe_app, f"run_script {script} | sort") + assert not out + assert not err + + +def test_broken_pipe_raised_by_a_redirected_command_in_a_piped_script_is_reported( + broken_pipe_app, tmp_path, running_pipe_process +) -> None: + """A command which redirects its output to a file does not write to the pipe of the command running it.""" + script = tmp_path / "script.txt" + script.write_text(f"raise_broken_pipe > {tmp_path / 'out.txt'}\n") + _out, err = run_cmd(broken_pipe_app, f"run_script {script} | sort") + assert "BrokenPipeError" in err[0] + + +def test_broken_pipe_raised_after_a_piped_command_is_reported(broken_pipe_app, running_pipe_process) -> None: + """The pipe of one command does not hide the error for the commands which follow it.""" + run_cmd(broken_pipe_app, "raise_broken_pipe | sort") + _out, err = run_cmd(broken_pipe_app, "raise_broken_pipe") + assert "BrokenPipeError" in err[0] + + +@pytest.mark.parametrize("redirection", ["", " > {file}"]) +def test_broken_pipe_raised_by_a_command_which_is_not_piped_is_reported(broken_pipe_app, tmp_path, redirection) -> None: + """Without a pipe the error did not come from the command's output, so it is not hidden.""" + broken_pipe_app.broken_pipe_warning = "The pipe broke" + _out, err = run_cmd(broken_pipe_app, "raise_broken_pipe" + redirection.format(file=tmp_path / "out.txt")) + assert "BrokenPipeError" in err[0] + assert "The pipe broke" not in err + + @pytest.mark.parametrize( "terminal", [False, pytest.param(True, marks=pytest.mark.skipif(sys.platform == "win32", reason="POSIX terminal job control"))], From cf7af12c62c88be1cc63d1f14a3963f72fa6bb3f Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:56:34 -0500 Subject: [PATCH 06/11] Address second round of review findings in the progress docs and example - Drop the broken pipe caveat and the example's handler now that cmd2 handles it for any piped command - Document that status and task text also gets emoji codes replaced, and recommend Text objects and TextColumn(markup=False) rather than escape() - Describe what the print methods actually do to an active progress bar - Note that direct writes to self.stdout need a flush - Keep each download's chunk size in its task's fields - Add the missing import to the carriage return snippet --- docs/features/generating_output.md | 33 +++++++++++++++----------- examples/rich_progress.py | 37 +++++++++++++++--------------- 2 files changed, 37 insertions(+), 33 deletions(-) diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index 53a91d12d..36a9adaf7 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -56,7 +56,9 @@ conveniences: 1. Since users can pipe output to a shell command, it catches `BrokenPipeError` and outputs the contents of `self.broken_pipe_warning` to `stderr`. `self.broken_pipe_warning` defaults to an empty string so this method will just swallow the exception. If you want to show an error - message, put it in `self.broken_pipe_warning` when you initialize `cmd2.Cmd`. + message, put it in `self.broken_pipe_warning` when you initialize `cmd2.Cmd`. A command which + writes to `self.stdout` some other way gets the same treatment when its output is piped to a + shell command: `cmd2` handles a `BrokenPipeError` which escapes it. 2. It examines and honors the [allow_style](./settings.md#allow_style) setting. See [Colored Output](#colored-output) below for more details. 3. It allows printing arbitrary `rich` renderable objects which can get visually quite complex. @@ -137,8 +139,9 @@ def do_process(self, _): A few things to know when using a progress bar in a command: - While the bar is active, print with `progress.console.print()` as shown above. The message then - appears above the bar. `poutput` does not know about the bar and writes on top of it. Once the - `with` block exits, `poutput` is safe to use again. + appears above the bar. `poutput` and the other print methods do not know about the bar: their + output lands on the end of its line and a stale copy of the bar is left behind. Once the `with` + block exits, they are safe to use again. - The finished bar is left on the screen. Pass `transient=True` to `Progress` to erase it instead. - Call `add_task` more than once to show several bars at the same time, and pass [columns](https://rich.readthedocs.io/en/stable/progress.html#columns) to `Progress` to change @@ -148,7 +151,7 @@ A few things to know when using a progress bar in a command: ### Styles, Redirection, and Markup -Status messages and progress bars differ from the print methods in a few ways: +Status messages and progress bars differ from the print methods in two ways: - **They are only animated where `allow_style` allows it.** With the default setting of `Terminal`, they are animated on a terminal. When the output of the command is redirected to a file or piped @@ -156,15 +159,14 @@ Status messages and progress bars differ from the print methods in a few ways: just a blank line if it is transient. With `Never`, that is what happens on a terminal too. With `Always`, redirected output also contains the escape sequences which hide and show the cursor and style the bar. -- **Their text is parsed as [console markup](https://rich.readthedocs.io/en/stable/markup.html).** - This applies to status messages and to the descriptions of progress bar tasks, even though markup - is off by default in the print methods. If the text could contain square brackets, as a file name - can, pass it through `rich.markup.escape()` first. Otherwise `report[draft].txt` is displayed as - `report.txt`, and an unmatched closing tag such as `[/b]` raises a `MarkupError`. -- **They do not handle broken pipes.** `poutput` quietly ignores the `BrokenPipeError` which occurs - when output is piped to a shell command that exits early, such as `head`. Anything written by a - console you created raises it instead. Catch `BrokenPipeError` around the `with` block if your - command prints through the console while it is running. +- **Their text is parsed as [console markup](https://rich.readthedocs.io/en/stable/markup.html).** A + status message or the description of a progress bar task is searched for markup tags such as + `[bold]` and emoji codes such as `:warning:`, even though both are off by default in the print + methods. So `report[draft].txt` is displayed as `report.txt`, `user:id:42` as `user🆔42`, and an + unmatched closing tag such as `[/b]` raises a `MarkupError`. To display text you do not control, + such as a file name, exactly as it is, give a status a `rich.text.Text` object instead of a + string, and show task descriptions with a `TextColumn("{task.description}", markup=False)` + [column](https://rich.readthedocs.io/en/stable/progress.html#columns). ### Carriage Returns @@ -172,6 +174,8 @@ If you would rather write the escape sequences yourself, put the carriage return parameter, which `rich` does not strip: ```py +import time + CLEAR_LINE = "\x1b[2K" @@ -192,7 +196,8 @@ when the output of the command is redirected to a file or pipe. The print methods flush the stream after every call, so there is no `flush` parameter to pass. Strings written directly to `self.stdout` are not processed by `rich`, so control characters in them -are left alone. +are left alone. They are not flushed either, so call `self.stdout.flush()` after writing a line +which does not end with a newline. ## Error Messages diff --git a/examples/rich_progress.py b/examples/rich_progress.py index 321be8dbd..9c6ca0639 100755 --- a/examples/rich_progress.py +++ b/examples/rich_progress.py @@ -65,22 +65,17 @@ def do_progress(self, _: cmd2.Statement) -> None: """Show a progress bar and print messages above it while it is running.""" files = [f"file_{i}.dat" for i in range(1, 11)] - try: - with Progress(console=self._create_console()) as progress: - task_id = progress.add_task("Processing files", total=len(files)) - for file in files: - time.sleep(0.4) - - # While the progress bar is active, print through its console so the message - # appears above the bar. poutput() does not know about the bar and would write - # on top of it. - progress.console.print(f"Processed {file}") - progress.advance(task_id) - except BrokenPipeError: - # The output was piped to a shell command which exited before reading all of it - # (e.g. "progress | head -n 2"). poutput() ignores this error for you, but output - # printed through a console you created does not. - return + with Progress(console=self._create_console()) as progress: + task_id = progress.add_task("Processing files", total=len(files)) + for file in files: + time.sleep(0.4) + + # While the progress bar is active, print through its console so the message + # appears above the bar. poutput() and the other print methods do not know about + # the bar: their output lands on the end of its line and a stale copy of the bar + # is left behind. + progress.console.print(f"Processed {file}") + progress.advance(task_id) # The finished bar is left on the screen. Once the with block exits, poutput() is safe again. self.poutput("All files processed.") @@ -88,7 +83,9 @@ def do_progress(self, _: cmd2.Statement) -> None: def do_downloads(self, _: cmd2.Statement) -> None: """Show several progress bars with custom columns updating at the same time.""" with Progress( - TextColumn("{task.description}", style=cmd2.Color.CYAN), + # Task descriptions are parsed as Rich markup unless the column which shows them says otherwise. + # File names can contain square brackets, so show them exactly as they are. + TextColumn("{task.description}", style=cmd2.Color.CYAN, markup=False), BarColumn(), DownloadColumn(), TransferSpeedColumn(), @@ -97,13 +94,15 @@ def do_downloads(self, _: cmd2.Statement) -> None: # Erase the progress bars when the with block exits transient=True, ) as progress: - chunk_sizes = {progress.add_task(name, total=size): chunk_size for name, size, chunk_size in DOWNLOADS} + for name, size, chunk_size in DOWNLOADS: + # Extra keyword arguments are stored in the task's fields + progress.add_task(name, total=size, chunk_size=chunk_size) while not progress.finished: time.sleep(0.05) for task in progress.tasks: if not task.finished: - progress.advance(task.id, chunk_sizes[task.id]) + progress.advance(task.id, task.fields["chunk_size"]) self.poutput(f"Downloaded {len(DOWNLOADS)} files.") From 7e57d822df094804866dd07cd226f2afc4047b2e Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 16:03:03 -0500 Subject: [PATCH 07/11] Use a non-Python consumer in the broken pipe test Coverage starts in Python subprocesses and, on Python 3.11, warns on stderr that it cannot use the sysmon core. The test asserts that nothing is written to stderr, so it failed there. --- tests/test_cmd2.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py index 2311d616d..b3faf44af 100644 --- a/tests/test_cmd2.py +++ b/tests/test_cmd2.py @@ -992,8 +992,9 @@ def broken_pipe_app() -> BrokenPipeApp: @pytest.mark.skipif(sys.platform == "win32", reason="a write to a closed pipe raises a different OSError on Windows") def test_broken_pipe_from_a_commands_own_console_is_ignored(broken_pipe_app) -> None: """A consumer which exits early ends the command quietly, as it does for one which uses poutput().""" - consumer = f'{sys.executable} -c "import time; time.sleep(0.5)"' - out, err = run_cmd(broken_pipe_app, f"own_console | {consumer}") + # The consumer must outlive the check that it started, and is not a Python process, which could write + # warnings of its own to stderr: coverage does when it starts in a subprocess on Python 3.11. + out, err = run_cmd(broken_pipe_app, "own_console | sleep 0.5") assert not out assert not err From 1d02b2b8baadc1d4d88b673029917c1b7395bd0f Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 16:31:34 -0500 Subject: [PATCH 08/11] Mark broken pipes where a cmd2 console raises them Deciding whether to swallow a BrokenPipeError by whether the command's output was piped hid unrelated errors, such as one from a socket, made a failed app() call in a piped pyscript look successful, and did not cover an application whose own stdout is a pipe. Cmd2BaseConsole.on_broken_pipe() now raises ConsoleBrokenPipeError, a BrokenPipeError subclass, and onecmd_plus_hooks() handles only that. It needs no state about redirection, and any other BrokenPipeError which escapes a command is reported as before. print_to() and the new handler share one method for printing broken_pipe_warning. The end-to-end tests no longer depend on the pipe process outliving the check that it started. --- CHANGELOG.md | 10 ++-- cmd2/cmd2.py | 39 +++++-------- cmd2/exceptions.py | 8 +++ cmd2/rich_utils.py | 8 ++- docs/features/generating_output.md | 6 +- tests/test_cmd2.py | 89 +++++++++++++++--------------- 6 files changed, 80 insertions(+), 80 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c7d8337b6..7ad8c3767 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,11 @@ ## 4.4.3 (TBD) - Bug Fixes - - A `BrokenPipeError` which escapes a command whose output is piped to a shell command is now - handled the way `poutput()` handles it: it is ignored, or `broken_pipe_warning` is printed if - set. Previously a command which wrote to `self.stdout` without using one of the print methods, - with its own Rich console for instance, ended with a `BrokenPipeError` message when the shell - command exited early, as `head` does. + - 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 handles a broken pipe from + such a console the way `poutput()` does: it is ignored, or `broken_pipe_warning` is printed if + set. - Enhancements - Added the [rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py) diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 6d13ca01f..63c744c5b 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -145,6 +145,7 @@ Cmd2ShlexError, CommandSetRegistrationError, CompletionError, + ConsoleBrokenPipeError, EmbeddedConsoleExit, EmptyStatement, IncompleteStatement, @@ -610,10 +611,6 @@ def __init__( # Used to keep track of whether we are redirecting or piping output self._redirecting = False - # True while self.stdout is a pipe to a shell command, whether the current command set up that pipe - # or a command which is running it did - self._stdout_is_pipe = False - # Set text which prints right before all of the help tables are listed. self.doc_leader = "" @@ -1710,8 +1707,14 @@ def print_to( # writing. If you would like your application to print a # warning message, then set the broken_pipe_warning attribute # to the message you want printed. - if self.broken_pipe_warning and file != sys.stderr: - Cmd2GeneralConsole(file=sys.stderr).print(self.broken_pipe_warning) + if file != sys.stderr: + self._print_broken_pipe_warning() + + def _print_broken_pipe_warning(self) -> None: + """Print broken_pipe_warning, if there is one, to sys.stderr.""" + if self.broken_pipe_warning: + # Should sys.stderr be a broken pipe too, print_to() says nothing about it + self.print_to(sys.stderr, self.broken_pipe_warning) def poutput( self, @@ -3036,11 +3039,6 @@ def onecmd_plus_hooks( stop = False statement = None - # Whether the command's output goes to a pipe. Kept here as well as in self._stdout_is_pipe, - # which is back to what it was for the caller by the time an exception is handled. - piping = False - saved_stdout_is_pipe = self._stdout_is_pipe - try: # Convert the line into a Statement statement = self._input_line_to_statement(line) @@ -3071,11 +3069,6 @@ def onecmd_plus_hooks( redir_saved_state = self._redirect_output(statement) - # A command which does not redirect its output writes wherever its caller's goes - if redir_saved_state.redirecting: - self._stdout_is_pipe = self._cur_pipe_proc_reader is not None - piping = self._stdout_is_pipe - timestart = dt.datetime.now(tz=dt.timezone.utc) # precommand hooks @@ -3106,7 +3099,6 @@ def onecmd_plus_hooks( finally: # Get sigint protection while we restore stuff with self.sigint_protection: - self._stdout_is_pipe = saved_stdout_is_pipe if redir_saved_state is not None: self._restore_output(statement, redir_saved_state) @@ -3129,15 +3121,10 @@ def onecmd_plus_hooks( stop = True except PassThroughException as ex: raise ex.wrapped_ex from None - except BrokenPipeError as ex: - # The print methods handle this in print_to(). A command which writes to self.stdout - # some other way, such as with its own Rich console, lets it escape when the shell - # command its output is piped to exits early. Treat that the same way. Without a - # pipe, the error came from something else the command did and is reported as usual. - if not piping: - self.pexcept(ex) - elif self.broken_pipe_warning: - Cmd2GeneralConsole(file=sys.stderr).print(self.broken_pipe_warning) + except ConsoleBrokenPipeError: + # The print methods handle a broken pipe in print_to(). A command which prints through a + # cmd2 console of its own, as one which shows a Rich progress bar does, lets it escape. + self._print_broken_pipe_warning() except Exception as ex: # noqa: BLE001 self.pexcept(ex) finally: diff --git a/cmd2/exceptions.py b/cmd2/exceptions.py index a113a02df..c6f7b0933 100644 --- a/cmd2/exceptions.py +++ b/cmd2/exceptions.py @@ -69,6 +69,14 @@ class Cmd2ShlexError(Exception): """Raised when shlex fails to parse a command line string in StatementParser.""" +class ConsoleBrokenPipeError(BrokenPipeError): + """Raised by a cmd2 console when the stream it writes to is a pipe whose reader has gone away. + + Being a subclass tells cmd2 that it was a command's output which broke, rather than something + else the command was writing to, such as a socket. + """ + + class EmbeddedConsoleExit(SystemExit): """Custom exception class for use with the py command.""" diff --git a/cmd2/rich_utils.py b/cmd2/rich_utils.py index 6e4192654..5e39cf51f 100644 --- a/cmd2/rich_utils.py +++ b/cmd2/rich_utils.py @@ -46,6 +46,7 @@ ) from . import constants +from .exceptions import ConsoleBrokenPipeError from .styles import ( DEFAULT_ARGPARSE_STYLES, Cmd2Style, @@ -413,9 +414,12 @@ def matches_config( return self._config_key == self._build_config_key(file=file, **kwargs) def on_broken_pipe(self) -> None: - """Override which raises BrokenPipeError instead of SystemExit.""" + """Override which raises a BrokenPipeError instead of SystemExit. + + cmd2 handles the error if it escapes the command which was printing. + """ self.quiet = True - raise BrokenPipeError + raise ConsoleBrokenPipeError def print( self, diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index 36a9adaf7..477015d66 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -57,8 +57,10 @@ conveniences: contents of `self.broken_pipe_warning` to `stderr`. `self.broken_pipe_warning` defaults to an empty string so this method will just swallow the exception. If you want to show an error message, put it in `self.broken_pipe_warning` when you initialize `cmd2.Cmd`. A command which - writes to `self.stdout` some other way gets the same treatment when its output is piped to a - shell command: `cmd2` handles a `BrokenPipeError` which escapes it. + prints through a `cmd2` console of its own, such as the + [Cmd2GeneralConsole][cmd2.rich_utils.Cmd2GeneralConsole] used for the progress displays described + below, gets the same treatment. Use one of those rather than a plain `rich.console.Console`, + which exits the application when it writes to a broken pipe. 2. It examines and honors the [allow_style](./settings.md#allow_style) setting. See [Colored Output](#colored-output) below for more details. 3. It allows printing arbitrary `rich` renderable objects which can get visually quite complex. diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py index b3faf44af..80c0c4ab8 100644 --- a/tests/test_cmd2.py +++ b/tests/test_cmd2.py @@ -9,9 +9,11 @@ import tempfile import threading from code import InteractiveConsole +from collections.abc import Iterator from concurrent.futures import ThreadPoolExecutor from typing import ( NoReturn, + TextIO, cast, ) from unittest import mock @@ -971,10 +973,10 @@ class BrokenPipeApp(cmd2.Cmd): """Commands which hit a broken pipe without going through one of cmd2's print methods.""" def do_own_console(self, _: str) -> None: - """Print through a console of its own until the consumer of its output exits.""" + """Print through a console of its own, for longer than the reader of its output stays around.""" console = ru.Cmd2GeneralConsole(file=self.stdout) - # More than fits in a pipe, so the command is still writing when the consumer exits + # More than fits in a pipe, so the command is still writing when the reader goes away for _line in range(4096): console.print("x" * 1024) self.perror("the pipe never broke") @@ -985,64 +987,61 @@ def do_raise_broken_pipe(self, _: str) -> None: @pytest.fixture -def broken_pipe_app() -> BrokenPipeApp: - return BrokenPipeApp() +def broken_pipe() -> Iterator[TextIO]: + """A stream which writes to a pipe nothing reads.""" + read_fd, write_fd = os.pipe() + os.close(read_fd) + stream = open(write_fd, "w") # noqa: SIM115 + yield stream + # Closing flushes what a failed write left in the buffer, which fails again + with contextlib.suppress(BrokenPipeError): + stream.close() -@pytest.mark.skipif(sys.platform == "win32", reason="a write to a closed pipe raises a different OSError on Windows") -def test_broken_pipe_from_a_commands_own_console_is_ignored(broken_pipe_app) -> None: - """A consumer which exits early ends the command quietly, as it does for one which uses poutput().""" - # The consumer must outlive the check that it started, and is not a Python process, which could write - # warnings of its own to stderr: coverage does when it starts in a subprocess on Python 3.11. - out, err = run_cmd(broken_pipe_app, "own_console | sleep 0.5") - assert not out - assert not err +#: A closed pipe raises BrokenPipeError on POSIX. On Windows it can raise another OSError, which no part of cmd2 handles. +posix_broken_pipe = pytest.mark.skipif(sys.platform == "win32", reason="a write to a closed pipe raises another OSError") -def test_broken_pipe_raised_by_a_piped_command_is_ignored(broken_pipe_app, running_pipe_process) -> None: - out, err = run_cmd(broken_pipe_app, "raise_broken_pipe | sort") - assert not out - assert not err +@posix_broken_pipe +def test_broken_pipe_from_a_commands_own_console_is_ignored(broken_pipe, capsys) -> None: + """Whatever stdout is a pipe to, a command ends quietly when its reader goes away, as one which uses poutput() does.""" + app = BrokenPipeApp(stdout=broken_pipe) + app.onecmd_plus_hooks("own_console") + assert not capsys.readouterr().err -def test_broken_pipe_raised_by_a_piped_command_prints_the_warning(broken_pipe_app, running_pipe_process) -> None: - broken_pipe_app.broken_pipe_warning = "The pipe broke" - out, err = run_cmd(broken_pipe_app, "raise_broken_pipe | sort") - assert not out - assert err == ["The pipe broke"] +@posix_broken_pipe +def test_broken_pipe_from_a_commands_own_console_prints_the_warning(broken_pipe, capsys) -> None: + app = BrokenPipeApp(stdout=broken_pipe) + app.broken_pipe_warning = "The pipe broke" + app.onecmd_plus_hooks("own_console") + assert capsys.readouterr().err == "The pipe broke\n" -def test_broken_pipe_raised_by_a_command_in_a_piped_script_is_ignored(broken_pipe_app, tmp_path, running_pipe_process) -> None: - """A command which does not redirect its own output writes to the pipe of the command running it.""" - script = tmp_path / "script.txt" - script.write_text("raise_broken_pipe\n") - out, err = run_cmd(broken_pipe_app, f"run_script {script} | sort") + +@posix_broken_pipe +def test_broken_pipe_from_a_piped_commands_own_console_is_ignored(running_pipe_process) -> None: + """The shell command a command's output is piped to exits without reading it.""" + out, err = run_cmd(BrokenPipeApp(), "own_console | true") assert not out assert not err -def test_broken_pipe_raised_by_a_redirected_command_in_a_piped_script_is_reported( - broken_pipe_app, tmp_path, running_pipe_process -) -> None: - """A command which redirects its output to a file does not write to the pipe of the command running it.""" +@posix_broken_pipe +def test_broken_pipe_from_the_console_of_a_command_in_a_piped_script_is_ignored(tmp_path, running_pipe_process) -> None: script = tmp_path / "script.txt" - script.write_text(f"raise_broken_pipe > {tmp_path / 'out.txt'}\n") - _out, err = run_cmd(broken_pipe_app, f"run_script {script} | sort") - assert "BrokenPipeError" in err[0] - - -def test_broken_pipe_raised_after_a_piped_command_is_reported(broken_pipe_app, running_pipe_process) -> None: - """The pipe of one command does not hide the error for the commands which follow it.""" - run_cmd(broken_pipe_app, "raise_broken_pipe | sort") - _out, err = run_cmd(broken_pipe_app, "raise_broken_pipe") - assert "BrokenPipeError" in err[0] + script.write_text("own_console\n") + out, err = run_cmd(BrokenPipeApp(), f"run_script {script} | true") + assert not out + assert not err -@pytest.mark.parametrize("redirection", ["", " > {file}"]) -def test_broken_pipe_raised_by_a_command_which_is_not_piped_is_reported(broken_pipe_app, tmp_path, redirection) -> None: - """Without a pipe the error did not come from the command's output, so it is not hidden.""" - broken_pipe_app.broken_pipe_warning = "The pipe broke" - _out, err = run_cmd(broken_pipe_app, "raise_broken_pipe" + redirection.format(file=tmp_path / "out.txt")) +@pytest.mark.parametrize("redirection", ["", " | sort", " > {file}"]) +def test_broken_pipe_raised_by_a_command_is_reported(tmp_path, running_pipe_process, redirection) -> None: + """Only a console knows that it was the command's output which broke. Any other BrokenPipeError is not hidden.""" + app = BrokenPipeApp() + app.broken_pipe_warning = "The pipe broke" + _out, err = run_cmd(app, "raise_broken_pipe" + redirection.format(file=tmp_path / "out.txt")) assert "BrokenPipeError" in err[0] assert "The pipe broke" not in err From 02bbca941397c3b4453ac821c36b55e53b01a176 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 16:37:45 -0500 Subject: [PATCH 09/11] Pipe the broken pipe tests to a consumer which cannot exit too soon A consumer which exits at once, like true, can be found to have exited before the command runs, which cmd2 reports as a failed pipe instead of running the command. head -n 1 stays until the command has written a line, so the tests no longer depend on how fast the two processes start. --- tests/test_cmd2.py | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py index 80c0c4ab8..79d024c44 100644 --- a/tests/test_cmd2.py +++ b/tests/test_cmd2.py @@ -1021,9 +1021,13 @@ def test_broken_pipe_from_a_commands_own_console_prints_the_warning(broken_pipe, @posix_broken_pipe def test_broken_pipe_from_a_piped_commands_own_console_is_ignored(running_pipe_process) -> None: - """The shell command a command's output is piped to exits without reading it.""" - out, err = run_cmd(BrokenPipeApp(), "own_console | true") - assert not out + """The shell command a command's output is piped to exits before reading all of it. + + head cannot exit before the command has written a line, so cmd2 never finds that the pipe process ended before the + command could run, however slowly the two start. + """ + out, err = run_cmd(BrokenPipeApp(), "own_console | head -n 1") + assert out == ["x" * 1024] assert not err @@ -1031,8 +1035,8 @@ def test_broken_pipe_from_a_piped_commands_own_console_is_ignored(running_pipe_p def test_broken_pipe_from_the_console_of_a_command_in_a_piped_script_is_ignored(tmp_path, running_pipe_process) -> None: script = tmp_path / "script.txt" script.write_text("own_console\n") - out, err = run_cmd(BrokenPipeApp(), f"run_script {script} | true") - assert not out + out, err = run_cmd(BrokenPipeApp(), f"run_script {script} | head -n 1") + assert out == ["x" * 1024] assert not err From 7bc052a90a45e8235701216c1c97fd385a38ad50 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Fri, 13 Nov 2026 17:21:28 -0500 Subject: [PATCH 10/11] Narrow the handling of a broken pipe from a command's own console - ConsoleBrokenPipeError names the stream which broke, and only one that is the command's output is handled quietly. A console which was writing somewhere else, to a socket for instance, has its error reported. - A KeyboardInterrupt or SystemExit which the broken pipe replaced, as when the with block of a progress display exits, is raised again, so Ctrl-C still stops a script and exiting still exits. - The console of a command finalization hook is handled the same way. - The documentation and changelog no longer say this is what poutput() does: the command ends at the call which found the pipe broken. --- CHANGELOG.md | 5 ++- cmd2/cmd2.py | 39 ++++++++++++++++++++--- cmd2/exceptions.py | 17 ++++++++-- cmd2/rich_utils.py | 2 +- docs/features/generating_output.md | 7 ++-- tests/test_cmd2.py | 51 ++++++++++++++++++++++++++++++ 6 files changed, 107 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ad8c3767..c09f7db73 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,8 @@ - Bug Fixes - 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 handles a broken pipe from - such a console the way `poutput()` does: it is ignored, or `broken_pipe_warning` is printed if - set. + is piped to something that exits early, as `head` does. `cmd2` now ends the command quietly + instead, printing `broken_pipe_warning` if it is set. - Enhancements - Added the [rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py) diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 63c744c5b..4372e3a37 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -1716,6 +1716,34 @@ def _print_broken_pipe_warning(self) -> None: # Should sys.stderr be a broken pipe too, print_to() says nothing about it self.print_to(sys.stderr, self.broken_pipe_warning) + def _handle_console_broken_pipe(self, ex: ConsoleBrokenPipeError) -> None: + """Handle a broken pipe which a cmd2 console raised while a command or one of its hooks was running. + + The print methods handle a broken pipe in print_to(). A command which prints through a cmd2 console + of its own, as one which shows a Rich progress bar does, lets it escape. Call this while self.stdout + is still what the command was writing to. + + :param ex: the exception the console raised + :raises KeyboardInterrupt: if the broken pipe replaced one + :raises SystemExit: if the broken pipe replaced one + :raises ConsoleBrokenPipeError: if it was not the command's output which broke + """ + # A console can hit the broken pipe while another exception is ending the command, as the with block + # of a progress display exits for instance. Ctrl-C and exiting still mean what they did. + context = ex.__context__ + while context is not None: + if isinstance(context, (KeyboardInterrupt, SystemExit)): + raise context + context = context.__context__ + + # Only the output of the command going away is expected. A console which was writing somewhere else, + # to a socket for instance, has a failure to report. + if not any(ex.file is stream for stream in (self.stdout, sys.stdout, sys.stderr)): + raise ex + + if ex.file is not sys.stderr: + self._print_broken_pipe_warning() + def poutput( self, *objects: Any, @@ -3096,6 +3124,8 @@ def onecmd_plus_hooks( if self.timing: self.perror(f"Elapsed: {dt.datetime.now(tz=dt.timezone.utc) - timestart}", style=None) + except ConsoleBrokenPipeError as ex: + self._handle_console_broken_pipe(ex) finally: # Get sigint protection while we restore stuff with self.sigint_protection: @@ -3121,15 +3151,14 @@ def onecmd_plus_hooks( stop = True except PassThroughException as ex: raise ex.wrapped_ex from None - except ConsoleBrokenPipeError: - # The print methods handle a broken pipe in print_to(). A command which prints through a - # cmd2 console of its own, as one which shows a Rich progress bar does, lets it escape. - self._print_broken_pipe_warning() except Exception as ex: # noqa: BLE001 self.pexcept(ex) finally: try: - stop = self._run_cmdfinalization_hooks(stop, statement) + try: + stop = self._run_cmdfinalization_hooks(stop, statement) + except ConsoleBrokenPipeError as ex: + self._handle_console_broken_pipe(ex) except KeyboardInterrupt: if raise_keyboard_interrupt and not stop: raise diff --git a/cmd2/exceptions.py b/cmd2/exceptions.py index c6f7b0933..ba95bc4b2 100644 --- a/cmd2/exceptions.py +++ b/cmd2/exceptions.py @@ -1,6 +1,9 @@ """Custom exceptions for cmd2.""" -from typing import Any +from typing import ( + IO, + Any, +) ############################################################################################################ # The following exceptions are part of the public API @@ -72,10 +75,18 @@ class Cmd2ShlexError(Exception): class ConsoleBrokenPipeError(BrokenPipeError): """Raised by a cmd2 console when the stream it writes to is a pipe whose reader has gone away. - Being a subclass tells cmd2 that it was a command's output which broke, rather than something - else the command was writing to, such as a socket. + It names the stream, which tells cmd2 whether it was a command's output which broke, rather + than something else the command was writing to, such as a socket. """ + def __init__(self, file: IO[str]) -> None: + """Initialize ConsoleBrokenPipeError instance. + + :param file: the stream the console was writing to + """ + super().__init__() + self.file = file + class EmbeddedConsoleExit(SystemExit): """Custom exception class for use with the py command.""" diff --git a/cmd2/rich_utils.py b/cmd2/rich_utils.py index 5e39cf51f..3dcc8f85d 100644 --- a/cmd2/rich_utils.py +++ b/cmd2/rich_utils.py @@ -419,7 +419,7 @@ def on_broken_pipe(self) -> None: cmd2 handles the error if it escapes the command which was printing. """ self.quiet = True - raise ConsoleBrokenPipeError + raise ConsoleBrokenPipeError(self.file) def print( self, diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index 477015d66..3ac3e890e 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -59,8 +59,11 @@ conveniences: message, put it in `self.broken_pipe_warning` when you initialize `cmd2.Cmd`. A command which prints through a `cmd2` console of its own, such as the [Cmd2GeneralConsole][cmd2.rich_utils.Cmd2GeneralConsole] used for the progress displays described - below, gets the same treatment. Use one of those rather than a plain `rich.console.Console`, - which exits the application when it writes to a broken pipe. + below, is covered too, with one difference. A command which uses `poutput` carries on after the + pipe breaks, but one which prints through its own console ends at the call which found the pipe + broken, and its postcommand hooks do not run. Put any cleanup such a command has to do in a + `finally` block or a context manager. Use a `cmd2` console rather than a plain + `rich.console.Console`, which exits the application when it writes to a broken pipe. 2. It examines and honors the [allow_style](./settings.md#allow_style) setting. See [Colored Output](#colored-output) below for more details. 3. It allows printing arbitrary `rich` renderable objects which can get visually quite complex. diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py index 79d024c44..4840b6ecd 100644 --- a/tests/test_cmd2.py +++ b/tests/test_cmd2.py @@ -985,6 +985,25 @@ def do_raise_broken_pipe(self, _: str) -> None: """Raise the error a write to a closed pipe or socket raises.""" raise BrokenPipeError + def do_other_console(self, _: str) -> None: + """Print through a console which writes somewhere other than the command's output.""" + ru.Cmd2GeneralConsole(file=self.other_stream).print("x") + + def do_unwind(self, how: str) -> None: + """Have a console write as an exception ends the command, as the with block of a progress display does.""" + try: + raise KeyboardInterrupt if how == "interrupt" else SystemExit(5) + finally: + ru.Cmd2GeneralConsole(file=self.stdout).print("x") + + def do_quiet(self, _: str) -> None: + """Write nothing.""" + + def console_hook(self, data: cmd2.plugin.CommandFinalizationData) -> cmd2.plugin.CommandFinalizationData: + """Print through a console of its own once a command has finished.""" + ru.Cmd2GeneralConsole(file=self.stdout).print("x") + return data + @pytest.fixture def broken_pipe() -> Iterator[TextIO]: @@ -1040,6 +1059,38 @@ def test_broken_pipe_from_the_console_of_a_command_in_a_piped_script_is_ignored( assert not err +@posix_broken_pipe +def test_broken_pipe_from_a_console_on_another_stream_is_reported(broken_pipe) -> None: + """A console knows which stream broke. Only the command's output going away is expected.""" + app = BrokenPipeApp() + app.other_stream = broken_pipe + _out, err = run_cmd(app, "other_console") + assert any("BrokenPipeError" in line for line in err) + + +@posix_broken_pipe +def test_broken_pipe_does_not_hide_the_interrupt_it_replaced(broken_pipe) -> None: + """Ctrl-C still stops a script when a console hits a broken pipe as the interrupt ends the command.""" + app = BrokenPipeApp(stdout=broken_pipe) + with pytest.raises(KeyboardInterrupt): + app.onecmd_plus_hooks("unwind interrupt", raise_keyboard_interrupt=True) + + +@posix_broken_pipe +def test_broken_pipe_does_not_hide_the_exit_it_replaced(broken_pipe) -> None: + app = BrokenPipeApp(stdout=broken_pipe) + assert app.onecmd_plus_hooks("unwind exit") is True + assert app.exit_code == 5 + + +@posix_broken_pipe +def test_broken_pipe_from_the_console_of_a_finalization_hook_is_ignored(broken_pipe, capsys) -> None: + app = BrokenPipeApp(stdout=broken_pipe) + app.register_cmdfinalization_hook(app.console_hook) + app.onecmd_plus_hooks("quiet") + assert not capsys.readouterr().err + + @pytest.mark.parametrize("redirection", ["", " | sort", " > {file}"]) def test_broken_pipe_raised_by_a_command_is_reported(tmp_path, running_pipe_process, redirection) -> None: """Only a console knows that it was the command's output which broke. Any other BrokenPipeError is not hidden.""" From 6653484409fc878ca37b0cce7393e3f82469cc3a Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:29:58 -0500 Subject: [PATCH 11/11] Fix docstring text to match behavior --- cmd2/rich_utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd2/rich_utils.py b/cmd2/rich_utils.py index 3dcc8f85d..e2ea30563 100644 --- a/cmd2/rich_utils.py +++ b/cmd2/rich_utils.py @@ -414,7 +414,7 @@ def matches_config( return self._config_key == self._build_config_key(file=file, **kwargs) def on_broken_pipe(self) -> None: - """Override which raises a BrokenPipeError instead of SystemExit. + """Override which raises a ConsoleBrokenPipeError instead of SystemExit. cmd2 handles the error if it escapes the command which was printing. """