Refactor completion API (#1575)

Overhauled the completion API to use encapsulation and better reflect how prompt-toolkit works.

Author: kmvanbrunt

CHANGELOG.md

@@ -27,6 +27,17 @@ shell, and the option for a persistent bottom bar that can display realtime stat
           `cmd2.Cmd.async_alert`
         - Removed `cmd2.Cmd.async_refresh_prompt` and `cmd2.Cmd.need_prompt_refresh` as they are no
           longer needed
+    - `completer` functions must now return a `cmd2.Completions` object instead of `list[str]`.
+    - `choices_provider` functions must now return a `cmd2.Choices` object instead of `list[str]`.
+    - An argparse argument's `descriptive_headers` field is now called `table_header`.
+    - `CompletionItem.descriptive_data` is now called `CompletionItem.table_row`.
+    - `Cmd.default_sort_key` moved to `utils.DEFAULT_STR_SORT_KEY`.
+    - Moved completion state data, which previously resided in `Cmd`, into other classes.
+        1. `Cmd.matches_sorted` -> `Completions.is_sorted` and `Choices.is_sorted`
+        1. `Cmd.completion_hint` -> `Completions.completion_hint`
+        1. `Cmd.formatted_completions` -> `Completions.completion_table`
+        1. `Cmd.matches_delimited` -> `Completions.is_delimited`
+        1. `Cmd.allow_appended_space/allow_closing_quote` -> `Completions.allow_finalization`
 - Enhancements
     - New `cmd2.Cmd` parameters
         - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These

cmd2/__init__.py

@@ -15,7 +15,6 @@
 from .argparse_custom import (
     Cmd2ArgumentParser,
     Cmd2AttributeWrapper,
-    CompletionItem,
     register_argparse_argument_parameter,
     set_default_argument_parser_type,
 )
@@ -25,6 +24,11 @@
     CommandSet,
     with_default_category,
 )
+from .completion import (
+    Choices,
+    CompletionItem,
+    Completions,
+)
 from .constants import (
     COMMAND_NAME,
     DEFAULT_SHORTCUTS,
@@ -52,6 +56,7 @@
     CustomCompletionSettings,
     Settable,
     categorize,
+    set_default_str_sort_key,
 )
 
 __all__: list[str] = [  # noqa: RUF022
@@ -60,7 +65,6 @@
     # Argparse Exports
     'Cmd2ArgumentParser',
     'Cmd2AttributeWrapper',
-    'CompletionItem',
     'register_argparse_argument_parameter',
     'set_default_ap_completer_type',
     'set_default_argument_parser_type',
@@ -71,6 +75,10 @@
     'Statement',
     # Colors
     "Color",
+    # Completion
+    'Choices',
+    'CompletionItem',
+    'Completions',
     # Decorators
     'with_argument_list',
     'with_argparser',
@@ -98,4 +106,5 @@
     'CompletionMode',
     'CustomCompletionSettings',
     'Settable',
+    'set_default_str_sort_key',
 ]