Renamed parser's table_header to table_columns.

Renamed CompletionItem's table_row to table_data.

Author: kmvanbrunt

CHANGELOG.md

@@ -37,10 +37,10 @@ prompt is displayed.
           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`.
-    - Removed `DEFAULT_DESCRIPTIVE_HEADERS`. This means you must define `table_header` when using
-      `CompletionItem.table_row` data.
+    - An argparse argument's `descriptive_headers` field is now called `table_columns`.
+    - `CompletionItem.descriptive_data` is now called `CompletionItem.table_data`.
+    - Removed `DEFAULT_DESCRIPTIVE_HEADERS`. This means you must define `table_columns` when using
+      `CompletionItem.table_data` data.
     - `Cmd.default_sort_key` moved to `utils.DEFAULT_STR_SORT_KEY`.
     - Moved completion state data, which previously resided in `Cmd`, into other classes.
         - `Cmd.matches_sorted` -> `Completions.is_sorted` and `Choices.is_sorted`

cmd2/argparse_completer.py

@@ -594,42 +594,46 @@ def _validate_table_data(arg_state: _ArgumentState, completions: Completions) ->
 
         :raises ValueError: if there is an error with the data.
         """
-        table_header = arg_state.action.get_table_header()  # type: ignore[attr-defined]
-        has_table_data = any(item.table_row for item in completions)
+        table_columns = arg_state.action.get_table_columns()  # type: ignore[attr-defined]
+        has_table_data = any(item.table_data for item in completions)
 
-        if table_header is None:
+        if table_columns is None:
             if has_table_data:
                 raise ValueError(
-                    f"Argument '{arg_state.action.dest}' has CompletionItems with table_row, "
-                    f"but no table_header was defined in add_argument()."
+                    f"Argument '{arg_state.action.dest}' has CompletionItems with table_data, "
+                    f"but no table_columns were defined in add_argument()."
                 )
             return
 
-        # If header is defined, then every item must have data, and lengths must match
+        # If columns are defined, then every item must have data, and lengths must match
         for item in completions:
-            if not item.table_row:
+            if not item.table_data:
                 raise ValueError(
-                    f"Argument '{arg_state.action.dest}' has table_header defined, "
-                    f"but the CompletionItem for '{item.text}' is missing table_row."
+                    f"Argument '{arg_state.action.dest}' has table_columns defined, "
+                    f"but the CompletionItem for '{item.text}' is missing table_data."
                 )
-            if len(item.table_row) != len(table_header):
+            if len(item.table_data) != len(table_columns):
                 raise ValueError(
-                    f"Argument '{arg_state.action.dest}': table_row length ({len(item.table_row)}) "
-                    f"does not match table_header length ({len(table_header)}) for item '{item.text}'."
+                    f"Argument '{arg_state.action.dest}': table_data length ({len(item.table_data)}) "
+                    f"does not match table_columns length ({len(table_columns)}) for item '{item.text}'."
                 )
 
     def _build_completion_table(self, arg_state: _ArgumentState, completions: Completions) -> Completions:
         """Build a rich.Table for completion results if applicable."""
         # Verify integrity of completion data
         self._validate_table_data(arg_state, completions)
 
-        table_header = cast(
+        table_columns = cast(
             Sequence[str | Column] | None,
-            arg_state.action.get_table_header(),  # type: ignore[attr-defined]
+            arg_state.action.get_table_columns(),  # type: ignore[attr-defined]
         )
 
         # Skip table generation if results are outside thresholds or no columns are defined
-        if len(completions) < 2 or len(completions) > self._cmd2_app.max_completion_table_items or table_header is None:
+        if (
+            len(completions) < 2
+            or len(completions) > self._cmd2_app.max_completion_table_items
+            or table_columns is None
+        ):  # fmt: skip
             return completions
 
         # If a metavar was defined, use that instead of the dest field
@@ -650,13 +654,13 @@ def _build_completion_table(self, arg_state: _ArgumentState, completions: Comple
         rich_columns: list[Column] = []
         rich_columns.append(Column(destination.upper(), justify="right" if all_nums else "left", no_wrap=True))
         rich_columns.extend(
-            column if isinstance(column, Column) else Column(column, overflow="fold") for column in table_header
+            column if isinstance(column, Column) else Column(column, overflow="fold") for column in table_columns
         )
 
         # Build the table
         table = Table(*rich_columns, box=SIMPLE_HEAD, show_edge=False, border_style=Cmd2Style.TABLE_BORDER)
         for item in completions:
-            table.add_row(Text.from_ansi(item.display), *item.table_row)
+            table.add_row(Text.from_ansi(item.display), *item.table_data)
 
         return dataclasses.replace(
             completions,

cmd2/argparse_custom.py

@@ -127,7 +127,7 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens) -> Completions
 
 1. display - string for displaying the completion differently in the completion menu
 2. display_meta - meta information about completion which displays in the completion menu
-3. table_row - row data for completion tables
+3. table_data - supplemental data for completion tables
 
 They can also be used as argparse choices. When a ``CompletionItem`` is created, it
 stores the original value (e.g. ID number) and makes it accessible through a property
@@ -139,8 +139,8 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens) -> Completions
 These were added to help in cases where uninformative data is being completed.
 For instance, completing ID numbers isn't very helpful to a user without context.
 
-Providing ``table_row`` data in your ``CompletionItem`` signals ArgparseCompleter
-to output the completion results in a table with descriptive data instead of just a table
+Providing ``table_data`` in your ``CompletionItem`` signals ArgparseCompleter
+to output the completion results in a table with supplemental data instead of just a table
 of tokens::
 
     Instead of this:
@@ -155,35 +155,34 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens) -> Completions
 
 
 The left-most column is the actual value being completed and its header is
-that value's name. The right column header is defined using the
-``table_header`` parameter of add_argument(), which is a list of header
-names that defaults to ["Description"]. The right column values come from the
-``table_row`` argument to ``CompletionItem``. It's a ``Sequence`` with the
-same number of items as ``table_header``.
+that value's name. Any additional column headers are defined using the
+``table_columns`` parameter of add_argument(), which is a list of header
+names. The supplemental column values come from the
+``table_data`` argument to ``CompletionItem``. It's a ``Sequence`` with the
+same number of items as ``table_columns``.
 
 Example::
 
-    Add an argument and define its table_header.
+    Add an argument and define its table_columns.
 
         parser.add_argument(
-            add_argument(
             "item_id",
             type=int,
             choices_provider=get_choices,
-            table_header=["Item Name", "Checked Out", "Due Date"],
+            table_columns=["Item Name", "Checked Out", "Due Date"],
         )
 
     Implement the choices_provider to return Choices.
 
         def get_choices(self) -> Choices:
             \"\"\"choices_provider which returns CompletionItems\"\"\"
 
-            # Populate CompletionItem's table_row argument.
-            # Its item count should match that of table_header.
+            # Populate CompletionItem's table_data argument.
+            # Its item count should match that of table_columns.
             items = [
-                CompletionItem(1, table_row=["My item", True, "02/02/2022"]),
-                CompletionItem(2, table_row=["Another item", False, ""]),
-                CompletionItem(3, table_row=["Yet another item", False, ""]),
+                CompletionItem(1, table_data=["My item", True, "02/02/2022"]),
+                CompletionItem(2, table_data=["Another item", False, ""]),
+                CompletionItem(3, table_data=["Yet another item", False, ""]),
             ]
             return Choices(items)
 
@@ -195,7 +194,7 @@ def get_choices(self) -> Choices:
               2   Another item       False
               3   Yet another item   False
 
-``table_header`` can be strings or ``Rich.table.Columns`` for more
+``table_columns`` can be strings or ``Rich.table.Columns`` for more
 control over things like alignment.
 
 - If a header is a string, it will render as a left-aligned column with its
@@ -207,9 +206,9 @@ def get_choices(self) -> Choices:
 truncated with an ellipsis at the end. You can override this and other settings
 when you create the ``Column``.
 
-``table_row`` items can include Rich objects, including styled Text and Tables.
+``table_data`` items can include Rich objects, including styled Text and Tables.
 
-To avoid printing a excessive information to the screen at once when a user
+To avoid printing excessive information to the screen at once when a user
 presses tab, there is a maximum threshold for the number of ``CompletionItems``
 that will be shown. Its value is defined in ``cmd2.Cmd.max_completion_table_items``.
 It defaults to 50, but can be changed. If the number of completion suggestions
@@ -240,8 +239,8 @@ def get_choices(self) -> Choices:
 - ``argparse.Action.get_choices_callable()`` - See `action_get_choices_callable` for more details.
 - ``argparse.Action.set_choices_provider()`` - See `_action_set_choices_provider` for more details.
 - ``argparse.Action.set_completer()`` - See `_action_set_completer` for more details.
-- ``argparse.Action.get_table_header()`` - See `_action_get_table_header` for more details.
-- ``argparse.Action.set_table_header()`` - See `_action_set_table_header` for more details.
+- ``argparse.Action.get_table_columns()`` - See `_action_get_table_columns` for more details.
+- ``argparse.Action.set_table_columns()`` - See `_action_set_table_columns` for more details.
 - ``argparse.Action.get_nargs_range()`` - See `_action_get_nargs_range` for more details.
 - ``argparse.Action.set_nargs_range()`` - See `_action_set_nargs_range` for more details.
 - ``argparse.Action.get_suppress_tab_hint()`` - See `_action_get_suppress_tab_hint` for more details.
@@ -418,8 +417,8 @@ def completer(self) -> CompleterUnbound[CmdOrSet]:
 # ChoicesCallable object that specifies the function to be called which provides choices to the argument
 ATTR_CHOICES_CALLABLE = 'choices_callable'
 
-# A completion table header
-ATTR_TABLE_HEADER = 'table_header'
+# Completion table columns
+ATTR_TABLE_COLUMNS = 'table_columns'
 
 # A tuple specifying nargs as a range (min, max)
 ATTR_NARGS_RANGE = 'nargs_range'
@@ -516,38 +515,38 @@ def _action_set_completer(
 
 
 ############################################################################################################
-# Patch argparse.Action with accessors for table_header attribute
+# Patch argparse.Action with accessors for table_columns attribute
 ############################################################################################################
-def _action_get_table_header(self: argparse.Action) -> Sequence[str | Column] | None:
-    """Get the table_header attribute of an argparse Action.
+def _action_get_table_columns(self: argparse.Action) -> Sequence[str | Column] | None:
+    """Get the table_columns attribute of an argparse Action.
 
-    This function is added by cmd2 as a method called ``get_table_header()`` to ``argparse.Action`` class.
+    This function is added by cmd2 as a method called ``get_table_columns()`` to ``argparse.Action`` class.
 
-    To call: ``action.get_table_header()``
+    To call: ``action.get_table_columns()``
 
     :param self: argparse Action being queried
-    :return: The value of table_header or None if attribute does not exist
+    :return: The value of table_columns or None if attribute does not exist
     """
-    return cast(Sequence[str | Column] | None, getattr(self, ATTR_TABLE_HEADER, None))
+    return cast(Sequence[str | Column] | None, getattr(self, ATTR_TABLE_COLUMNS, None))
 
 
-setattr(argparse.Action, 'get_table_header', _action_get_table_header)
+setattr(argparse.Action, 'get_table_columns', _action_get_table_columns)
 
 
-def _action_set_table_header(self: argparse.Action, table_header: Sequence[str | Column] | None) -> None:
-    """Set the table_header attribute of an argparse Action.
+def _action_set_table_columns(self: argparse.Action, table_columns: Sequence[str | Column] | None) -> None:
+    """Set the table_columns attribute of an argparse Action.
 
-    This function is added by cmd2 as a method called ``set_table_header()`` to ``argparse.Action`` class.
+    This function is added by cmd2 as a method called ``set_table_columns()`` to ``argparse.Action`` class.
 
-    To call: ``action.set_table_header(table_header)``
+    To call: ``action.set_table_columns(table_columns)``
 
     :param self: argparse Action being updated
-    :param table_header: value being assigned
+    :param table_columns: value being assigned
     """
-    setattr(self, ATTR_TABLE_HEADER, table_header)
+    setattr(self, ATTR_TABLE_COLUMNS, table_columns)
 
 
-setattr(argparse.Action, 'set_table_header', _action_set_table_header)
+setattr(argparse.Action, 'set_table_columns', _action_set_table_columns)
 
 
 ############################################################################################################
@@ -698,7 +697,7 @@ def _add_argument_wrapper(
     choices_provider: ChoicesProviderUnbound[CmdOrSet] | None = None,
     completer: CompleterUnbound[CmdOrSet] | None = None,
     suppress_tab_hint: bool = False,
-    table_header: Sequence[str | Column] | None = None,
+    table_columns: Sequence[str | Column] | None = None,
     **kwargs: Any,
 ) -> argparse.Action:
     """Wrap ActionsContainer.add_argument() which supports more settings used by cmd2.
@@ -718,7 +717,7 @@ def _add_argument_wrapper(
                               current argument's help text as a hint. Set this to True to suppress the hint. If this
                               argument's help text is set to argparse.SUPPRESS, then tab hints will not display
                               regardless of the value passed for suppress_tab_hint. Defaults to False.
-    :param table_header: optional header for when displaying a completion table. Defaults to None.
+    :param table_columns: optional headers for when displaying a completion table. Defaults to None.
 
     # Args from original function
     :param kwargs: keyword-arguments recognized by argparse._ActionsContainer.add_argument
@@ -809,7 +808,7 @@ def _add_argument_wrapper(
         new_arg.set_completer(completer)  # type: ignore[attr-defined]
 
     new_arg.set_suppress_tab_hint(suppress_tab_hint)  # type: ignore[attr-defined]
-    new_arg.set_table_header(table_header)  # type: ignore[attr-defined]
+    new_arg.set_table_columns(table_columns)  # type: ignore[attr-defined]
 
     for keyword, value in custom_attribs.items():
         attr_setter = getattr(new_arg, f'set_{keyword}', None)

cmd2/cmd2.py

@@ -2526,7 +2526,7 @@ def _get_alias_choices(self) -> Choices:
         items: list[CompletionItem] = []
 
         for name, value in self.aliases.items():
-            items.append(CompletionItem(name, display_meta=value, table_row=[value]))
+            items.append(CompletionItem(name, display_meta=value, table_data=[value]))
 
         return Choices(items=items)
 
@@ -2535,7 +2535,7 @@ def _get_macro_choices(self) -> Choices:
         items: list[CompletionItem] = []
 
         for name, macro in self.macros.items():
-            items.append(CompletionItem(name, display_meta=macro.value, table_row=[macro.value]))
+            items.append(CompletionItem(name, display_meta=macro.value, table_data=[macro.value]))
 
         return Choices(items=items)
 
@@ -2545,12 +2545,12 @@ def _get_settable_choices(self) -> Choices:
 
         for name, settable in self.settables.items():
             value_str = str(settable.value)
-            table_row = [
+            table_data = [
                 value_str,
                 settable.description,
             ]
             display_meta = f"[Current: {su.stylize(value_str, Style(bold=True))}] {settable.description}"
-            items.append(CompletionItem(name, display_meta=display_meta, table_row=table_row))
+            items.append(CompletionItem(name, display_meta=display_meta, table_data=table_data))
 
         return Choices(items=items)
 
@@ -3658,7 +3658,7 @@ def _build_alias_delete_parser(cls) -> Cmd2ArgumentParser:
             nargs=argparse.ZERO_OR_MORE,
             help='alias(es) to delete',
             choices_provider=cls._get_alias_choices,
-            table_header=["Value"],
+            table_columns=["Value"],
         )
 
         return alias_delete_parser
@@ -3700,7 +3700,7 @@ def _build_alias_list_parser(cls) -> Cmd2ArgumentParser:
             nargs=argparse.ZERO_OR_MORE,
             help='alias(es) to list',
             choices_provider=cls._get_alias_choices,
-            table_header=["Value"],
+            table_columns=["Value"],
         )
 
         return alias_list_parser
@@ -3949,7 +3949,7 @@ def _build_macro_delete_parser(cls) -> Cmd2ArgumentParser:
             nargs=argparse.ZERO_OR_MORE,
             help='macro(s) to delete',
             choices_provider=cls._get_macro_choices,
-            table_header=["Value"],
+            table_columns=["Value"],
         )
 
         return macro_delete_parser
@@ -3991,7 +3991,7 @@ def _build_macro_list_parser(cls) -> Cmd2ArgumentParser:
             nargs=argparse.ZERO_OR_MORE,
             help='macro(s) to list',
             choices_provider=cls._get_macro_choices,
-            table_header=["Value"],
+            table_columns=["Value"],
         )
 
         return macro_list_parser
@@ -4475,7 +4475,7 @@ def _build_base_set_parser(cls) -> Cmd2ArgumentParser:
             nargs=argparse.OPTIONAL,
             help='parameter to set or view',
             choices_provider=cls._get_settable_choices,
-            table_header=["Value", "Description"],
+            table_columns=["Value", "Description"],
         )
 
         return base_set_parser