Updated initialization.py and python_scripting.py examples for cmd2 3.0.

Deleted basic.py and pirate.py examples.

Author: kmvanbrunt

.github/CODEOWNERS

@@ -27,10 +27,10 @@
 
 # cmd2 code
 cmd2/__init__.py           @kmvanbrunt @tleonhardt
-cmd2/ansi.py               @kmvanbrunt @tleonhardt
 cmd2/argparse_*.py         @kmvanbrunt @anselor
 cmd2/clipboard.py          @tleonhardt
 cmd2/cmd2.py               @tleonhardt @kmvanbrunt
+cmd2/colors.py             @tleonhardt @kmvanbrunt
 cmd2/command_definition.py @anselor
 cmd2/constants.py          @tleonhardt @kmvanbrunt
 cmd2/decorators.py         @kmvanbrunt @anselor
@@ -39,8 +39,11 @@ cmd2/history.py            @tleonhardt
 cmd2/parsing.py            @kmvanbrunt
 cmd2/plugin.py             @anselor
 cmd2/py_bridge.py          @kmvanbrunt
+cmd2/rich_utils.py         @kmvanbrunt
 cmd2/rl_utils.py           @kmvanbrunt
-cmd2/table_creator.py      @kmvanbrunt
+cmd2/string_utils.py       @kmvanbrunt
+cmd2/styles.py             @tleonhardt @kmvanbrunt
+cmd2/terminal_utils.py     @kmvanbrunt
 cmd2/transcript.py         @tleonhardt
 cmd2/utils.py              @tleonhardt @kmvanbrunt
 

.github/CONTRIBUTING.md

@@ -269,7 +269,7 @@ uv venv --python 3.12
 Then you can run commands in this isolated virtual environment using `uv` like so:
 
 ```sh
-uv run examples/basic.py
+uv run examples/hello_cmd2.py
 ```
 
 Alternatively you can activate the virtual environment using the OS-specific command such as this on

README.md

@@ -105,10 +105,6 @@ examples.
 
 ## Tutorials
 
-- PyOhio 2019 presentation:
-    - [video](https://www.youtube.com/watch?v=pebeWrTqIIw)
-    - [slides](https://github.com/python-cmd2/talks/blob/master/PyOhio_2019/cmd2-PyOhio_2019.pdf)
-    - [example code](https://github.com/python-cmd2/talks/tree/master/PyOhio_2019/examples)
 - [Cookiecutter](https://github.com/cookiecutter/cookiecutter) Templates from community
     - Basic cookiecutter template for cmd2 application :
       https://github.com/jayrod/cookiecutter-python-cmd2

docs/features/generating_output.md

@@ -126,21 +126,6 @@ you can pad it appropriately with spaces. However, there are categories of Unico
 occupy 2 cells, and other that occupy 0. To further complicate matters, you might have included ANSI
 escape sequences in the output to generate colors on the terminal.
 
-The `cmd2.ansi.style_aware_wcswidth` function solves both of these problems. Pass it a string, and
+The `cmd2.string_utils.str_width` function solves both of these problems. Pass it a string, and
 regardless of which Unicode characters and ANSI text style escape sequences it contains, it will
 tell you how many characters on the screen that string will consume when printed.
-
-## Pretty Printing Data Structures
-
-The `cmd2.Cmd.ppretty` method is similar to the Python
-[pprint](https://docs.python.org/3/library/pprint.html) function from the standard `pprint` module.
-`cmd2.Cmd.pprint` adds the same conveniences as `cmd2.Cmd.poutput`.
-
-This method provides a capability to “pretty-print” arbitrary Python data structures in a form which
-can be used as input to the interpreter and is easy for humans to read.
-
-The formatted representation keeps objects on a single line if it can, and breaks them onto multiple
-lines if they don’t fit within the allowed width, adjustable by the width parameter defaulting to 80
-characters.
-
-Dictionaries are sorted by key before the display is computed.

docs/features/initialization.md

@@ -4,31 +4,32 @@ Here is a basic example `cmd2` application which demonstrates many capabilities
 
 ```py
     #!/usr/bin/env python3
-    # coding=utf-8
     """A simple example cmd2 application demonstrating the following:
-         1) Colorizing/stylizing output
-         2) Using multiline commands
-         3) Persistent history
-         4) How to run an initialization script at startup
-         5) How to group and categorize commands when displaying them in help
-         6) Opting-in to using the ipy command to run an IPython shell
-         7) Allowing access to your application in py and ipy
-         8) Displaying an intro banner upon starting your application
-         9) Using a custom prompt
-        10) How to make custom attributes settable at runtime
+    1) Colorizing/stylizing output
+    2) Using multiline commands
+    3) Persistent history
+    4) How to run an initialization script at startup
+    5) How to group and categorize commands when displaying them in help
+    6) Opting-in to using the ipy command to run an IPython shell
+    7) Allowing access to your application in py and ipy
+    8) Displaying an intro banner upon starting your application
+    9) Using a custom prompt
+    10) How to make custom attributes settable at runtime.
     """
+
+    from rich.style import Style
+
     import cmd2
     from cmd2 import (
-        Bg,
-        Fg,
-        style,
+        Color,
+        stylize,
     )
 
 
     class BasicApp(cmd2.Cmd):
         CUSTOM_CATEGORY = 'My Custom Commands'
 
-        def __init__(self):
+        def __init__(self) -> None:
             super().__init__(
                 multiline_commands=['echo'],
                 persistent_history_file='cmd2_history.dat',
@@ -37,7 +38,10 @@ Here is a basic example `cmd2` application which demonstrates many capabilities
             )
 
             # Prints an intro banner once upon application startup
-            self.intro = style('Welcome to cmd2!', fg=Fg.RED, bg=Bg.WHITE, bold=True)
+            self.intro = stylize(
+                'Welcome to cmd2!',
+                style=Style(color=Color.RED, bgcolor=Color.WHITE, bold=True),
+            )
 
             # Show this as the prompt when asking for input
             self.prompt = 'myapp> '
@@ -52,25 +56,34 @@ Here is a basic example `cmd2` application which demonstrates many capabilities
             self.default_category = 'cmd2 Built-in Commands'
 
             # Color to output text in with echo command
-            self.foreground_color = Fg.CYAN.name.lower()
+            self.foreground_color = Color.CYAN.value
 
             # Make echo_fg settable at runtime
-            fg_colors = [c.name.lower() for c in Fg]
+            fg_colors = [c.value for c in Color]
             self.add_settable(
-                cmd2.Settable('foreground_color', str, 'Foreground color to use with echo command', self,
-                              choices=fg_colors)
+                cmd2.Settable(
+                    'foreground_color',
+                    str,
+                    'Foreground color to use with echo command',
+                    self,
+                    choices=fg_colors,
+                )
             )
 
         @cmd2.with_category(CUSTOM_CATEGORY)
-        def do_intro(self, _):
-            """Display the intro banner"""
+        def do_intro(self, _: cmd2.Statement) -> None:
+            """Display the intro banner."""
             self.poutput(self.intro)
 
         @cmd2.with_category(CUSTOM_CATEGORY)
-        def do_echo(self, arg):
-            """Example of a multiline command"""
-            fg_color = Fg[self.foreground_color.upper()]
-            self.poutput(style(arg, fg=fg_color))
+        def do_echo(self, arg: cmd2.Statement) -> None:
+            """Example of a multiline command."""
+            self.poutput(
+                stylize(
+                    arg,
+                    style=Style(color=self.foreground_color),
+                )
+            )
 
 
     if __name__ == '__main__':

docs/features/prompt.md

@@ -6,25 +6,25 @@
 
 This prompt can be configured by setting the `cmd2.Cmd.prompt` instance attribute. This contains the
 string which should be printed as a prompt for user input. See the
-[Pirate](https://github.com/python-cmd2/cmd2/blob/main/examples/pirate.py#L39) example for the
-simple use case of statically setting the prompt.
+[Initialization](https://github.com/python-cmd2/cmd2/blob/main/examples/initialization.py) example
+for the simple use case of statically setting the prompt.
 
 ## Continuation Prompt
 
 When a user types a [Multiline Command](./multiline_commands.md) it may span more than one line of
 input. The prompt for the first line of input is specified by the `cmd2.Cmd.prompt` instance
 attribute. The prompt for subsequent lines of input is defined by the `cmd2.Cmd.continuation_prompt`
 attribute.See the
-[Initialization](https://github.com/python-cmd2/cmd2/blob/main/examples/initialization.py#L42)
-example for a demonstration of customizing the continuation prompt.
+[Initialization](https://github.com/python-cmd2/cmd2/blob/main/examples/initialization.py) example
+for a demonstration of customizing the continuation prompt.
 
 ## Updating the prompt
 
 If you wish to update the prompt between commands, you can do so using one of the
 [Application Lifecycle Hooks](./hooks.md#application-lifecycle-hooks) such as a
 [Postcommand hook](./hooks.md#postcommand-hooks). See
-[PythonScripting](https://github.com/python-cmd2/cmd2/blob/main/examples/python_scripting.py#L38-L55)
-for an example of dynamically updating the prompt.
+[PythonScripting](https://github.com/python-cmd2/cmd2/blob/main/examples/python_scripting.py) for an
+example of dynamically updating the prompt.
 
 ## Asynchronous Feedback
 

docs/migrating/next_steps.md

@@ -41,5 +41,5 @@ to `cmd2.Cmd.poutput`, `cmd2.Cmd.perror`, and `cmd2.Cmd.pfeedback`. These method
 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.ansi.style` function. These and other related topics are covered in
+`cmd2.string_utils.stylize` function. These and other related topics are covered in
 [Generating Output](../features/generating_output.md).

examples/README.md

@@ -25,9 +25,6 @@ each:
 - [async_printing.py](https://github.com/python-cmd2/cmd2/blob/main/examples/async_printing.py)
     - Shows how to asynchronously print alerts, update the prompt in realtime, and change the window
       title
-- [basic.py](https://github.com/python-cmd2/cmd2/blob/main/examples/basic.py)
-    - Shows how to add a command, add help for it, and create persistent command history for your
-      application
 - [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/main/examples/basic_completion.py)
     - Show how to enable custom tab completion by assigning a completer function to `do_*` commands
 - [cmd2_as_argument.py](https://github.com/python-cmd2/cmd2/blob/main/examples/cmd_as_argument.py)
@@ -81,9 +78,6 @@ each:
     - Shows how to use output pagination within `cmd2` apps via the `ppaged` method
 - [persistent_history.py](https://github.com/python-cmd2/cmd2/blob/main/examples/persistent_history.py)
     - Shows how to enable persistent history in your `cmd2` application
-- [pirate.py](https://github.com/python-cmd2/cmd2/blob/main/examples/pirate.py)
-    - Demonstrates many features including colorized output, multiline commands, shorcuts,
-      defaulting to shell, etc.
 - [pretty_print.py](https://github.com/python-cmd2/cmd2/blob/main/examples/pretty_print.py)
     - Demonstrates use of cmd2.Cmd.ppretty() for pretty-printing arbitrary Python data structures
       like dictionaries.

examples/basic.py

@@ -12,11 +12,12 @@
 10) How to make custom attributes settable at runtime.
 """
 
+from rich.style import Style
+
 import cmd2
 from cmd2 import (
-    Bg,
-    Fg,
-    style,
+    Color,
+    stylize,
 )
 
 
@@ -32,7 +33,10 @@ def __init__(self) -> None:
         )
 
         # Prints an intro banner once upon application startup
-        self.intro = style('Welcome to cmd2!', fg=Fg.RED, bg=Bg.WHITE, bold=True)
+        self.intro = stylize(
+            'Welcome to cmd2!',
+            style=Style(color=Color.RED, bgcolor=Color.WHITE, bold=True),
+        )
 
         # Show this as the prompt when asking for input
         self.prompt = 'myapp> '
@@ -47,24 +51,34 @@ def __init__(self) -> None:
         self.default_category = 'cmd2 Built-in Commands'
 
         # Color to output text in with echo command
-        self.foreground_color = Fg.CYAN.name.lower()
+        self.foreground_color = Color.CYAN.value
 
         # Make echo_fg settable at runtime
-        fg_colors = [c.name.lower() for c in Fg]
+        fg_colors = [c.value for c in Color]
         self.add_settable(
-            cmd2.Settable('foreground_color', str, 'Foreground color to use with echo command', self, choices=fg_colors)
+            cmd2.Settable(
+                'foreground_color',
+                str,
+                'Foreground color to use with echo command',
+                self,
+                choices=fg_colors,
+            )
         )
 
     @cmd2.with_category(CUSTOM_CATEGORY)
-    def do_intro(self, _) -> None:
+    def do_intro(self, _: cmd2.Statement) -> None:
         """Display the intro banner."""
         self.poutput(self.intro)
 
     @cmd2.with_category(CUSTOM_CATEGORY)
-    def do_echo(self, arg) -> None:
+    def do_echo(self, arg: cmd2.Statement) -> None:
         """Example of a multiline command."""
-        fg_color = Fg[self.foreground_color.upper()]
-        self.poutput(style(arg, fg=fg_color))
+        self.poutput(
+            stylize(
+                arg,
+                style=Style(color=self.foreground_color),
+            )
+        )
 
 
 if __name__ == '__main__':