Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,20 @@
## Unreleased
## 4.4.3 (TBD)

- Bug Fixes
- Fixed file path completion for names containing square brackets, including bracketed working
directories and home directories.
- 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
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)
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)

Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
46 changes: 43 additions & 3 deletions cmd2/cmd2.py
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,7 @@
Cmd2ShlexError,
CommandSetRegistrationError,
CompletionError,
ConsoleBrokenPipeError,
EmbeddedConsoleExit,
EmptyStatement,
IncompleteStatement,
Expand Down Expand Up @@ -1706,8 +1707,42 @@ 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 _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,
Expand Down Expand Up @@ -3089,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:
Expand Down Expand Up @@ -3118,7 +3155,10 @@ def onecmd_plus_hooks(
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
Expand Down
21 changes: 20 additions & 1 deletion cmd2/exceptions.py
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -69,6 +72,22 @@ 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.

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."""

Expand Down
8 changes: 6 additions & 2 deletions cmd2/rich_utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
)

from . import constants
from .exceptions import ConsoleBrokenPipeError
from .styles import (
DEFAULT_ARGPARSE_STYLES,
Cmd2Style,
Expand Down Expand Up @@ -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 ConsoleBrokenPipeError instead of SystemExit.

cmd2 handles the error if it escapes the command which was printing.
"""
self.quiet = True
raise BrokenPipeError
raise ConsoleBrokenPipeError(self.file)

def print(
self,
Expand Down
137 changes: 136 additions & 1 deletion docs/features/generating_output.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,14 @@ 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
prints through a `cmd2` console of its own, such as the
[Cmd2GeneralConsole][cmd2.rich_utils.Cmd2GeneralConsole] used for the progress displays described
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.
Expand All @@ -69,6 +76,134 @@ 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, so the cursor never returns to
the start of the line.

`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.

### 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

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.

### 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` 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
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)`.

### Styles, Redirection, and Markup

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
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).** 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

If you would rather write the escape sequences yourself, put the carriage return in the `end`
parameter, which `rich` does not strip:

```py
import time

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!")
```

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
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

When an error occurs in your program, you can display it on `sys.stderr` by calling the
Expand Down
3 changes: 3 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading
Loading