Refactor input

.github/CODEOWNERS

@@ -31,7 +31,8 @@ cmd2/argparse_*.py         @kmvanbrunt @anselor
 cmd2/clipboard.py          @tleonhardt
 cmd2/cmd2.py               @tleonhardt @kmvanbrunt
 cmd2/colors.py             @tleonhardt @kmvanbrunt
-cmd2/command_definition.py @anselor
+cmd2/command_definition.py @anselor @kmvanbrunt
+cmd2/completion.py         @kmvanbrunt
 cmd2/constants.py          @tleonhardt @kmvanbrunt
 cmd2/decorators.py         @kmvanbrunt @anselor
 cmd2/exceptions.py         @kmvanbrunt @anselor
@@ -43,7 +44,6 @@ cmd2/py_bridge.py          @kmvanbrunt
 cmd2/rich_utils.py         @kmvanbrunt
 cmd2/string_utils.py       @kmvanbrunt
 cmd2/styles.py             @tleonhardt @kmvanbrunt
-cmd2/terminal_utils.py     @kmvanbrunt
 cmd2/utils.py              @tleonhardt @kmvanbrunt
 
 # Documentation

CHANGELOG.md

@@ -56,6 +56,7 @@ prompt is displayed.
       `Statement.redirect_to`.
     - Changed `StatementParser.parse_command_only()` to return a `PartialStatement` object.
     - Renamed `Macro.arg_list` to `Macro.args`.
+    - Removed `terminal_utils.py` since `prompt-toolkit` provides this functionality.
 - Enhancements
     - New `cmd2.Cmd` parameters
         - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These

cmd2/__init__.py

@@ -52,7 +52,6 @@
 from .string_utils import stylize
 from .styles import Cmd2Style
 from .utils import (
-    CompletionMode,
     CustomCompletionSettings,
     Settable,
     categorize,
@@ -103,7 +102,6 @@
     "Cmd2Style",
     # Utilities
     'categorize',
-    'CompletionMode',
     'CustomCompletionSettings',
     'Settable',
     'set_default_str_sort_key',

cmd2/completion.py

@@ -1,4 +1,4 @@
-"""Provides classes and functions related to completion."""
+"""Provides classes and functions related to command-line completion."""
 
 import re
 import sys

cmd2/constants.py

@@ -4,6 +4,7 @@
 # nothing here should be considered part of the public API of this module
 
 INFINITY = float('inf')
+EOF = 'eof'
 
 # Used for command parsing, output redirection, completion, and word breaks. Do not change.
 QUOTES = ['"', "'"]

cmd2/pt_utils.py

@@ -11,6 +11,7 @@
 )
 
 from prompt_toolkit import print_formatted_text
+from prompt_toolkit.application import get_app
 from prompt_toolkit.completion import (
     Completer,
     Completion,
@@ -95,7 +96,7 @@ def get_completions(self, document: Document, _complete_event: object) -> Iterab
         # and returning early, we trigger a new completion cycle where the quote
         # is already present, allowing for proper common prefix calculation.
         if completions._add_opening_quote and search_text_length > 0:
-            buffer = self.cmd_app.session.app.current_buffer
+            buffer = get_app().current_buffer
 
             buffer.cursor_left(search_text_length)
             buffer.insert_text(completions._quote_char)

cmd2/utils.py

@@ -17,7 +17,6 @@
     MutableSequence,
 )
 from difflib import SequenceMatcher
-from enum import Enum
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -733,24 +732,6 @@ def get_defining_class(meth: Callable[..., Any]) -> type[Any] | None:
     return cast(type, getattr(meth, '__objclass__', None))  # handle special descriptor objects
 
 
-class CompletionMode(Enum):
-    """Enum for what type of completion to perform in cmd2.Cmd.read_input()."""
-
-    # Completion will be disabled during read_input() call
-    # Use of custom up-arrow history supported
-    NONE = 1
-
-    # read_input() will complete cmd2 commands and their arguments
-    # cmd2's command line history will be used for up arrow if history is not provided.
-    # Otherwise use of custom up-arrow history supported.
-    COMMANDS = 2
-
-    # read_input() will complete based on one of its following parameters:
-    #     choices, choices_provider, completer, parser
-    # Use of custom up-arrow history supported
-    CUSTOM = 3
-
-
 class CustomCompletionSettings:
     """Used by cmd2.Cmd.complete() to complete strings other than command arguments."""
 

docs/api/completion.md

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

docs/api/index.md

@@ -18,6 +18,7 @@ incremented according to the [Semantic Version Specification](https://semver.org
 - [cmd2.colors](./colors.md) - StrEnum of all color names supported by the Rich library
 - [cmd2.command_definition](./command_definition.md) - supports the definition of commands in
   separate classes to be composed into cmd2.Cmd
+- [cmd2.completion](./completion.md) - classes and functions related to command-line completion
 - [cmd2.constants](./constants.md) - constants used in `cmd2`
 - [cmd2.decorators](./decorators.md) - decorators for `cmd2` commands
 - [cmd2.exceptions](./exceptions.md) - custom `cmd2` exceptions
@@ -30,5 +31,4 @@ incremented according to the [Semantic Version Specification](https://semver.org
 - [cmd2.rich_utils](./rich_utils.md) - common utilities to support Rich in cmd2 applications
 - [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
 - [cmd2.utils](./utils.md) - various utility classes and functions

docs/features/generating_output.md

@@ -121,7 +121,6 @@ following sections:
 - [cmd2.colors][]
 - [cmd2.rich_utils][]
 - [cmd2.string_utils][]
-- [cmd2.terminal_utils][]
 
 The [color.py](https://github.com/python-cmd2/cmd2/blob/main/examples/color.py) example demonstrates
 all colors available to your `cmd2` application.

examples/read_input.py

@@ -32,13 +32,6 @@ def do_basic_with_history(self, _) -> None:
         else:
             self.custom_history.append(input_str)
 
-    @cmd2.with_category(EXAMPLE_COMMANDS)
-    def do_commands(self, _) -> None:
-        """Call read_input the same way cmd2 prompt does to read commands."""
-        self.poutput("Tab completing and up-arrow history configured for commands")
-        with contextlib.suppress(EOFError):
-            self.read_input("> ", completion_mode=cmd2.CompletionMode.COMMANDS)
-
     @cmd2.with_category(EXAMPLE_COMMANDS)
     def do_custom_choices(self, _) -> None:
         """Call read_input to use custom history and choices."""
@@ -47,17 +40,16 @@ def do_custom_choices(self, _) -> None:
             input_str = self.read_input(
                 "> ",
                 history=self.custom_history,
-                completion_mode=cmd2.CompletionMode.CUSTOM,
                 choices=['choice_1', 'choice_2', 'choice_3'],
             )
         except EOFError:
             pass
         else:
             self.custom_history.append(input_str)
 
-    def choices_provider(self) -> list[str]:
+    def choices_provider(self) -> cmd2.Choices:
         """Example choices provider function."""
-        return ["from_provider_1", "from_provider_2", "from_provider_3"]
+        return cmd2.Choices.from_values(["from_provider_1", "from_provider_2", "from_provider_3"])
 
     @cmd2.with_category(EXAMPLE_COMMANDS)
     def do_custom_choices_provider(self, _) -> None:
@@ -67,7 +59,6 @@ def do_custom_choices_provider(self, _) -> None:
             input_str = self.read_input(
                 "> ",
                 history=self.custom_history,
-                completion_mode=cmd2.CompletionMode.CUSTOM,
                 choices_provider=ReadInputApp.choices_provider,
             )
         except EOFError:
@@ -80,9 +71,7 @@ def do_custom_completer(self, _) -> None:
         """Call read_input to use custom history and completer function."""
         self.poutput("Tab completing paths and using custom history")
         try:
-            input_str = self.read_input(
-                "> ", history=self.custom_history, completion_mode=cmd2.CompletionMode.CUSTOM, completer=cmd2.Cmd.path_complete
-            )
+            input_str = self.read_input("> ", history=self.custom_history, completer=cmd2.Cmd.path_complete)
             self.custom_history.append(input_str)
         except EOFError:
             pass
@@ -99,9 +88,7 @@ def do_custom_parser(self, _) -> None:
         self.poutput(parser.format_usage())
 
         try:
-            input_str = self.read_input(
-                "> ", history=self.custom_history, completion_mode=cmd2.CompletionMode.CUSTOM, parser=parser
-            )
+            input_str = self.read_input("> ", history=self.custom_history, parser=parser)
         except EOFError:
             pass
         else:

mkdocs.yml

@@ -199,6 +199,7 @@ nav:
       - api/clipboard.md
       - api/colors.md
       - api/command_definition.md
+      - api/completion.md
       - api/constants.md
       - api/decorators.md
       - api/exceptions.md
@@ -210,7 +211,6 @@ nav:
       - api/rich_utils.md
       - api/string_utils.md
       - api/styles.md
-      - api/terminal_utils.md
       - api/utils.md
   - Version Upgrades:
       - upgrades.md