From c4885406ada987c9d7055100c99ec404e775673f Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sat, 13 Sep 2025 13:04:36 -0400 Subject: [PATCH 1/5] First pass at removing outdated info from the documentation based on changes in the 3.0.0 release and adding info on new capabilities --- docs/features/argument_processing.md | 4 ---- docs/features/generating_output.md | 21 ++++++++++++++++++--- docs/features/table_creation.md | 3 +++ docs/migrating/next_steps.md | 6 +++--- 4 files changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md index 9535d5e21..f4943cbff 100644 --- a/docs/features/argument_processing.md +++ b/docs/features/argument_processing.md @@ -61,10 +61,6 @@ def do_speak(self, opts): self.poutput(arg) ``` -!!! note - - `cmd2` sets the `prog` variable in the argument parser based on the name of the method it is decorating. This will override anything you specify in `prog` variable when creating the argument parser. - ## Help Messages By default, `cmd2` uses the docstring of the command method when a user asks for help on the diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index b423258d0..b9356bfe0 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -19,6 +19,11 @@ output you generate must be sent to `self.stdout`. You can use the methods descr everything will work fine. [cmd2.Cmd][] also includes a number of output related methods which you may use to enhance the output your application produces. +Since `cmd2` has a dependency on the [rich](https://github.com/Textualize/rich) library, all of +`cmd2`'s output methods can natively render `rich` +[renderable objects](https://rich.readthedocs.io/en/latest/protocol.html), enabling beautiful and +complex output. + ## Ordinary Output The `cmd2.Cmd.poutput` method is similar to the Python @@ -92,6 +97,16 @@ following sections: - [cmd2.string_utils][] - [cmd2.terminal_utils][] +The [color.py](https://github.com/python-cmd2/cmd2/blob/main/examples/color.py) example demonstrates +all colors available to your `cmd2` application. + +### Custom Themes + +`cmd2` uses a `rich` `Theme` object to define styles for various UI elements. You can define your +own custom theme using `cmd2.rich_utils.set_theme`. See the +[rich_theme.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_theme.py) example for +more information. + After adding the desired escape sequences to your output, you should use one of these methods to present the output to the user: @@ -110,9 +125,9 @@ to control whether these escape codes are passed through to the terminal or not. If you would like to generate output which is left, center, or right aligned within a specified width or the terminal width, the following functions can help: -- `cmd2.utils.align_left` -- `cmd2.utils.align_center` -- `cmd2.utils.align_right` +- `cmd2.string_utils.align_left` +- `cmd2.string_utils.align_center` +- `cmd2.string_utils.align_right` These functions differ from Python's string justifying functions in that they support characters with display widths greater than 1. Additionally, ANSI style sequences are safely ignored and do not diff --git a/docs/features/table_creation.md b/docs/features/table_creation.md index 2509ba45f..4a54cadd4 100644 --- a/docs/features/table_creation.md +++ b/docs/features/table_creation.md @@ -7,3 +7,6 @@ excellent support for this feature. Please see rich's documentation on [Tables](https://rich.readthedocs.io/en/latest/tables.html) for more information. + +The [rich_tables.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_tables.py) example +demonstrates how to use `rich` tables in a `cmd2` application. diff --git a/docs/migrating/next_steps.md b/docs/migrating/next_steps.md index a261bccfd..1e047a524 100644 --- a/docs/migrating/next_steps.md +++ b/docs/migrating/next_steps.md @@ -41,6 +41,6 @@ If your program generates output by printing directly to `sys.stdout`, you shoul to `cmd2.Cmd.poutput`, `cmd2.Cmd.perror`, and `cmd2.Cmd.pfeedback`. These methods work with several of the built in [Settings](../features/settings.md) to allow the user to view or suppress feedback (i.e. progress or status output). They also properly handle ANSI colored output according to user -preference. Speaking of colored output, you can use any color library you want, or use the included -`cmd2.string_utils.stylize` function. These and other related topics are covered in -[Generating Output](../features/generating_output.md). +preference. `cmd2`'s dependency on `rich` makes it easy to add color and style to your output. See +the [Colored Output](../features/generating_output.md#colored-output) section for more details. +These and other related topics are covered in [Generating Output](../features/generating_output.md). From 2043357ea747eff7f5bbf10cce39a2fb257ded6c Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sat, 13 Sep 2025 13:39:59 -0400 Subject: [PATCH 2/5] Add a note back in that shouldn't have been deleted and try to update it for 3.0.0 --- docs/features/argument_processing.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md index f4943cbff..1c1d2e6f2 100644 --- a/docs/features/argument_processing.md +++ b/docs/features/argument_processing.md @@ -61,6 +61,12 @@ def do_speak(self, opts): self.poutput(arg) ``` +!!! note + + `cmd2` sets the `prog` variable in the argument parser based on the name of the method it is decorating. This will override anything you specify in `prog` variable when creating the argument parser. + + As of the 3.0.0 release, `cmd2` now sets the `prog` later than it did previously. `prog` now gets set when the instance-specific parser deep copy is created. Previously, it was set in the `with_argparser` decorator itself. + ## Help Messages By default, `cmd2` uses the docstring of the command method when a user asks for help on the From 742cddb6eabbca5c12709dd37b76b7bf5851fd10 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sat, 13 Sep 2025 14:17:44 -0400 Subject: [PATCH 3/5] Minor grammar fix --- docs/features/argument_processing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md index 1c1d2e6f2..bc6156b6b 100644 --- a/docs/features/argument_processing.md +++ b/docs/features/argument_processing.md @@ -65,7 +65,7 @@ def do_speak(self, opts): `cmd2` sets the `prog` variable in the argument parser based on the name of the method it is decorating. This will override anything you specify in `prog` variable when creating the argument parser. - As of the 3.0.0 release, `cmd2` now sets the `prog` later than it did previously. `prog` now gets set when the instance-specific parser deep copy is created. Previously, it was set in the `with_argparser` decorator itself. + As of the 3.0.0 release, `cmd2` now sets `prog` later than it did previously. `prog` now gets set when the instance-specific parser deep-copy is created. Previously, it was set in the `with_argparser` decorator itself. ## Help Messages From 5b9e3a1c431a6005f5c53d3e664445111ab49082 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sat, 13 Sep 2025 14:30:48 -0400 Subject: [PATCH 4/5] Update docs/features/argument_processing.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/features/argument_processing.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md index bc6156b6b..3840087cb 100644 --- a/docs/features/argument_processing.md +++ b/docs/features/argument_processing.md @@ -65,8 +65,7 @@ def do_speak(self, opts): `cmd2` sets the `prog` variable in the argument parser based on the name of the method it is decorating. This will override anything you specify in `prog` variable when creating the argument parser. - As of the 3.0.0 release, `cmd2` now sets `prog` later than it did previously. `prog` now gets set when the instance-specific parser deep-copy is created. Previously, it was set in the `with_argparser` decorator itself. - +As of the 3.0.0 release, `cmd2` sets `prog` when the instance-specific parser is created, which is later than it did previously. ## Help Messages By default, `cmd2` uses the docstring of the command method when a user asks for help on the From 9fd6ebdc72010699dcb68c7f6ddf1633905871de Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sat, 13 Sep 2025 14:34:10 -0400 Subject: [PATCH 5/5] Run prettier on documentation auto-updated by gemini-cli --- docs/features/argument_processing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md index 3840087cb..5f3392d16 100644 --- a/docs/features/argument_processing.md +++ b/docs/features/argument_processing.md @@ -65,7 +65,9 @@ def do_speak(self, opts): `cmd2` sets the `prog` variable in the argument parser based on the name of the method it is decorating. This will override anything you specify in `prog` variable when creating the argument parser. -As of the 3.0.0 release, `cmd2` sets `prog` when the instance-specific parser is created, which is later than it did previously. +As of the 3.0.0 release, `cmd2` sets `prog` when the instance-specific parser is created, which is +later than it did previously. + ## Help Messages By default, `cmd2` uses the docstring of the command method when a user asks for help on the