Merge branch 'master' into topic_width

Author: kmvanbrunt

CHANGELOG.md

@@ -1,14 +1,19 @@
 ## 2.2.0 (TBD, 2021)
 * Enhancements
-    * Using `SimpleTable` in the output for the following commands to improve appearance.
-        * help
-        * set (command and tab completion of Settables)
-        * alias tab completion
-        * macro tab completion
-    * Tab completion of `CompletionItems` now includes divider row comprised of `Cmd.ruler` character.
-    * Removed `--verbose` flag from set command since descriptions always show now.
+  * New function `set_default_command_completer_type()` allows developer to extend and modify the
+    behavior of `ArgparseCompleter`. 
+  * New function `register_argparse_argument_parameter()` allows developers to specify custom 
+    parameters to be passed to the argparse parser's `add_argument()` method. These parameters will
+    become accessible in the resulting argparse Action object when modifying `ArgparseCompleter` behavior.
+  * Using `SimpleTable` in the output for the following commands to improve appearance.
+    * help
+    * set (command and tab completion of Settables)
+    * alias tab completion
+    * macro tab completion
+  * Tab completion of `CompletionItems` now includes divider row comprised of `Cmd.ruler` character.
+  * Removed `--verbose` flag from set command since descriptions always show now.
 * Deletions (potentially breaking changes)
-    * Deleted ``set_choices_provider()`` and ``set_completer()`` which were deprecated in 2.1.2
+  * Deleted ``set_choices_provider()`` and ``set_completer()`` which were deprecated in 2.1.2
 
 ## 2.1.2 (July 5, 2021)
 * Enhancements

cmd2/__init__.py

@@ -5,7 +5,7 @@
 
 import sys
 
-# For python 3.8 and late
+# For python 3.8 and later
 if sys.version_info >= (3, 8):
     import importlib.metadata as importlib_metadata
 else:
@@ -20,9 +20,16 @@
 from typing import List
 
 from .ansi import style, fg, bg
-from .argparse_custom import Cmd2ArgumentParser, Cmd2AttributeWrapper, CompletionItem, set_default_argument_parser
+from .argparse_custom import (
+    Cmd2ArgumentParser,
+    Cmd2AttributeWrapper,
+    CompletionItem,
+    register_argparse_argument_parameter,
+    set_default_argument_parser,
+)
 
-# Check if user has defined a module that sets a custom value for argparse_custom.DEFAULT_ARGUMENT_PARSER
+# Check if user has defined a module that sets a custom value for argparse_custom.DEFAULT_ARGUMENT_PARSER.
+# Do this before loading cmd2.Cmd class so its commands use the custom parser.
 import argparse
 
 cmd2_parser_module = getattr(argparse, 'cmd2_parser_module', None)
@@ -31,8 +38,8 @@
 
     importlib.import_module(cmd2_parser_module)
 
-# Get the current value for argparse_custom.DEFAULT_ARGUMENT_PARSER
-from .argparse_custom import DEFAULT_ARGUMENT_PARSER
+from .argparse_completer import set_default_command_completer_type
+
 from .cmd2 import Cmd
 from .command_definition import CommandSet, with_default_category
 from .constants import COMMAND_NAME, DEFAULT_SHORTCUTS
@@ -46,7 +53,6 @@
 
 __all__: List[str] = [
     'COMMAND_NAME',
-    'DEFAULT_ARGUMENT_PARSER',
     'DEFAULT_SHORTCUTS',
     # ANSI Style exports
     'bg',
@@ -56,7 +62,9 @@
     'Cmd2ArgumentParser',
     'Cmd2AttributeWrapper',
     'CompletionItem',
+    'register_argparse_argument_parameter',
     'set_default_argument_parser',
+    'set_default_command_completer_type',
     # Cmd2
     'Cmd',
     'CommandResult',

cmd2/argparse_completer.py

@@ -13,18 +13,28 @@
     deque,
 )
 from typing import (
+    TYPE_CHECKING,
     Dict,
     List,
     Optional,
+    Type,
     Union,
     cast,
 )
 
-from . import (
-    ansi,
-    cmd2,
-    constants,
+from .ansi import (
+    style_aware_wcswidth,
+    widest_line,
 )
+from .constants import (
+    INFINITY,
+)
+
+if TYPE_CHECKING:
+    from .cmd2 import (
+        Cmd,
+    )
+
 from .argparse_custom import (
     ChoicesCallable,
     ChoicesProviderFuncWithTokens,
@@ -124,10 +134,10 @@ def __init__(self, arg_action: argparse.Action) -> None:
             self.max = 1
         elif self.action.nargs == argparse.ZERO_OR_MORE or self.action.nargs == argparse.REMAINDER:
             self.min = 0
-            self.max = constants.INFINITY
+            self.max = INFINITY
         elif self.action.nargs == argparse.ONE_OR_MORE:
             self.min = 1
-            self.max = constants.INFINITY
+            self.max = INFINITY
         else:
             self.min = self.action.nargs
             self.max = self.action.nargs
@@ -165,7 +175,7 @@ class ArgparseCompleter:
     """Automatic command line tab completion based on argparse parameters"""
 
     def __init__(
-        self, parser: argparse.ArgumentParser, cmd2_app: cmd2.Cmd, *, parent_tokens: Optional[Dict[str, List[str]]] = None
+        self, parser: argparse.ArgumentParser, cmd2_app: 'Cmd', *, parent_tokens: Optional[Dict[str, List[str]]] = None
     ) -> None:
         """
         Create an ArgparseCompleter
@@ -564,15 +574,15 @@ def _format_completions(self, arg_state: _ArgumentState, completions: Union[List
             desc_header = desc_header.replace('\t', four_spaces)
 
             # Calculate needed widths for the token and description columns of the table
-            token_width = ansi.style_aware_wcswidth(destination)
-            desc_width = ansi.widest_line(desc_header)
+            token_width = style_aware_wcswidth(destination)
+            desc_width = widest_line(desc_header)
 
             for item in completion_items:
-                token_width = max(ansi.style_aware_wcswidth(item), token_width)
+                token_width = max(style_aware_wcswidth(item), token_width)
 
                 # Replace tabs with 4 spaces so we can calculate width
                 item.description = item.description.replace('\t', four_spaces)
-                desc_width = max(ansi.widest_line(item.description), desc_width)
+                desc_width = max(widest_line(item.description), desc_width)
 
             cols = list()
             cols.append(Column(destination.upper(), width=token_width))
@@ -728,3 +738,16 @@ def _complete_arg(
             return []
 
         return self._format_completions(arg_state, results)
+
+
+DEFAULT_COMMAND_COMPLETER: Type[ArgparseCompleter] = ArgparseCompleter
+
+
+def set_default_command_completer_type(completer_type: Type[ArgparseCompleter]) -> None:
+    """
+    Set the default command completer type. It must be a sub-class of the ArgparseCompleter.
+
+    :param completer_type: Type that is a subclass of ArgparseCompleter.
+    """
+    global DEFAULT_COMMAND_COMPLETER
+    DEFAULT_COMMAND_COMPLETER = completer_type

cmd2/argparse_custom.py

@@ -240,6 +240,7 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens)
     NoReturn,
     Optional,
     Sequence,
+    Set,
     Tuple,
     Type,
     Union,
@@ -640,10 +641,75 @@ def _action_set_suppress_tab_hint(self: argparse.Action, suppress_tab_hint: bool
 setattr(argparse.Action, 'set_suppress_tab_hint', _action_set_suppress_tab_hint)
 
 
+############################################################################################################
+# Allow developers to add custom action attributes
+############################################################################################################
+
+CUSTOM_ACTION_ATTRIBS: Set[str] = set()
+_CUSTOM_ATTRIB_PFX = '_attr_'
+
+
+def register_argparse_argument_parameter(param_name: str, param_type: Optional[Type[Any]]) -> None:
+    """
+    Registers a custom argparse argument parameter.
+
+    The registered name will then be a recognized keyword parameter to the parser's `add_argument()` function.
+
+    An accessor functions will be added to the parameter's Action object in the form of: ``get_{param_name}()``
+    and ``set_{param_name}(value)``.
+
+    :param param_name: Name of the parameter to add.
+    """
+    attr_name = f'{_CUSTOM_ATTRIB_PFX}{param_name}'
+    if param_name in CUSTOM_ACTION_ATTRIBS or hasattr(argparse.Action, attr_name):
+        raise KeyError(f'Custom parameter {param_name} already exists')
+    if not re.search('^[A-Za-z_][A-Za-z0-9_]*$', param_name):
+        raise KeyError(f'Invalid parameter name {param_name} - cannot be used as a python identifier')
+
+    getter_name = f'get_{param_name}'
+
+    def _action_get_custom_parameter(self: argparse.Action) -> Any:
+        f"""
+        Get the custom {param_name} attribute of an argparse Action.
+
+        This function is added by cmd2 as a method called ``{getter_name}()`` to ``argparse.Action`` class.
+
+        To call: ``action.{getter_name}()``
+
+        :param self: argparse Action being queried
+        :return: The value of {param_name} or None if attribute does not exist
+        """
+        return getattr(self, attr_name, None)
+
+    setattr(argparse.Action, getter_name, _action_get_custom_parameter)
+
+    setter_name = f'set_{param_name}'
+
+    def _action_set_custom_parameter(self: argparse.Action, value: Any) -> None:
+        f"""
+        Set the custom {param_name} attribute of an argparse Action.
+
+        This function is added by cmd2 as a method called ``{setter_name}()`` to ``argparse.Action`` class.
+
+        To call: ``action.{setter_name}({param_name})``
+
+        :param self: argparse Action being updated
+        :param value: value being assigned
+        """
+        if param_type and not isinstance(value, param_type):
+            raise TypeError(f'{param_name} must be of type {param_type}, got: {value} ({type(value)})')
+        setattr(self, attr_name, value)
+
+    setattr(argparse.Action, setter_name, _action_set_custom_parameter)
+
+    CUSTOM_ACTION_ATTRIBS.add(param_name)
+
+
 ############################################################################################################
 # Patch _ActionsContainer.add_argument with our wrapper to support more arguments
 ############################################################################################################
 
+
 # Save original _ActionsContainer.add_argument so we can call it in our wrapper
 # noinspection PyProtectedMember
 orig_actions_container_add_argument = argparse._ActionsContainer.add_argument
@@ -753,6 +819,14 @@ def _add_argument_wrapper(
         # Add the argparse-recognized version of nargs to kwargs
         kwargs['nargs'] = nargs_adjusted
 
+    # Extract registered custom keyword arguments
+    custom_attribs: Dict[str, Any] = {}
+    for keyword, value in kwargs.items():
+        if keyword in CUSTOM_ACTION_ATTRIBS:
+            custom_attribs[keyword] = value
+    for keyword in custom_attribs:
+        del kwargs[keyword]
+
     # Create the argument using the original add_argument function
     new_arg = orig_actions_container_add_argument(self, *args, **kwargs)
 
@@ -767,6 +841,11 @@ def _add_argument_wrapper(
     new_arg.set_suppress_tab_hint(suppress_tab_hint)  # type: ignore[attr-defined]
     new_arg.set_descriptive_header(descriptive_header)  # type: ignore[attr-defined]
 
+    for keyword, value in custom_attribs.items():
+        attr_setter = getattr(new_arg, f'set_{keyword}', None)
+        if attr_setter is not None:
+            attr_setter(value)
+
     return new_arg
 
 
@@ -1243,6 +1322,9 @@ def set(self, new_val: Any) -> None:
 
 
 def set_default_argument_parser(parser: Type[argparse.ArgumentParser]) -> None:
-    """Set the default ArgumentParser class for a cmd2 app"""
+    """
+    Set the default ArgumentParser class for a cmd2 app. This must be called prior to loading cmd2.py if
+    you want to override the parser for cmd2's built-in commands. See examples/override_parser.py.
+    """
     global DEFAULT_ARGUMENT_PARSER
     DEFAULT_ARGUMENT_PARSER = parser