Refactored cmd2 to better account for our use of Rich. (#1477)

* Added string_utils.py which contains all string utility functions.
  This includes quoting and alignment functions from utils.py.
  This also includes style-related functions from ansi.py.

* Added colors.py which contains a StrEnum of all color names supported by Rich.

* Added styles.py which contains a StrEnum of all cmd2-specific style names and their respective
   style definitions.

* Moved string styling functionality from ansi.py to string_utils.py.

* Removed all text style Enums from ansi.py in favor of Rich styles.

* Renamed ansi.py to terminal_utils.py to reflect the functions left in it.

* Removed table_creator.py in favor of Rich tables.

* Renamed rich_utils.allow_style to rich_utils.ALLOW_STYLE to be consistent with our other global settings.

---------

Co-authored-by: Todd Leonhardt <[email protected]>

Author: kmvanbrunt

.github/CONTRIBUTING.md

@@ -60,15 +60,19 @@ Nearly all project configuration, including for dependencies and quality tools i
 
 See the `dependencies` list under the `[project]` heading in [pyproject.toml](../pyproject.toml).
 
-| Prerequisite                                        | Minimum Version | Purpose                                |
-| --------------------------------------------------- | --------------- | -------------------------------------- |
-| [python](https://www.python.org/downloads/)         | `3.10`          | Python programming language            |
-| [pyperclip](https://github.com/asweigart/pyperclip) | `1.8`           | Cross-platform clipboard functions     |
-| [wcwidth](https://pypi.python.org/pypi/wcwidth)     | `0.2.10`        | Measure the displayed width of unicode |
+| Prerequisite                                               | Minimum Version | Purpose                                                |
+| ---------------------------------------------------------- | --------------- | ------------------------------------------------------ |
+| [python](https://www.python.org/downloads/)                | `3.10`          | Python programming language                            |
+| [pyperclip](https://github.com/asweigart/pyperclip)        | `1.8`           | Cross-platform clipboard functions                     |
+| [rich](https://github.com/Textualize/rich)                 | `14.1.0`        | Add rich text and beautiful formatting in the terminal |
+| [rich-argparse](https://github.com/hamdanal/rich-argparse) | `1.7.1`         | A rich-enabled help formatter for argparse             |
 
 > `macOS` and `Windows` each have an extra dependency to ensure they have a viable alternative to
 > [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) available.
 
+> Python 3.10 depends on [backports.strenum](https://github.com/clbarnes/backports.strenum) to use
+> the `enum.StrEnum` class introduced in Python 3.11.
+
 #### Additional prerequisites to build and publish cmd2
 
 See the `build` list under the `[dependency-groups]` heading in [pyproject.toml](../pyproject.toml)

CHANGELOG.md

@@ -5,17 +5,26 @@
     - No longer setting parser's `prog` value in `with_argparser()` since it gets set in
       `Cmd._build_parser()`. This code had previously been restored to support backward
       compatibility in `cmd2` 2.0 family.
+    - Removed table_creator.py in favor of `Rich` tables.
+    - Moved string styling functionality from ansi.py to string_utils.py.
+    - Moved all string-related functions from utils.py to string_utils.py.
+    - Removed all text style Enums from ansi.py in favor of `Rich` styles.
+    - Renamed ansi.py to terminal_utils.py to reflect the functions left in it.
 
 - Enhancements
     - Simplified the process to set a custom parser for `cmd2's` built-in commands. See
       [custom_parser.py](https://github.com/python-cmd2/cmd2/blob/main/examples/custom_parser.py)
       example for more details.
-
     - Added `Cmd.macro_arg_complete()` which tab completes arguments to a macro. Its default
       behavior is to perform path completion, but it can be overridden as needed.
-
     - All print methods (`poutput()`, `perror()`, `ppaged()`, etc.) have the ability to print Rich
       objects.
+    - Added string_utils.py which contains all string utility functions. This includes quoting and
+      alignment functions from utils.py. This also includes style-related functions from ansi.py.
+      This also includes style-related functions from ansi.py.
+    - Added colors.py which contains a StrEnum of all color names supported by Rich.
+    - Added styles.py which contains a StrEnum of all cmd2-specific style names and their respective
+      style definitions.
 
 - Bug Fixes
     - No longer redirecting `sys.stdout` if it's a different stream than `self.stdout`. This fixes

cmd2/__init__.py

@@ -9,17 +9,7 @@
 from . import (
     plugin,
     rich_utils,
-)
-from .ansi import (
-    Bg,
-    Cursor,
-    EightBitBg,
-    EightBitFg,
-    Fg,
-    RgbBg,
-    RgbFg,
-    TextStyle,
-    style,
+    string_utils,
 )
 from .argparse_completer import set_default_ap_completer_type
 from .argparse_custom import (
@@ -30,6 +20,7 @@
     set_default_argument_parser_type,
 )
 from .cmd2 import Cmd
+from .colors import Color
 from .command_definition import (
     CommandSet,
     with_default_category,
@@ -53,6 +44,8 @@
 )
 from .parsing import Statement
 from .py_bridge import CommandResult
+from .string_utils import stylize
+from .styles import Cmd2Style
 from .utils import (
     CompletionMode,
     CustomCompletionSettings,
@@ -63,16 +56,6 @@
 __all__: list[str] = [  # noqa: RUF022
     'COMMAND_NAME',
     'DEFAULT_SHORTCUTS',
-    # ANSI Exports
-    'Cursor',
-    'Bg',
-    'Fg',
-    'EightBitBg',
-    'EightBitFg',
-    'RgbBg',
-    'RgbFg',
-    'TextStyle',
-    'style',
     # Argparse Exports
     'Cmd2ArgumentParser',
     'Cmd2AttributeWrapper',
@@ -85,6 +68,8 @@
     'CommandResult',
     'CommandSet',
     'Statement',
+    # Colors
+    "Color",
     # Decorators
     'with_argument_list',
     'with_argparser',
@@ -100,6 +85,11 @@
     # modules
     'plugin',
     'rich_utils',
+    'string_utils',
+    # String Utils
+    'stylize',
+    # Styles,
+    "Cmd2Style",
     # Utilities
     'categorize',
     'CompletionMode',