Added additional prompt-toolkit completion styles to cmd2's rich theme

Also:
- Updated outdated docstring that was insufficiently broad
- Updated rich_theme.py example to use new completion styles
- Updated CHANGELOG and documentation

Author: tleonhardt

CHANGELOG.md

@@ -151,8 +151,16 @@ prompt is displayed.
     - Added `Cmd2ArgumentParser.output_to()` context manager to temporarily set the output stream
       during `argparse` operations. This is helpful for directing output for functions like
       `parse_args()`, which default to `sys.stdout` and lack a `file` argument.
-    - Added ability to customize `prompt-toolkit` completion menu colors by overriding
-      `Cmd2Style.COMPLETION_MENU_ITEM` and `Cmd2Style.COMPLETION_MENU_META` in the `cmd2` theme.
+    - Added ability to customize `prompt-toolkit` completion menu colors by overriding the following
+      fields in the `cmd2` theme:
+        - `Cmd2Style.COMPLETION_MENU` - Base style for the entire completion menu container (sets
+          the background)
+        - `Cmd2Style.COMPLETION_MENU_COMPLETION` -Style for an individual, non-selected completion
+          item
+        - `Cmd2Style.COMPLETION_MENU_CURRENT` - Style for the currently selected completion item
+        - `Cmd2Style.COMPLETION_MENU_META` - Style for "meta" information shown alongside a
+          completion
+        - `Cmd2Style.COMPLETION_MENU_META_CURRENT`- Style for meta info of current item
 
 ## 3.5.1 (April 24, 2026)
 

cmd2/cmd2.py

@@ -529,7 +529,7 @@ def __init__(
 
         # Cache for prompt_toolkit completion menu styles
         self._cached_pt_style: PtStyle | None = None
-        self._cached_pt_style_params: tuple[StyleType, StyleType] | None = None
+        self._cached_pt_style_params: tuple[StyleType, StyleType, StyleType, StyleType, StyleType] | None = None
 
         # Create the main PromptSession
         self.bottom_toolbar = bottom_toolbar
@@ -725,24 +725,33 @@ def _should_continue_multiline(self) -> bool:
                 return False
 
     def _get_pt_style(self) -> "PtStyle":
-        """Return the prompt_toolkit style for the completion menu."""
+        """Return the cached prompt_toolkit style."""
         theme = ru.get_theme()
-        rich_item_style = theme.styles.get(Cmd2Style.COMPLETION_MENU_ITEM, "")
+        rich_menu_style = theme.styles.get(Cmd2Style.COMPLETION_MENU, "")
+        rich_completion_style = theme.styles.get(Cmd2Style.COMPLETION_MENU_COMPLETION, "")
+        rich_current_style = theme.styles.get(Cmd2Style.COMPLETION_MENU_CURRENT, "")
         rich_meta_style = theme.styles.get(Cmd2Style.COMPLETION_MENU_META, "")
+        rich_meta_current_style = theme.styles.get(Cmd2Style.COMPLETION_MENU_META_CURRENT, "")
 
-        current_params = (rich_item_style, rich_meta_style)
+        current_params = (rich_menu_style, rich_completion_style, rich_current_style, rich_meta_style, rich_meta_current_style)
         if self._cached_pt_style is not None and self._cached_pt_style_params == current_params:
             return self._cached_pt_style
 
-        item_style = rich_to_pt_style(rich_item_style)
+        menu_style = rich_to_pt_style(rich_menu_style)
+        completion_style = rich_to_pt_style(rich_completion_style)
+        current_style = rich_to_pt_style(rich_current_style)
         meta_style = rich_to_pt_style(rich_meta_style)
+        meta_current_style = rich_to_pt_style(rich_meta_current_style)
 
         self._cached_pt_style_params = current_params
         self._cached_pt_style = PtStyle.from_dict(
             {
-                "completion-menu.completion.current": item_style,
-                "completion-menu.meta.completion.current": meta_style,
-                "completion-menu.multi-column-meta": meta_style,
+                "completion-menu": menu_style,
+                "completion-menu.completion": completion_style,
+                "completion-menu.completion.current": current_style,
+                "completion-menu.meta.completion": meta_style,
+                "completion-menu.meta.completion.current": meta_current_style,
+                "completion-menu.multi-column-meta": meta_current_style,
             }
         )
 

cmd2/styles.py

@@ -22,6 +22,8 @@
 For rich-argparse, the style names are defined in the
 `rich_argparse.RichHelpFormatter.styles` dictionary.
 
+For prompt-toolkit default styles, see:
+https://github.com/prompt-toolkit/python-prompt-toolkit/blob/main/src/prompt_toolkit/styles/defaults.py
 """
 
 import sys
@@ -51,8 +53,11 @@ class Cmd2Style(StrEnum):
     """
 
     COMMAND_LINE = "cmd2.example"  # Command line examples in help text
-    COMPLETION_MENU_ITEM = "cmd2.completion_menu.item"  # Selected completion item
-    COMPLETION_MENU_META = "cmd2.completion_menu.meta"  # Selected completion help/meta text
+    COMPLETION_MENU = "cmd2.completion_menu"  # Base style for the entire completion menu container (sets the background)
+    COMPLETION_MENU_COMPLETION = "cmd2.completion-menu.completion"  # Style for an individual, non-selected completion item
+    COMPLETION_MENU_CURRENT = "cmd2.completion-menu.completion.current"  # Style for the currently selected completion item
+    COMPLETION_MENU_META = "cmd2.completion-menu.meta.completion"  # Style for "meta" information shown alongside a completion
+    COMPLETION_MENU_META_CURRENT = "cmd2.completion-menu.meta.completion.current"  # Style for meta info of current item
     ERROR = "cmd2.error"  # Error text (used by perror())
     HELP_HEADER = "cmd2.help.header"  # Help table header text
     HELP_LEADER = "cmd2.help.leader"  # Text right before the help tables are listed
@@ -70,8 +75,11 @@ class Cmd2Style(StrEnum):
 # Tightly coupled with the Cmd2Style enum.
 DEFAULT_CMD2_STYLES: dict[str, StyleType] = {
     Cmd2Style.COMMAND_LINE: Style(color=Color.CYAN, bold=True),
-    Cmd2Style.COMPLETION_MENU_ITEM: Style(color=Color.BLACK, bgcolor=Color.GREEN),
-    Cmd2Style.COMPLETION_MENU_META: Style(color=Color.BLACK, bgcolor=Color.BRIGHT_GREEN),
+    Cmd2Style.COMPLETION_MENU: Style(color="#000000", bgcolor="#bbbbbb"),  # prompt-toolkit default
+    Cmd2Style.COMPLETION_MENU_COMPLETION: Style(),  # prompt-toolkit default
+    Cmd2Style.COMPLETION_MENU_CURRENT: Style(color=Color.GREEN, bgcolor=Color.BLACK),  # This style swaps FG and BG colors
+    Cmd2Style.COMPLETION_MENU_META: Style(color="#000000", bgcolor="#bbbbbb"),  # prompt-toolkit default
+    Cmd2Style.COMPLETION_MENU_META_CURRENT: Style(color=Color.BLACK, bgcolor=Color.BRIGHT_GREEN),
     Cmd2Style.ERROR: Style(color=Color.BRIGHT_RED),
     Cmd2Style.HELP_HEADER: Style(color=Color.BRIGHT_GREEN),
     Cmd2Style.HELP_LEADER: Style(color=Color.CYAN),

docs/features/theme.md

@@ -11,12 +11,17 @@ that is appealing to your user base.
 `cmd2` leverages `prompt-toolkit` for its tab completion menu. You can customize the colors of the
 completion menu by overriding the following styles in your `cmd2` theme:
 
-- `Cmd2Style.COMPLETION_MENU_ITEM`: The background and foreground color of the selected completion
-  item.
-- `Cmd2Style.COMPLETION_MENU_META`: The background and foreground color of the selected completion
-  item's help/meta text.
+- `Cmd2Style.COMPLETION_MENU` - Base style for the entire completion menu container (sets the
+  background)
+- `Cmd2Style.COMPLETION_MENU_COMPLETION` -Style for an individual, non-selected completion item
+- `Cmd2Style.COMPLETION_MENU_CURRENT` - Style for the currently selected completion item
+- `Cmd2Style.COMPLETION_MENU_META` - Style for "meta" information shown alongside a completion
+- `Cmd2Style.COMPLETION_MENU_META_CURRENT`- Style for meta info of current item
 
-By default, these are styled with black text on a green background to provide contrast.
+By default, the currently selected completion item and metadata are styled with black text on a
+green background to provide contrast. All others are left at `prompt-toolkit` defaults by default.
+However, `cmd2` application authors are free to customimze these as they see fit in order to match a
+desired visual style and/or branding.
 
 ## Example
 

docs/upgrades.md

@@ -51,7 +51,7 @@ periodically.
 `cmd2` now leverages `prompt-toolkit` for its tab completion menu and provides the ability to
 customize its appearance using the `cmd2` theme.
 
-- **Customization**: Override the `Cmd2Style.COMPLETION_MENU_ITEM` and
+- **Customization**: Override the `Cmd2Style.COMPLETION_MENU_CURRENT` and
   `Cmd2Style.COMPLETION_MENU_META` styles using `cmd2.rich_utils.set_theme()`. See
   [Customizing Completion Menu Colors](features/theme.md#customizing-completion-menu-colors) for
   more details.

examples/rich_theme.py

@@ -34,8 +34,11 @@ def __init__(self, *args, **kwargs):
             Cmd2Style.LEXER_MACRO: Style(color=Color.LIGHT_CORAL),
             Cmd2Style.LEXER_FLAG: Style(color=Color.LIGHT_PINK3),
             Cmd2Style.LEXER_ARGUMENT: Style(color=Color.LIGHT_GOLDENROD1),
-            Cmd2Style.COMPLETION_MENU_ITEM: Style(color=Color.WHITE, bgcolor=Color.NAVY_BLUE),
-            Cmd2Style.COMPLETION_MENU_META: Style(color=Color.WHITE, bgcolor=Color.DARK_SLATE_GRAY2),
+            Cmd2Style.COMPLETION_MENU: Style(color="#000000", bgcolor=Color.SKY_BLUE1),
+            Cmd2Style.COMPLETION_MENU_COMPLETION: Style(color=Color.MAGENTA),
+            Cmd2Style.COMPLETION_MENU_CURRENT: Style(color=Color.WHITE, bgcolor=Color.NAVY_BLUE),
+            Cmd2Style.COMPLETION_MENU_META: Style(color="#000000", bgcolor=Color.CYAN),
+            Cmd2Style.COMPLETION_MENU_META_CURRENT: Style(color=Color.WHITE, bgcolor=Color.DARK_SLATE_GRAY2),
             "traceback.exc_type": Style(color=Color.RED, bgcolor=Color.LIGHT_YELLOW3, bold=True),
             "argparse.args": Style(color=Color.AQUAMARINE3, underline=True),
         }

tests/test_cmd2.py

@@ -1889,7 +1889,7 @@ def test_get_pt_style_caching(base_app) -> None:
     orig_theme = ru.get_theme()
 
     try:
-        ru.set_theme({Cmd2Style.COMPLETION_MENU_ITEM: Style(color="red")})
+        ru.set_theme({Cmd2Style.COMPLETION_MENU_CURRENT: Style(color="red")})
 
         # Getting the style now should return a new object
         style3 = base_app._get_pt_style()