Updated comments and renamed a function.

Author: kmvanbrunt

cmd2/cmd2.py

@@ -309,7 +309,7 @@ class AsyncAlert:
 
 
 class _ConsoleCache(threading.local):
-    """Thread-local storage for cached Rich consoles used by print_to()."""
+    """Thread-local storage for cached Rich consoles used by core print methods."""
 
     def __init__(self) -> None:
         self.stdout: Cmd2BaseConsole | None = None
@@ -449,7 +449,7 @@ def __init__(
         self.scripts_add_to_history = True  # Scripts and pyscripts add commands to history
         self.timing = False  # Prints elapsed time for each command
 
-        # Thread-local storage for cached Rich consoles used by print_to()
+        # Cached Rich consoles used by core print methods.
         self._console_cache = _ConsoleCache()
 
         # The maximum number of items to display in a completion table. If the number of completion
@@ -1335,20 +1335,21 @@ def visible_prompt(self) -> str:
         """
         return su.strip_style(self.prompt)
 
-    def _create_base_printing_console(
+    def _get_core_print_console(
         self,
         *,
         file: IO[str],
         emoji: bool,
         markup: bool,
         highlight: bool,
     ) -> Cmd2BaseConsole:
-        """Get a Cmd2BaseConsole configured for the specified stream and formatting settings.
+        """Get a console configured for the specified stream and formatting settings.
 
-        This method manages a thread-local cache for consoles printing to self.stdout or
-        sys.stderr to avoid the overhead of repeated initialization. It returns a cached
-        instance if its configuration matches the request. Otherwise, a new console is
-        created and cached.
+        This method is intended for internal use by cmd2's core print methods.
+        To avoid the overhead of repeated initialization, it manages a thread-local
+        cache for consoles targeting ``self.stdout`` or ``sys.stderr``. It returns a cached
+        instance if its configuration matches the request. For all other streams, or if
+        the configuration has changed, a new console is created.
 
         Note: This implementation works around a bug in Rich where passing formatting settings
         (emoji, markup, and highlight) directly to console.print() or console.log() does not
@@ -1437,7 +1438,7 @@ def print_to(
         See the Rich documentation for more details on emoji codes, markup tags, and highlighting.
         """
         try:
-            self._create_base_printing_console(
+            self._get_core_print_console(
                 file=file,
                 emoji=emoji,
                 markup=markup,
@@ -1753,7 +1754,7 @@ def ppaged(
                 soft_wrap = True
 
             # Generate the bytes to send to the pager
-            console = self._create_base_printing_console(
+            console = self._get_core_print_console(
                 file=self.stdout,
                 emoji=emoji,
                 markup=markup,

tests/test_cmd2.py

@@ -2536,14 +2536,12 @@ def test_poutput_all_keyword_args(outsim_app):
         (True, False, True),
     ],
 )
-def test_create_base_printing_console_caching(
-    base_app: cmd2.Cmd, stream: str, emoji: bool, markup: bool, highlight: bool
-) -> None:
-    """Test that base printing consoles are cached and reused when settings match."""
+def test_get_core_print_console_caching(base_app: cmd2.Cmd, stream: str, emoji: bool, markup: bool, highlight: bool) -> None:
+    """Test that printing consoles are cached and reused when settings match."""
     file = sys.stderr if stream == 'stderr' else base_app.stdout
 
     # Initial creation
-    console1 = base_app._create_base_printing_console(
+    console1 = base_app._get_core_print_console(
         file=file,
         emoji=emoji,
         markup=markup,
@@ -2555,7 +2553,7 @@ def test_create_base_printing_console_caching(
     assert cached is console1
 
     # Identical request should return the same object
-    console2 = base_app._create_base_printing_console(
+    console2 = base_app._get_core_print_console(
         file=file,
         emoji=emoji,
         markup=markup,
@@ -2568,20 +2566,20 @@ def test_create_base_printing_console_caching(
     'stream',
     ['stdout', 'stderr'],
 )
-def test_create_base_printing_console_invalidation(base_app: cmd2.Cmd, stream: str) -> None:
+def test_get_core_print_console_invalidation(base_app: cmd2.Cmd, stream: str) -> None:
     """Test that changing settings, theme, or ALLOW_STYLE invalidates the cache."""
     file = sys.stderr if stream == 'stderr' else base_app.stdout
 
     # Initial creation
-    console1 = base_app._create_base_printing_console(
+    console1 = base_app._get_core_print_console(
         file=file,
         emoji=True,
         markup=True,
         highlight=True,
     )
 
     # Changing emoji should create a new console
-    console2 = base_app._create_base_printing_console(
+    console2 = base_app._get_core_print_console(
         file=file,
         emoji=False,
         markup=True,
@@ -2591,7 +2589,7 @@ def test_create_base_printing_console_invalidation(base_app: cmd2.Cmd, stream: s
     assert getattr(base_app._console_cache, stream) is console2
 
     # Changing markup should create a new console
-    console3 = base_app._create_base_printing_console(
+    console3 = base_app._get_core_print_console(
         file=file,
         emoji=False,
         markup=False,
@@ -2601,7 +2599,7 @@ def test_create_base_printing_console_invalidation(base_app: cmd2.Cmd, stream: s
     assert getattr(base_app._console_cache, stream) is console3
 
     # Changing highlight should create a new console
-    console4 = base_app._create_base_printing_console(
+    console4 = base_app._get_core_print_console(
         file=file,
         emoji=False,
         markup=False,
@@ -2614,7 +2612,7 @@ def test_create_base_printing_console_invalidation(base_app: cmd2.Cmd, stream: s
     orig_allow_style = ru.ALLOW_STYLE
     try:
         ru.ALLOW_STYLE = ru.AllowStyle.ALWAYS if orig_allow_style != ru.AllowStyle.ALWAYS else ru.AllowStyle.NEVER
-        console5 = base_app._create_base_printing_console(
+        console5 = base_app._get_core_print_console(
             file=file,
             emoji=False,
             markup=False,
@@ -2631,7 +2629,7 @@ def test_create_base_printing_console_invalidation(base_app: cmd2.Cmd, stream: s
     old_theme = ru.APP_THEME
     try:
         ru.APP_THEME = Theme()
-        console6 = base_app._create_base_printing_console(
+        console6 = base_app._get_core_print_console(
             file=file,
             emoji=False,
             markup=False,
@@ -2643,11 +2641,11 @@ def test_create_base_printing_console_invalidation(base_app: cmd2.Cmd, stream: s
         ru.APP_THEME = old_theme
 
 
-def test_create_base_printing_console_non_cached(base_app: cmd2.Cmd) -> None:
+def test_get_core_print_console_non_cached(base_app: cmd2.Cmd) -> None:
     """Test that arbitrary file objects are not cached."""
     file = io.StringIO()
 
-    console1 = base_app._create_base_printing_console(
+    console1 = base_app._get_core_print_console(
         file=file,
         emoji=True,
         markup=True,
@@ -2659,7 +2657,7 @@ def test_create_base_printing_console_non_cached(base_app: cmd2.Cmd) -> None:
     assert base_app._console_cache.stderr is None
 
     # A second request for the same file should still create a new object
-    console2 = base_app._create_base_printing_console(
+    console2 = base_app._get_core_print_console(
         file=file,
         emoji=True,
         markup=True,