Remove remaining use of readline in cmd2.py and replace it with prompt_toolkit

Author: tleonhardt

.github/CODEOWNERS

@@ -38,9 +38,9 @@ cmd2/exceptions.py         @kmvanbrunt @anselor
 cmd2/history.py            @tleonhardt
 cmd2/parsing.py            @kmvanbrunt
 cmd2/plugin.py             @anselor
+cmd2/pt_utils.py           @kmvanbrunt @tleonhardt
 cmd2/py_bridge.py          @kmvanbrunt
 cmd2/rich_utils.py         @kmvanbrunt
-cmd2/rl_utils.py           @kmvanbrunt
 cmd2/string_utils.py       @kmvanbrunt
 cmd2/styles.py             @tleonhardt @kmvanbrunt
 cmd2/terminal_utils.py     @kmvanbrunt

cmd2/cmd2.py

@@ -63,6 +63,7 @@
     cast,
 )
 
+import prompt_toolkit as pt
 import rich.box
 from rich.console import Group, RenderableType
 from rich.highlighter import ReprHighlighter
@@ -137,7 +138,6 @@
 )
 from .styles import Cmd2Style
 
-# NOTE: When using gnureadline with Python 3.13, start_ipython needs to be imported before any readline-related stuff
 with contextlib.suppress(ImportError):
     from IPython import start_ipython
 
@@ -254,6 +254,8 @@ class Cmd:
     Line-oriented command interpreters are often useful for test harnesses, internal tools, and rapid prototypes.
     """
 
+    DEFAULT_COMPLETEKEY = 'tab'
+
     DEFAULT_EDITOR = utils.find_editor()
 
     # Sorting keys for strings
@@ -267,7 +269,7 @@ class Cmd:
 
     def __init__(
         self,
-        completekey: str = 'tab',
+        completekey: str = DEFAULT_COMPLETEKEY,
         stdin: TextIO | None = None,
         stdout: TextIO | None = None,
         *,
@@ -291,7 +293,7 @@ def __init__(
     ) -> None:
         """Easy but powerful framework for writing line-oriented command interpreters, extends Python's cmd package.
 
-        :param completekey: readline name of a completion key, default to Tab
+        :param completekey: name of a completion key, default to Tab
         :param stdin: alternate input file object, if not specified, sys.stdin is used
         :param stdout: alternate output file object, if not specified, sys.stdout is used
         :param persistent_history_file: file path to load a persistent cmd2 command history from
@@ -369,6 +371,9 @@ def __init__(
 
         # Key used for tab completion
         self.completekey = completekey
+        if self.completekey != self.DEFAULT_COMPLETEKEY:
+            # TODO(T or K): Configure prompt_toolkit `KeyBindings` with the custom key for completion  # noqa: FIX002, TD003
+            pass
 
         # Attributes which should NOT be dynamically settable via the set command at runtime
         self.default_to_shell = False  # Attempt to run unrecognized commands as shell commands
@@ -588,14 +593,14 @@ def __init__(
         # An optional hint which prints above tab completion suggestions
         self.completion_hint: str = ''
 
-        # Normally cmd2 uses readline's formatter to columnize the list of completion suggestions.
+        # Normally cmd2 uses prompt-toolkit's formatter to columnize the list of completion suggestions.
         # If a custom format is preferred, write the formatted completions to this string. cmd2 will
-        # then print it instead of the readline format. ANSI style sequences and newlines are supported
+        # then print it instead of the prompt-toolkit format. ANSI style sequences and newlines are supported
         # when using this value. Even when using formatted_completions, the full matches must still be returned
         # from your completer function. ArgparseCompleter writes its tab completion tables to this string.
         self.formatted_completions: str = ''
 
-        # Used by complete() for readline tab completion
+        # Used by complete() for prompt-toolkit tab completion
         self.completion_matches: list[str] = []
 
         # Use this list if you need to display tab completion suggestions that are different than the actual text
@@ -1574,7 +1579,7 @@ def ppaged(
     def _reset_completion_defaults(self) -> None:
         """Reset tab completion settings.
 
-        Needs to be called each time readline runs tab completion.
+        Needs to be called each time prompt-toolkit runs tab completion.
         """
         self.allow_appended_space = True
         self.allow_closing_quote = True
@@ -1970,12 +1975,12 @@ def complete_users() -> list[str]:
                     matches[index] += os.path.sep
                     self.display_matches[index] += os.path.sep
 
-            # Remove cwd if it was added to match the text readline expects
+            # Remove cwd if it was added to match the text prompt-toolkit expects
             if cwd_added:
                 to_replace = cwd if cwd == os.path.sep else cwd + os.path.sep
                 matches = [cur_path.replace(to_replace, '', 1) for cur_path in matches]
 
-            # Restore the tilde string if we expanded one to match the text readline expects
+            # Restore the tilde string if we expanded one to match the text prompt-toolkit expects
             if expanded_tilde_path:
                 matches = [cur_path.replace(expanded_tilde_path, orig_tilde_path, 1) for cur_path in matches]
 
@@ -2213,11 +2218,11 @@ def _perform_completion(
             # Save the quote so we can add a matching closing quote later.
             completion_token_quote = raw_completion_token[0]
 
-            # readline still performs word breaks after a quote. Therefore, something like quoted search
+            # prompt-toolkit still performs word breaks after a quote. Therefore, something like quoted search
             # text with a space would have resulted in begidx pointing to the middle of the token we
             # we want to complete. Figure out where that token actually begins and save the beginning
-            # portion of it that was not part of the text readline gave us. We will remove it from the
-            # completions later since readline expects them to start with the original text.
+            # portion of it that was not part of the text prompt-toolkit gave us. We will remove it from the
+            # completions later since prompt-toolkit expects them to start with the original text.
             actual_begidx = line[:endidx].rfind(tokens[-1])
 
             if actual_begidx != begidx:
@@ -2240,7 +2245,7 @@ def _perform_completion(
             if not self.display_matches:
                 # Since self.display_matches is empty, set it to self.completion_matches
                 # before we alter them. That way the suggestions will reflect how we parsed
-                # the token being completed and not how readline did.
+                # the token being completed and not how prompt-toolkit did.
                 import copy
 
                 self.display_matches = copy.copy(self.completion_matches)
@@ -2290,12 +2295,12 @@ def complete(
     ) -> str | None:
         """Override of cmd's complete method which returns the next possible completion for 'text'.
 
-        This completer function is called by readline as complete(text, state), for state in 0, 1, 2, …,
+        This completer function is called by prompt-toolkit as complete(text, state), for state in 0, 1, 2, …,
         until it returns a non-string value. It should return the next possible completion starting with text.
 
-        Since readline suppresses any exception raised in completer functions, they can be difficult to debug.
+        Since prompt-toolkit suppresses any exception raised in completer functions, they can be difficult to debug.
         Therefore, this function wraps the actual tab completion logic and prints to stderr any exception that
-        occurs before returning control to readline.
+        occurs before returning control to prompt-toolkit.
 
         :param text: the current word that user is typing
         :param state: non-negative integer
@@ -2575,7 +2580,7 @@ def postloop(self) -> None:
     def parseline(self, line: str) -> tuple[str, str, str]:
         """Parse the line into a command name and a string containing the arguments.
 
-        :param line: line read by readline
+        :param line: line read by prompt-toolkit
         :return: tuple containing (command, args, line)
         """
         statement = self.statement_parser.parse_command_only(line)
@@ -3225,15 +3230,13 @@ def get_prompt() -> Any:
         # Otherwise read from self.stdin
         elif self.stdin.isatty():
             # on a tty, print the prompt first, then read the line
-            self.poutput(prompt, end='')
-            self.stdout.flush()
-            line = self.stdin.readline()
+            line = pt.prompt(prompt)
             if len(line) == 0:
                 raise EOFError
             return line.rstrip('\n')
         else:
             # not a tty, just read the line
-            line = self.stdin.readline()
+            line = pt.prompt()
             if len(line) == 0:
                 raise EOFError
             return line.rstrip('\n')
@@ -4736,7 +4739,7 @@ def do_history(self, args: argparse.Namespace) -> bool | None:
         if args.clear:
             self.last_result = True
 
-            # Clear command and readline history
+            # Clear command and prompt-toolkit history
             self.history.clear()
 
             if self.persistent_history_file:
@@ -5333,8 +5336,8 @@ def async_refresh_prompt(self) -> None:  # pragma: no cover
 
         One case where the onscreen prompt and self.prompt can get out of sync is
         when async_alert() is called while a user is in search mode (e.g. Ctrl-r).
-        To prevent overwriting readline's onscreen search prompt, self.prompt is updated
-        but readline's saved prompt isn't.
+        To prevent overwriting prompt-toolkit's onscreen search prompt, self.prompt is updated
+        but prompt-toolkit's saved prompt isn't.
 
         Therefore when a user aborts a search, the old prompt is still on screen until they
         press Enter or this method is called. Call need_prompt_refresh() in an async print
@@ -5494,7 +5497,7 @@ def cmdloop(self, intro: RenderableType = '') -> int:
             original_sigterm_handler = signal.getsignal(signal.SIGTERM)
             signal.signal(signal.SIGTERM, self.termination_signal_handler)
 
-        # Grab terminal lock before the command line prompt has been drawn by readline
+        # Grab terminal lock before the command line prompt has been drawn by prompt-toolkit
         self.terminal_lock.acquire()
 
         # Always run the preloop first

docs/api/index.md

@@ -24,11 +24,10 @@ incremented according to the [Semantic Version Specification](https://semver.org
 - [cmd2.history](./history.md) - classes for storing the history of previously entered commands
 - [cmd2.parsing](./parsing.md) - classes for parsing and storing user input
 - [cmd2.plugin](./plugin.md) - data classes for hook methods
+- [cmd2.pt_utils](./pt_utils.md) - utilities related to prompt-toolkit
 - [cmd2.py_bridge](./py_bridge.md) - classes for bridging calls from the embedded python environment
   to the host app
 - [cmd2.rich_utils](./rich_utils.md) - common utilities to support Rich in cmd2 applications
-- [cmd2.rl_utils](./rl_utils.md) - imports the proper Readline for the platform and provides utility
-  functions for it
 - [cmd2.string_utils](./string_utils.md) - string utility functions
 - [cmd2.styles](./styles.md) - cmd2-specific Rich styles and a StrEnum of their corresponding names
 - [cmd2.terminal_utils](./terminal_utils.md) - support for terminal control escape sequences

docs/api/pt_utils.md

@@ -0,0 +1,3 @@
+# cmd2.pt_utils
+
+::: cmd2.pt_utils

docs/api/rl_utils.md

@@ -204,9 +204,9 @@ nav:
       - api/history.md
       - api/parsing.md
       - api/plugin.md
+      - api/pt_utils.md
       - api/py_bridge.md
       - api/rich_utils.md
-      - api/rl_utils.md
       - api/string_utils.md
       - api/styles.md
       - api/terminal_utils.md

mkdocs.yml

@@ -11,13 +11,11 @@
     TypeVar,
     cast,
 )
-from unittest import mock
 
 import pytest
 
 import cmd2
 from cmd2 import rich_utils as ru
-from cmd2.rl_utils import readline
 from cmd2.utils import StdSim
 
 # For type hinting decorators
@@ -122,8 +120,8 @@ def cmd_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
 
 def complete_tester(text: str, line: str, begidx: int, endidx: int, app: cmd2.Cmd) -> str | None:
     """This is a convenience function to test cmd2.complete() since
-    in a unit test environment there is no actual console readline
-    is monitoring. Therefore we use mock to provide readline data
+    in a unit test environment there is no actual console prompt-toolkit
+    is monitoring. Therefore we use mock to provide prompt-toolkit data
     to complete().
 
     :param text: the string prefix we are attempting to match
@@ -145,13 +143,8 @@ def get_begidx() -> int:
     def get_endidx() -> int:
         return endidx
 
-    # Run the readline tab completion function with readline mocks in place
-    with (
-        mock.patch.object(readline, 'get_line_buffer', get_line),
-        mock.patch.object(readline, 'get_begidx', get_begidx),
-        mock.patch.object(readline, 'get_endidx', get_endidx),
-    ):
-        return app.complete(text, 0, line, begidx, endidx)
+    # Run the prompt-toolkit tab completion function with mocks in place
+    return app.complete(text, 0, line, begidx, endidx)
 
 
 def find_subcommand(action: argparse.ArgumentParser, subcmd_names: list[str]) -> argparse.ArgumentParser: