Skip to content

Add Rich progress docs and example, and handle broken pipes from any piped command - #1809

Merged
tleonhardt merged 12 commits into
mainfrom
docs-in-place-output
Nov 15, 2026
Merged

tleonhardt merged 12 commits into
mainfrom
docs-in-place-output

Conversation

@tleonhardt

@tleonhardt tleonhardt commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

Documents how to overwrite output in place (countdowns, status lines, progress bars) from a cmd2
command, adds an example application which does it with Rich, and fixes a BrokenPipeError that
this kind of command ran into when its output was piped.

poutput() and the other print methods render through Rich, which strips carriage returns (along
with backspace, bell, vertical tab, and form feed) from every string it renders. A \r embedded in
a string is therefore dropped, so the cursor never returns to the start of the line. This has been
the behavior since the print methods moved to Rich in 3.0.0, but it was not documented.

Bug fix

The print methods ignore the BrokenPipeError raised when a command's output goes to a pipe whose
reader exits early, such as head. A command which printed through a cmd2 console of its own, as
one showing a Rich progress bar does, let the error escape and ended with a BrokenPipeError
message.

Cmd2BaseConsole.on_broken_pipe() now raises ConsoleBrokenPipeError, an internal
BrokenPipeError subclass which names the stream that broke, and onecmd_plus_hooks() ends the
command quietly, printing broken_pipe_warning if it is set. Marking the error where the console
raises it means:

  • It works wherever the output goes: a cmd | shell pipe, a command run by a piped run_script,
    or an application whose own stdout is a pipe. A command finalization hook's console is covered too
  • Only the command's output going away is handled. A console writing somewhere else, such as a
    socket, and any other BrokenPipeError which escapes a command are still 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
  • No redirection state is needed to decide

Unlike a command which uses poutput(), which carries on after the pipe breaks, a command printing
through its own console ends at the call which found the pipe broken. A command which writes to
self.stdout directly, or through a plain rich.console.Console, is not covered. The documentation
says both.

Documentation

Adds an "Updating Output in Place" section to the
Generating Output page, which
explains why an embedded \r does not work and has four subsections:

  • Status Messages - a Rich status spinner on a Cmd2GeneralConsole writing to self.stdout
  • Progress Bars - a Rich Progress bar on the same kind of console, including how to print
    while the bar is active (progress.console.print() rather than the print methods),
    transient=True, multiple bars, custom columns, and track()
  • Styles, Redirection, and Markup - how these displays differ from the print methods: whether
    they are animated depends on allow_style, and their text is parsed for markup tags and emoji
    codes
  • Carriage Returns - passing the carriage return in the end parameter, which Rich does not
    strip, for those who want to write the escape sequences themselves

Example

Adds examples/rich_progress.py and lists it in examples/README.md. Its commands are:

  • status - a spinner with a status message
  • progress - a progress bar with messages printed above it while it runs
  • downloads - several transient progress bars with custom columns updating at the same time
  • track - a progress bar added to a loop with rich.progress.track()

README and CHANGELOG

Mentions progress bars in the README's "Build more with less code" list, linking to the new
documentation, and adds CHANGELOG entries for the bug fix and the example under a new 4.4.3 heading.

Testing

  • New tests in tests/test_cmd2.py cover a command whose own console writes to a broken pipe
    (stdout itself, a cmd | shell pipe, a command run by a piped script, and a finalization hook),
    with and without broken_pipe_warning. They also cover what must not be hidden: a console on
    another stream, a KeyboardInterrupt or SystemExit the broken pipe replaced, and a
    BrokenPipeError the command raised itself with no redirection, when piped, and when redirected
    to a file. The tests for new behavior were written first and seen to fail. Those which need a real
    broken pipe are skipped on Windows, where a closed pipe can raise a different OSError that
    cmd2 has never handled
  • Every command in the new example and every snippet in the documentation was run in a
    pseudo-terminal, with output redirected to a file, and (for the example) interrupted with Ctrl-C
    and piped to commands which exit early, from inside the application and from the shell
  • The allow_style, markup, emoji, and styled-string behavior described in the documentation was
    reproduced against Rich 15.0.0
  • make check, make docs-test, and make test pass

Closes #1808

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.
@codecov

codecov Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.75%. Comparing base (c2eef0b) to head (f87ae0b).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1809   +/-   ##
=======================================
  Coverage   99.75%   99.75%           
=======================================
  Files          23       23           
  Lines        6609     6632   +23     
=======================================
+ Hits         6593     6616   +23     
  Misses         16       16           
Flag Coverage Δ
unittests 99.75% <100.00%> (+<0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

@tleonhardt tleonhardt self-assigned this Nov 13, 2026
@tleonhardt tleonhardt changed the title Document how to update output in place with the print methods Document updating output in place and add a Rich progress bar example Nov 13, 2026
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.
- 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
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.
- 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
@tleonhardt tleonhardt changed the title Document updating output in place and add a Rich progress bar example Add Rich progress docs and example, and handle broken pipes from any piped command Nov 13, 2026
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.
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.
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.
- 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.
kmvanbrunt
kmvanbrunt previously approved these changes Nov 14, 2026
Comment thread cmd2/rich_utils.py Resolved
@tleonhardt
tleonhardt merged commit 0047276 into main Nov 15, 2026
32 checks passed
@tleonhardt
tleonhardt deleted the docs-in-place-output branch November 15, 2026 20:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

poutput does not respect carriage return or ANSI clear lines

2 participants