Skip to content

Commit 87c3b8a

Browse files
committed
Merge branch 'main' into consolidated_toolbar
# Conflicts: # CHANGELOG.md
2 parents ead92b0 + 0047276 commit 87c3b8a

9 files changed

Lines changed: 473 additions & 9 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,18 @@
33
- Bug Fixes
44
- Fixed file path completion for names containing square brackets, including bracketed working
55
directories and home directories.
6-
6+
- A command which prints through a `cmd2` console of its own, such as a `Cmd2GeneralConsole`
7+
showing a Rich progress bar, no longer ends with a `BrokenPipeError` message when its output
8+
is piped to something that exits early, as `head` does. `cmd2` now ends the command quietly
9+
instead, printing `broken_pipe_warning` if it is set.
710
- Enhancements
11+
- Added the
12+
[rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py)
13+
example, which shows how to display the progress of long-running commands with Rich status
14+
spinners and progress bars. See the new
15+
[Updating Output in Place](docs/features/generating_output.md#updating-output-in-place)
16+
documentation for details, including why a carriage return embedded in a string passed to
17+
`poutput()` does not move the cursor.
818
- `enable_bottom_toolbar=True` now keeps the toolbar visible and refreshing during command
919
execution. Command output appears above it. A line of output left unfinished when a command
1020
ends is ended there, so the next prompt starts on a new line while the toolbar is enabled.

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,9 @@ to build a more complete application.
9898
arguments and subcommands, or plain type hints via
9999
[`@with_annotated`](https://cmd2.readthedocs.io/en/latest/features/annotated/). A single parser
100100
definition drives validation, help, and completion.
101-
- Render Rich tables and other styled objects, with consistent helpers for
101+
- Render Rich tables,
102+
[progress bars](https://cmd2.readthedocs.io/en/latest/features/generating_output/#progress-bars),
103+
and other styled objects, with consistent helpers for
102104
[normal output, errors, warnings, and paging](https://cmd2.readthedocs.io/en/latest/features/generating_output/).
103105
- Organize large applications into independently testable and dynamically loadable
104106
[CommandSets](https://cmd2.readthedocs.io/en/latest/features/modular_commands/), and customize the

‎cmd2/cmd2.py‎

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,7 @@
147147
Cmd2ShlexError,
148148
CommandSetRegistrationError,
149149
CompletionError,
150+
ConsoleBrokenPipeError,
150151
EmbeddedConsoleExit,
151152
EmptyStatement,
152153
IncompleteStatement,
@@ -1711,8 +1712,42 @@ def print_to(
17111712
# writing. If you would like your application to print a
17121713
# warning message, then set the broken_pipe_warning attribute
17131714
# to the message you want printed.
1714-
if self.broken_pipe_warning and file != sys.stderr:
1715-
Cmd2GeneralConsole(file=sys.stderr).print(self.broken_pipe_warning)
1715+
if file != sys.stderr:
1716+
self._print_broken_pipe_warning()
1717+
1718+
def _print_broken_pipe_warning(self) -> None:
1719+
"""Print broken_pipe_warning, if there is one, to sys.stderr."""
1720+
if self.broken_pipe_warning:
1721+
# Should sys.stderr be a broken pipe too, print_to() says nothing about it
1722+
self.print_to(sys.stderr, self.broken_pipe_warning)
1723+
1724+
def _handle_console_broken_pipe(self, ex: ConsoleBrokenPipeError) -> None:
1725+
"""Handle a broken pipe which a cmd2 console raised while a command or one of its hooks was running.
1726+
1727+
The print methods handle a broken pipe in print_to(). A command which prints through a cmd2 console
1728+
of its own, as one which shows a Rich progress bar does, lets it escape. Call this while self.stdout
1729+
is still what the command was writing to.
1730+
1731+
:param ex: the exception the console raised
1732+
:raises KeyboardInterrupt: if the broken pipe replaced one
1733+
:raises SystemExit: if the broken pipe replaced one
1734+
:raises ConsoleBrokenPipeError: if it was not the command's output which broke
1735+
"""
1736+
# A console can hit the broken pipe while another exception is ending the command, as the with block
1737+
# of a progress display exits for instance. Ctrl-C and exiting still mean what they did.
1738+
context = ex.__context__
1739+
while context is not None:
1740+
if isinstance(context, (KeyboardInterrupt, SystemExit)):
1741+
raise context
1742+
context = context.__context__
1743+
1744+
# Only the output of the command going away is expected. A console which was writing somewhere else,
1745+
# to a socket for instance, has a failure to report.
1746+
if not any(ex.file is stream for stream in (self.stdout, sys.stdout, sys.stderr)):
1747+
raise ex
1748+
1749+
if ex.file is not sys.stderr:
1750+
self._print_broken_pipe_warning()
17161751

17171752
def poutput(
17181753
self,
@@ -3157,6 +3192,8 @@ def onecmd_plus_hooks(
31573192

31583193
if self.timing:
31593194
self.perror(f"Elapsed: {dt.datetime.now(tz=dt.timezone.utc) - timestart}", style=None)
3195+
except ConsoleBrokenPipeError as ex:
3196+
self._handle_console_broken_pipe(ex)
31603197
finally:
31613198
# Get sigint protection while we restore stuff
31623199
with self.sigint_protection:
@@ -3186,7 +3223,10 @@ def onecmd_plus_hooks(
31863223
self.pexcept(ex)
31873224
finally:
31883225
try:
3189-
stop = self._run_cmdfinalization_hooks(stop, statement)
3226+
try:
3227+
stop = self._run_cmdfinalization_hooks(stop, statement)
3228+
except ConsoleBrokenPipeError as ex:
3229+
self._handle_console_broken_pipe(ex)
31903230
except KeyboardInterrupt:
31913231
if raise_keyboard_interrupt and not stop:
31923232
raise

‎cmd2/exceptions.py‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
"""Custom exceptions for cmd2."""
22

3-
from typing import Any
3+
from typing import (
4+
IO,
5+
Any,
6+
)
47

58
############################################################################################################
69
# The following exceptions are part of the public API
@@ -69,6 +72,22 @@ class Cmd2ShlexError(Exception):
6972
"""Raised when shlex fails to parse a command line string in StatementParser."""
7073

7174

75+
class ConsoleBrokenPipeError(BrokenPipeError):
76+
"""Raised by a cmd2 console when the stream it writes to is a pipe whose reader has gone away.
77+
78+
It names the stream, which tells cmd2 whether it was a command's output which broke, rather
79+
than something else the command was writing to, such as a socket.
80+
"""
81+
82+
def __init__(self, file: IO[str]) -> None:
83+
"""Initialize ConsoleBrokenPipeError instance.
84+
85+
:param file: the stream the console was writing to
86+
"""
87+
super().__init__()
88+
self.file = file
89+
90+
7291
class EmbeddedConsoleExit(SystemExit):
7392
"""Custom exception class for use with the py command."""
7493

‎cmd2/rich_utils.py‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@
4646
)
4747

4848
from . import constants
49+
from .exceptions import ConsoleBrokenPipeError
4950
from .styles import (
5051
DEFAULT_ARGPARSE_STYLES,
5152
Cmd2Style,
@@ -413,9 +414,12 @@ def matches_config(
413414
return self._config_key == self._build_config_key(file=file, **kwargs)
414415

415416
def on_broken_pipe(self) -> None:
416-
"""Override which raises BrokenPipeError instead of SystemExit."""
417+
"""Override which raises a ConsoleBrokenPipeError instead of SystemExit.
418+
419+
cmd2 handles the error if it escapes the command which was printing.
420+
"""
417421
self.quiet = True
418-
raise BrokenPipeError
422+
raise ConsoleBrokenPipeError(self.file)
419423

420424
def print(
421425
self,

‎docs/features/generating_output.md‎

Lines changed: 136 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,14 @@ conveniences:
5656
1. Since users can pipe output to a shell command, it catches `BrokenPipeError` and outputs the
5757
contents of `self.broken_pipe_warning` to `stderr`. `self.broken_pipe_warning` defaults to an
5858
empty string so this method will just swallow the exception. If you want to show an error
59-
message, put it in `self.broken_pipe_warning` when you initialize `cmd2.Cmd`.
59+
message, put it in `self.broken_pipe_warning` when you initialize `cmd2.Cmd`. A command which
60+
prints through a `cmd2` console of its own, such as the
61+
[Cmd2GeneralConsole][cmd2.rich_utils.Cmd2GeneralConsole] used for the progress displays described
62+
below, is covered too, with one difference. A command which uses `poutput` carries on after the
63+
pipe breaks, but one which prints through its own console ends at the call which found the pipe
64+
broken, and its postcommand hooks do not run. Put any cleanup such a command has to do in a
65+
`finally` block or a context manager. Use a `cmd2` console rather than a plain
66+
`rich.console.Console`, which exits the application when it writes to a broken pipe.
6067
2. It examines and honors the [allow_style](./settings.md#allow_style) setting. See
6168
[Colored Output](#colored-output) below for more details.
6269
3. It allows printing arbitrary `rich` renderable objects which can get visually quite complex.
@@ -69,6 +76,134 @@ def do_echo(self, args):
6976
self.poutput(args)
7077
```
7178

79+
## Updating Output in Place
80+
81+
Countdowns, progress indicators, and status lines repeatedly overwrite the same line of the
82+
terminal. The traditional way to do that with `print()` is to embed a carriage return (`\r`) in the
83+
string, but that does not work with `poutput` or any of the other `cmd2` print methods. `rich`
84+
removes the carriage return, backspace, bell, vertical tab, and form feed characters from every
85+
string it renders because they would break its width calculations, so the cursor never returns to
86+
the start of the line.
87+
88+
`rich` can manage the cursor for you instead. Its status spinners and progress bars work inside a
89+
command when you give them a console which writes to `self.stdout`. Create one with
90+
[Cmd2GeneralConsole][cmd2.rich_utils.Cmd2GeneralConsole] so the display uses the `cmd2` theme and
91+
follows the [allow_style](./settings.md#allow_style) setting. The
92+
[rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py) example
93+
demonstrates everything described below.
94+
95+
### Status Messages
96+
97+
For work of an unknown length, show a spinner and a message with a
98+
[status](https://rich.readthedocs.io/en/stable/console.html#status):
99+
100+
```py
101+
import time
102+
103+
from cmd2.rich_utils import Cmd2GeneralConsole
104+
105+
106+
def do_countdown(self, _):
107+
"""Count down from 5 on a single line"""
108+
console = Cmd2GeneralConsole(file=self.stdout)
109+
with console.status("Starting...") as status:
110+
for remaining in range(5, 0, -1):
111+
status.update(f"Time remaining: {remaining}s")
112+
time.sleep(1)
113+
self.poutput("Done!")
114+
```
115+
116+
The status line disappears when the `with` block exits.
117+
118+
### Progress Bars
119+
120+
When you know how much work there is, show a
121+
[progress bar](https://rich.readthedocs.io/en/stable/progress.html):
122+
123+
```py
124+
import time
125+
126+
from rich.progress import Progress
127+
128+
from cmd2.rich_utils import Cmd2GeneralConsole
129+
130+
131+
def do_process(self, _):
132+
"""Process some files while showing a progress bar"""
133+
files = [f"file_{i}.dat" for i in range(1, 11)]
134+
console = Cmd2GeneralConsole(file=self.stdout)
135+
with Progress(console=console) as progress:
136+
task_id = progress.add_task("Processing files", total=len(files))
137+
for file in files:
138+
time.sleep(0.4)
139+
progress.console.print(f"Processed {file}")
140+
progress.advance(task_id)
141+
self.poutput("All files processed.")
142+
```
143+
144+
A few things to know when using a progress bar in a command:
145+
146+
- While the bar is active, print with `progress.console.print()` as shown above. The message then
147+
appears above the bar. `poutput` and the other print methods do not know about the bar: their
148+
output lands on the end of its line and a stale copy of the bar is left behind. Once the `with`
149+
block exits, they are safe to use again.
150+
- The finished bar is left on the screen. Pass `transient=True` to `Progress` to erase it instead.
151+
- Call `add_task` more than once to show several bars at the same time, and pass
152+
[columns](https://rich.readthedocs.io/en/stable/progress.html#columns) to `Progress` to change
153+
what is shown for each one.
154+
- To add a bar to a simple loop, wrap the sequence being iterated over with
155+
`rich.progress.track(sequence, console=console)`.
156+
157+
### Styles, Redirection, and Markup
158+
159+
Status messages and progress bars differ from the print methods in two ways:
160+
161+
- **They are only animated where `allow_style` allows it.** With the default setting of `Terminal`,
162+
they are animated on a terminal. When the output of the command is redirected to a file or piped
163+
to a shell command, a status writes nothing and a progress bar writes only its final state, or
164+
just a blank line if it is transient. With `Never`, that is what happens on a terminal too. With
165+
`Always`, redirected output also contains the escape sequences which hide and show the cursor and
166+
style the bar.
167+
- **Their text is parsed as [console markup](https://rich.readthedocs.io/en/stable/markup.html).** A
168+
status message or the description of a progress bar task is searched for markup tags such as
169+
`[bold]` and emoji codes such as `:warning:`, even though both are off by default in the print
170+
methods. So `report[draft].txt` is displayed as `report.txt`, `user:id:42` as `user🆔42`, and an
171+
unmatched closing tag such as `[/b]` raises a `MarkupError`. To display text you do not control,
172+
such as a file name, exactly as it is, give a status a `rich.text.Text` object instead of a
173+
string, and show task descriptions with a `TextColumn("{task.description}", markup=False)`
174+
[column](https://rich.readthedocs.io/en/stable/progress.html#columns).
175+
176+
### Carriage Returns
177+
178+
If you would rather write the escape sequences yourself, put the carriage return in the `end`
179+
parameter, which `rich` does not strip:
180+
181+
```py
182+
import time
183+
184+
CLEAR_LINE = "\x1b[2K"
185+
186+
187+
def do_countdown(self, _):
188+
"""Count down from 5 on a single line"""
189+
for remaining in range(5, 0, -1):
190+
self.poutput(f"{CLEAR_LINE}Time remaining: {remaining}s", end="\r")
191+
time.sleep(1)
192+
self.poutput(f"{CLEAR_LINE}Done!")
193+
```
194+
195+
Use the `style` parameter if you want to color text printed this way. A string which already
196+
contains ANSI style sequences is parsed as ANSI text, which discards every other kind of escape
197+
sequence in it, including the one that clears the line.
198+
199+
Unlike the `rich` displays, this always writes the escape sequences and carriage returns, including
200+
when the output of the command is redirected to a file or pipe.
201+
202+
The print methods flush the stream after every call, so there is no `flush` parameter to pass.
203+
Strings written directly to `self.stdout` are not processed by `rich`, so control characters in them
204+
are left alone. They are not flushed either, so call `self.stdout.flush()` after writing a line
205+
which does not end with a newline.
206+
72207
## Error Messages
73208

74209
When an error occurs in your program, you can display it on `sys.stderr` by calling the

‎examples/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,9 @@ each:
8888
- [remove_settable.py](https://github.com/python-cmd2/cmd2/blob/main/examples/remove_settable.py)
8989
- Shows how to remove any of the built-in cmd2 `Settables` you do not want in your cmd2
9090
application
91+
- [rich_progress.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_progress.py)
92+
- Shows how to use Rich progress bars and status spinners to display the progress of
93+
long-running commands
9194
- [rich_tables.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_tables.py)
9295
- Example of using Rich Tables within a cmd2 application for displaying tabular data
9396
- [rich_theme.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_theme.py)

0 commit comments

Comments
 (0)