Added functions for registering synchronized styles.

Author: kmvanbrunt

cmd2/__init__.py

@@ -59,9 +59,11 @@
     get_theme,
     register_pt_mapping,
     register_synchronized_prefix,
+    register_synchronized_style,
     set_theme,
     unregister_pt_mapping,
     unregister_synchronized_prefix,
+    unregister_synchronized_style,
 )
 from .utils import (
     CustomCompletionSettings,
@@ -120,9 +122,11 @@
     "get_theme",
     "register_pt_mapping",
     "register_synchronized_prefix",
+    "register_synchronized_style",
     "set_theme",
     "unregister_pt_mapping",
     "unregister_synchronized_prefix",
+    "unregister_synchronized_style",
     # Utilities
     "categorize",
     "CustomCompletionSettings",

cmd2/theme.py

@@ -46,7 +46,12 @@
 # Maps style names to internal UI component names used by prompt-toolkit.
 # This allows developers to use application-specific style names in set_theme()
 # while ensuring the underlying prompt-toolkit UI is styled correctly.
-# Use register_pt_mapping() to modify it.
+# Use register_pt_mapping() and unregister_pt_mapping() to manage these mappings.
+#
+# Presence in this mapping, even with an empty set of UI component names, flags the
+# style for synchronization to the prompt-toolkit theme. Use register_synchronized_style()
+# and unregister_synchronized_style() to manage synchronization for styles that lack a
+# registered prefix and do not require specific UI component mappings.
 _PT_UI_MAP: dict[str, set[str]] = {
     Cmd2Style.COMPLETION_MENU: {"completion-menu"},
     Cmd2Style.COMPLETION_MENU_COMPLETION: {"completion-menu.completion"},
@@ -58,8 +63,9 @@
     },
 }
 
-# Only Rich styles starting with one of these prefixes are synchronized to
-# the prompt-toolkit theme. Use register_synchronized_prefix() to modify it.
+# Rich styles that start with one of these prefixes are automatically
+# synchronized to the prompt-toolkit theme. Use register_synchronized_prefix()
+# and unregister_synchronized_prefix() to modify this set.
 _SYNCHRONIZED_PREFIXES: set[str] = {"cmd2."}
 
 
@@ -135,7 +141,7 @@ def _sync_pt_theme() -> None:
             # Register the style name as a prompt-toolkit class (accessible via 'class:name')
             style_rules.append((name, pt_style_str))
 
-            # Add any prompt-toolkit UI component aliases from the map (e.g., 'completion-menu')
+            # Add any prompt-toolkit UI component names from the map (e.g., 'completion-menu')
             if is_mapped_style:
                 style_rules.extend((pt_name, pt_style_str) for pt_name in _PT_UI_MAP[name])
 
@@ -159,22 +165,23 @@ def register_pt_mapping(style_name: str, pt_ui_names: str | Iterable[str]) -> No
     This enables styling of prompt-toolkit's internal elements (such as the
     completion menu) using styles in the application's Rich theme.
 
+    Registering a mapping also flags the style for synchronization to the
+    prompt-toolkit theme, making it accessible via 'class:style_name'.
+
     :param style_name: The style name used in the Rich theme.
     :param pt_ui_names: One or more prompt-toolkit UI component names (e.g., 'completion-menu').
     """
     if isinstance(pt_ui_names, str):
         pt_ui_names = [pt_ui_names]
 
-    # Register the style in the map. Presence in this map, even with an empty set,
-    # is the trigger that flags this style for synchronization to prompt-toolkit.
-    # This is helpful for styles which do not begin with a registered prefix.
+    # Register the style in the map.
     if style_name not in _PT_UI_MAP:
         _PT_UI_MAP[style_name] = set()
         changed = True
     else:
         changed = False
 
-    # Add UI aliases, excluding 'style_name' which the sync handles by default.
+    # Add UI mappings, excluding 'style_name' which the sync handles by default.
     original_size = len(_PT_UI_MAP[style_name])
     _PT_UI_MAP[style_name].update(n for n in pt_ui_names if n != style_name)
 
@@ -186,42 +193,64 @@ def register_pt_mapping(style_name: str, pt_ui_names: str | Iterable[str]) -> No
         _sync_pt_theme()
 
 
-def unregister_pt_mapping(style_name: str, pt_ui_names: str | Iterable[str] | None = None) -> None:
+def register_synchronized_style(style_name: str) -> None:
+    """Register a Rich theme style for synchronization with prompt-toolkit.
+
+    This ensures that the style is synchronized to the prompt-toolkit theme
+    (accessible via 'class:style_name') even if it does not begin with a
+    registered prefix.
+
+    :param style_name: The style name used in the Rich theme.
+    """
+    register_pt_mapping(style_name, [])
+
+
+def unregister_pt_mapping(style_name: str, pt_ui_names: str | Iterable[str]) -> None:
     """Remove one or more prompt-toolkit UI component mappings.
 
-    If pt_ui_names is None, all mappings for the given style_name are removed.
+    The style itself remains in the synchronization mapping (even if no
+    UI component mappings remain), ensuring it continues to be synchronized
+    to the prompt-toolkit theme.
+
+    To completely remove a style from synchronization, use
+    unregister_synchronized_style().
 
     :param style_name: The style name used in the Rich theme.
-    :param pt_ui_names: Specific UI component(s) to unmap, or None to clear all.
+    :param pt_ui_names: Specific UI component(s) to unmap.
     """
     if style_name not in _PT_UI_MAP:
         return
 
-    changed = False
-
-    if pt_ui_names is None:
-        del _PT_UI_MAP[style_name]
-        changed = True
-    else:
-        if isinstance(pt_ui_names, str):
-            pt_ui_names = [pt_ui_names]
-
-        original_size = len(_PT_UI_MAP[style_name])
-        for name in pt_ui_names:
-            _PT_UI_MAP[style_name].discard(name)
+    if isinstance(pt_ui_names, str):
+        pt_ui_names = [pt_ui_names]
 
-        changed = len(_PT_UI_MAP[style_name]) < original_size
+    original_size = len(_PT_UI_MAP[style_name])
+    for name in pt_ui_names:
+        _PT_UI_MAP[style_name].discard(name)
 
-        # Clean up the key if no mappings remain
-        if not _PT_UI_MAP[style_name]:
-            del _PT_UI_MAP[style_name]
-            changed = True
+    changed = len(_PT_UI_MAP[style_name]) < original_size
 
     # Trigger a re-sync if the theme is already initialized
     if changed and _PT_THEME is not None:
         _sync_pt_theme()
 
 
+def unregister_synchronized_style(style_name: str) -> None:
+    """Stop synchronizing a Rich theme style with prompt-toolkit.
+
+    This removes the style and all its mappings entirely from the
+    prompt-toolkit theme synchronization.
+
+    :param style_name: The style name to unregister.
+    """
+    if style_name in _PT_UI_MAP:
+        del _PT_UI_MAP[style_name]
+
+        # Trigger a re-sync if the theme is already initialized
+        if _PT_THEME is not None:
+            _sync_pt_theme()
+
+
 def register_synchronized_prefix(prefix: str) -> None:
     """Register a prefix whose styles will be synchronized to the prompt-toolkit theme.
 

tests/test_theme.py

@@ -15,9 +15,11 @@
     get_theme,
     register_pt_mapping,
     register_synchronized_prefix,
+    register_synchronized_style,
     set_theme,
     unregister_pt_mapping,
     unregister_synchronized_prefix,
+    unregister_synchronized_style,
 )
 
 
@@ -99,7 +101,7 @@ def test_pt_theme_is_none() -> None:
 
 
 def test_register_pt_mapping() -> None:
-    """Test style to UI mapping."""
+    """Test style registration with UI mapping."""
     style_name = "my_custom_scrollbar"
     ui_name = "scrollbar"
 
@@ -147,7 +149,7 @@ def test_register_pt_mapping_existing_style() -> None:
 
 
 def test_unregister_pt_mapping() -> None:
-    """Test unmapping styles from UI components."""
+    """Test unregistering UI mappings from styles."""
     from prompt_toolkit.styles import DEFAULT_ATTRS
 
     style_name = "custom_scroll"
@@ -166,28 +168,59 @@ def test_unregister_pt_mapping() -> None:
     assert pt_theme.get_attrs_for_style_str("class:scroll1") == DEFAULT_ATTRS
     assert pt_theme.get_attrs_for_style_str("class:scroll2").color == "ansired"
 
-    # Unregister the entire style mapping
-    unregister_pt_mapping(style_name)
+    # Unregister the other UI component
+    unregister_pt_mapping(style_name, "scroll2")
     pt_theme = get_pt_theme()
     assert pt_theme.get_attrs_for_style_str("class:scroll2") == DEFAULT_ATTRS
 
 
 def test_unregister_pt_mapping_nonexistent() -> None:
-    """Test unregistering a mapping that doesn't exist."""
-    unregister_pt_mapping("nonexistent_style")
+    """Test unregistering a style that doesn't exist."""
+    unregister_pt_mapping("nonexistent_style", "some_ui")
 
 
-def test_unregister_pt_mapping_cleans_up_key() -> None:
-    """Test that unregistering the last UI component removes the style key."""
-    style_name = "cleanup_style"
-    ui_name = "cleanup_ui"
+def test_unregister_pt_mapping_preserves_key() -> None:
+    """Test that unregistering UI components preserves the style key for synchronization."""
+    style_name = "preserved_style"
+    ui_name = "some_ui"
     register_pt_mapping(style_name, ui_name)
 
     from cmd2 import theme
 
     assert style_name in theme._PT_UI_MAP
+    assert ui_name in theme._PT_UI_MAP[style_name]
 
+    # Unregister just the UI component
     unregister_pt_mapping(style_name, ui_name)
+
+    # The style key should still be in the map to trigger synchronization
+    assert style_name in theme._PT_UI_MAP
+    assert not theme._PT_UI_MAP[style_name]
+
+
+def test_register_synchronized_style() -> None:
+    """Test that simple registration (no UI mapping) synchronizes to PT."""
+    style_name = "simple_style"
+    register_synchronized_style(style_name)
+
+    set_theme({style_name: Style(color=Color.RED)})
+
+    # It should be available as a class:name
+    pt_theme = get_pt_theme()
+    attrs = pt_theme.get_attrs_for_style_str(f"class:{style_name}")
+    assert attrs.color == "ansired"
+
+
+def test_unregister_synchronized_style() -> None:
+    """Test that unregistering removes the style entirely."""
+    style_name = "removal_style"
+    ui_name = "removal_ui"
+    register_pt_mapping(style_name, ui_name)
+
+    from cmd2 import theme
+
+    assert style_name in theme._PT_UI_MAP
+    unregister_synchronized_style(style_name)
     assert style_name not in theme._PT_UI_MAP