Updated change log and docs.

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

docs/features/builtin_commands.md

@@ -77,19 +77,19 @@ application:
 
 ```text
 (Cmd) set
- Name                     Value      Description
-───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
- allow_style              Terminal   Allow ANSI text style sequences in output (valid values: Always, Never, Terminal)
- always_show_hint         False      Display tab completion hint even when completion suggestions print
- debug                    False      Show full traceback on exception
- echo                     False      Echo command issued into output
- editor                   vim        Program used by 'edit'
- feedback_to_output       False      Include nonessentials in '|' and '>' results
- foreground_color         cyan       Foreground color to use with echo command
- max_completion_items     50         Maximum number of CompletionItems to display during tab completion
- quiet                    False      Don't print nonessential feedback
- scripts_add_to_history   True       Scripts and pyscripts add commands to history
- timing                   False      Report execution times
+  Name                            Value      Description
+──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ allow_style                     Terminal   Allow ANSI text style sequences in output (valid values: Always, Never, Terminal)
+ always_show_hint                False      Display completion hint even when completion suggestions print
+ debug                           False      Show full traceback on exception
+ echo                            False      Echo command issued into output
+ editor                          vim        Program used by 'edit'
+ feedback_to_output              False      Include nonessentials in '|' and '>' results
+ max_column_completion_results   7          Maximum number of completion results to display in a single column
+ max_completion_table_items      50         Maximum number of completion results allowed for a completion table to appear
+ quiet                           False      Don't print nonessential feedback
+ scripts_add_to_history          True       Scripts and pyscripts add commands to history
+ timing                          False      Report execution times
 ```
 
 Any of these user-settable parameters can be set while running your app with the `set` command like

docs/features/initialization.md

@@ -31,7 +31,6 @@ Here are instance attributes of `cmd2.Cmd` which developers might wish to overri
 - **debug**: if `True`, show full stack trace on error (Default: `False`)
 - **default_category**: if any command has been categorized, then all other commands that haven't been categorized will display under this section in the help output.
 - **default_error**: the error that prints when a non-existent command is run
-- **default_sort_key**: the default key for sorting string results. Its default value performs a case-insensitive alphabetical sort.
 - **default_to_shell**: if `True`, attempt to run unrecognized commands as shell commands (Default: `False`)
 - **disabled_commands**: commands that have been disabled from use. This is to support commands that are only available during specific states of the application. This dictionary's keys are the command names and its values are DisabledCommand objects.
 - **doc_header**: Set the header used for the help function's listing of documented functions
@@ -45,7 +44,7 @@ Here are instance attributes of `cmd2.Cmd` which developers might wish to overri
 - **last_result**: stores results from the last command run to enable usage of results in a Python script or interactive console. Built-in commands don't make use of this. It is purely there for user-defined commands and convenience.
 - **macros**: dictionary of macro names and their values
 - **max_column_completion_results**: The maximum number of completion results to display in a single column (Default: 7)
-- **max_completion_items**: max number of CompletionItems to display during tab completion (Default: 50)
+- **max_completion_table_items**: The maximum number of completion results allowed for a completion table to appear (Default: 50)
 - **pager**: sets the pager command used by the `Cmd.ppaged()` method for displaying wrapped output using a pager
 - **pager_chop**: sets the pager command used by the `Cmd.ppaged()` method for displaying chopped/truncated output using a pager
 - **py_bridge_name**: name by which embedded Python environments and scripts refer to the `cmd2` application by in order to call commands (Default: `app`)

examples/argparse_completion.py

@@ -9,6 +9,7 @@
 from rich.text import Text
 
 from cmd2 import (
+    Choices,
     Cmd,
     Cmd2ArgumentParser,
     Cmd2Style,
@@ -27,23 +28,23 @@ def __init__(self) -> None:
         super().__init__(include_ipy=True)
         self.sport_item_strs = ['Bat', 'Basket', 'Basketball', 'Football', 'Space Ball']
 
-    def choices_provider(self) -> list[str]:
+    def choices_provider(self) -> Choices:
         """A choices provider is useful when the choice list is based on instance data of your application."""
-        return self.sport_item_strs
+        return Choices.from_values(self.sport_item_strs)
 
-    def choices_completion_error(self) -> list[str]:
+    def choices_completion_error(self) -> Choices:
         """CompletionErrors can be raised if an error occurs while tab completing.
 
         Example use cases
             - Reading a database to retrieve a tab completion data set failed
             - A previous command line argument that determines the data set being completed is invalid
         """
         if self.debug:
-            return self.sport_item_strs
+            return Choices.from_values(self.sport_item_strs)
         raise CompletionError("debug must be true")
 
-    def choices_completion_item(self) -> list[CompletionItem]:
-        """Return CompletionItem instead of strings. These give more context to what's being tab completed."""
+    def choices_completion_tables(self) -> Choices:
+        """Return CompletionItems with completion tables. These give more context to what's being tab completed."""
         fancy_item = Text.assemble(
             "These things can\ncontain newlines and\n",
             Text("styled text!!", style=Style(color=Color.BRIGHT_YELLOW, underline=True)),
@@ -58,16 +59,18 @@ def choices_completion_item(self) -> list[CompletionItem]:
         table_item.add_row("Yes, it's true.", "CompletionItems can")
         table_item.add_row("even display description", "data in tables!")
 
-        items = {
+        item_dict = {
             1: "My item",
             2: "Another item",
             3: "Yet another item",
             4: fancy_item,
             5: table_item,
         }
-        return [CompletionItem(item_id, [description]) for item_id, description in items.items()]
 
-    def choices_arg_tokens(self, arg_tokens: dict[str, list[str]]) -> list[str]:
+        completion_items = [CompletionItem(item_id, table_row=[description]) for item_id, description in item_dict.items()]
+        return Choices(items=completion_items)
+
+    def choices_arg_tokens(self, arg_tokens: dict[str, list[str]]) -> Choices:
         """If a choices or completer function/method takes a value called arg_tokens, then it will be
         passed a dictionary that maps the command line tokens up through the one being completed
         to their argparse argument name.  All values of the arg_tokens dictionary are lists, even if
@@ -79,7 +82,7 @@ def choices_arg_tokens(self, arg_tokens: dict[str, list[str]]) -> list[str]:
             values.append('is {}'.format(arg_tokens['choices_provider'][0]))
         else:
             values.append('not supplied')
-        return values
+        return Choices.from_values(values)
 
     # Parser for example command
     example_parser = Cmd2ArgumentParser(
@@ -105,10 +108,10 @@ def choices_arg_tokens(self, arg_tokens: dict[str, list[str]]) -> list[str]:
         help="raise a CompletionError while tab completing if debug is False",
     )
 
-    # Demonstrate returning CompletionItems instead of strings
+    # Demonstrate use of completion table
     example_parser.add_argument(
-        '--completion_item',
-        choices_provider=choices_completion_item,
+        '--completion_table',
+        choices_provider=choices_completion_tables,
         metavar="ITEM_ID",
         table_header=["Description"],
         help="demonstrate use of CompletionItems",

examples/basic_completion.py

@@ -14,6 +14,7 @@
 import functools
 
 import cmd2
+from cmd2 import Completions
 
 # List of strings used with completion functions
 food_item_strs = ['Pizza', 'Ham', 'Ham Sandwich', 'Potato']
@@ -41,7 +42,7 @@ def do_flag_based(self, statement: cmd2.Statement) -> None:
         """
         self.poutput(f"Args: {statement.args}")
 
-    def complete_flag_based(self, text, line, begidx, endidx) -> list[str]:
+    def complete_flag_based(self, text, line, begidx, endidx) -> Completions:
         """Completion function for do_flag_based."""
         flag_dict = {
             # Tab complete food items after -f and --food flags in command line
@@ -61,7 +62,7 @@ def do_index_based(self, statement: cmd2.Statement) -> None:
         """Tab completes first 3 arguments using index_based_complete."""
         self.poutput(f"Args: {statement.args}")
 
-    def complete_index_based(self, text, line, begidx, endidx) -> list[str]:
+    def complete_index_based(self, text, line, begidx, endidx) -> Completions:
         """Completion function for do_index_based."""
         index_dict = {
             1: food_item_strs,  # Tab complete food items at index 1 in command line
@@ -82,7 +83,7 @@ def do_raise_error(self, statement: cmd2.Statement) -> None:
         """Demonstrates effect of raising CompletionError."""
         self.poutput(f"Args: {statement.args}")
 
-    def complete_raise_error(self, _text, _line, _begidx, _endidx) -> list[str]:
+    def complete_raise_error(self, _text, _line, _begidx, _endidx) -> Completions:
         """CompletionErrors can be raised if an error occurs while tab completing.
 
         Example use cases

examples/transcripts/exampleSession.txt

@@ -8,7 +8,7 @@ debug: False
 echo: False
 editor: /.*?/
 feedback_to_output: False
-max_completion_items: 50
+max_completion_table_items: 50
 maxrepeats: 3
 quiet: False
 timing: False

examples/transcripts/transcript_regex.txt

@@ -2,19 +2,18 @@
 # Anything between two forward slashes, /, is interpreted as a regular expression (regex).
 # The regex for editor will match whatever program you use.
 # regexes on prompts just make the trailing space obvious
-(Cmd) set 
-
- Name                     Value      Description                                                                       
-───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
- allow_style              Terminal   Allow ANSI text style sequences in output (valid values: Always, Never, Terminal) 
- always_show_hint         False      Display tab completion hint even when completion suggestions print                
- debug                    False      Show full traceback on exception                                                  
- echo                     False      Echo command issued into output                                                   
- editor                   /.*?/      Program used by 'edit'                                                            
- feedback_to_output       False      Include nonessentials in '|' and '>' results                                      
- max_completion_items     50         Maximum number of CompletionItems to display during tab completion                
- maxrepeats               3          max repetitions for speak command                                                 
- quiet                    False      Don't print nonessential feedback                                                 
- scripts_add_to_history   True       Scripts and pyscripts add commands to history                                     
- timing                   False      Report execution times                                                            
+(Cmd) set
 
+ Name                            Value      Description
+──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ allow_style                     Terminal   Allow ANSI text style sequences in output (valid values: Always, Never, Terminal)
+ always_show_hint                False      Display completion hint even when completion suggestions print
+ debug                           True       Show full traceback on exception
+ echo                            False      Echo command issued into output
+ editor                          vim        Program used by 'edit'
+ feedback_to_output              False      Include nonessentials in '|' and '>' results
+ max_column_completion_results   7          Maximum number of completion results to display in a single column
+ max_completion_table_items      50         Maximum number of completion results allowed for a completion table to appear
+ quiet                           False      Don't print nonessential feedback
+ scripts_add_to_history          True       Scripts and pyscripts add commands to history
+ timing                          False      Report execution times

tests/test_completion.py

@@ -288,7 +288,7 @@ def test_complete_macro(base_app, request) -> None:
     assert completions.to_strings() == Completions.from_values(expected).to_strings()
 
 
-def test_default_sort_key(cmd2_app) -> None:
+def test_default_str_sort_key(cmd2_app) -> None:
     text = ''
     line = f'test_sort_key {text}'
     endidx = len(line)