Refactor and standardize argparse-related naming and metadata (#1670)

- Consistently use full words COMMAND and SUBCOMMAND over abbreviations
- Renamed cmd2_subcmd_handler to cmd2_subcommand_func
- Consolidate command metadata into ArgparseCommandSpec dataclass
- Simplify subcommand examples by using required=True for subparsers
- Renamed set_default_argument_parser_type() to set_default_argument_parser()
- Renamed set_default_ap_completer_type() to set_default_argparse_completer()
- Renamed Cmd2ArgumentParser.ap_completer_type to completer_class

Author: kmvanbrunt

CHANGELOG.md

@@ -67,12 +67,14 @@ prompt is displayed.
     - Removed `Cmd.ruler` since `cmd2` no longer uses it.
     - All parsers used with `cmd2` commands must be an instance of `Cmd2ArgumentParser` or a child
       class of it.
-    - Removed `set_ap_completer_type()` and `get_ap_completer_type()` since `ap_completer_type` is
-      now a public member of `Cmd2ArgumentParser`.
+    - Renamed `set_default_argument_parser_type()` to `set_default_argument_parser()`.
+    - Renamed `set_default_ap_completer_type()` to `set_default_argparse_completer()`.
+    - Removed `set_ap_completer_type()` and `get_ap_completer_type()` since `completer_class` is now
+      a public member of `Cmd2ArgumentParser`.
     - Moved `set_parser_prog()` to `Cmd2ArgumentParser.update_prog()`.
-    - Renamed `cmd2_handler` to `cmd2_subcmd_handler` in the `argparse.Namespace` for clarity.
+    - Renamed `cmd2_handler` to `cmd2_subcommand_func` in the `argparse.Namespace` for clarity.
     - Removed `Cmd2AttributeWrapper` class. `argparse.Namespace` objects passed to command functions
-      now contain direct attributes for `cmd2_statement` and `cmd2_subcmd_handler`.
+      now contain direct attributes for `cmd2_statement` and `cmd2_subcommand_func`.
     - Renamed `cmd2/command_definition.py` to `cmd2/command_set.py`.
     - Removed `Cmd.doc_header` and the `with_default_category` decorator. Help categorization is now
       driven by the `DEFAULT_CATEGORY` class variable (see **Simplified command categorization** in

cmd2/__init__.py

@@ -12,12 +12,12 @@
     string_utils,
 )
 from .annotated import with_annotated
-from .argparse_completer import set_default_ap_completer_type
+from .argparse_completer import set_default_argparse_completer
 from .argparse_utils import (
     Cmd2ArgumentParser,
     SubcommandRecord,
     register_argparse_argument_parameter,
-    set_default_argument_parser_type,
+    set_default_argument_parser,
 )
 from .cmd2 import Cmd
 from .colors import Color
@@ -75,8 +75,8 @@
     "Cmd2ArgumentParser",
     "SubcommandRecord",
     "register_argparse_argument_parameter",
-    "set_default_ap_completer_type",
-    "set_default_argument_parser_type",
+    "set_default_argparse_completer",
+    "set_default_argument_parser",
     # Cmd2
     "Cmd",
     "CommandResult",

cmd2/annotated.py

@@ -18,7 +18,7 @@
 flag (``dry_run`` -> ``--dry-run``); pass an explicit ``Option("--my_flag")`` to opt out.
 Positional-only parameters (before ``/``) and ``**kwargs`` raise ``TypeError``.  The parameter
 names ``dest`` and ``subcommand`` are reserved; ``cmd2_statement`` receives the parsed
-``Statement`` and (with ``base_command=True``) ``cmd2_handler`` receives the subcommand handler:
+``Statement`` and (with ``base_command=True``) ``cmd2_subcommand_func`` receives the subcommand handler:
 
     class MyApp(cmd2.Cmd):
         @cmd2.with_annotated
@@ -118,7 +118,7 @@ def do_paint(
 692 ``**parser_kwargs: Unpack[Cmd2ParserKwargs]``.  Anything the parser ctor accepts -- ``description``,
 ``epilog``, ``prog``, ``usage``, ``parents``, ``argument_default``, ``prefix_chars``,
 ``fromfile_prefix_chars``, ``conflict_handler``, ``add_help``, ``allow_abbrev``, ``exit_on_error``,
-``formatter_class``, ``ap_completer_type``, and on Python >= 3.14 ``suggest_on_error`` / ``color`` --
+``formatter_class``, ``completer_class``, and on Python >= 3.14 ``suggest_on_error`` / ``color`` --
 flows straight through; the [`Cmd2ParserKwargs`][cmd2.annotated.Cmd2ParserKwargs] ``TypedDict`` is the single source of truth
 and gives type-checkers/IDEs autocomplete on the decorator's call site.  ``parser_class`` stays as
 its own explicit kwarg because it selects the class itself, not a value passed to it.  Two
@@ -181,8 +181,16 @@ def do_paint(
 import functools
 import inspect
 import types
-from collections.abc import Callable, Container, Iterable, Sequence
-from dataclasses import dataclass, field
+from collections.abc import (
+    Callable,
+    Container,
+    Iterable,
+    Sequence,
+)
+from dataclasses import (
+    dataclass,
+    field,
+)
 from pathlib import Path
 from typing import (
     TYPE_CHECKING,
@@ -203,12 +211,20 @@ def do_paint(
 from rich.table import Column
 
 from . import constants
-from .argparse_utils import DEFAULT_ARGUMENT_PARSER, Cmd2ArgumentParser, SubcommandSpec
+from .argparse_utils import (
+    ArgparseCommandSpec,
+    Cmd2ArgumentParser,
+    SubcommandSpec,
+)
 from .completion import CompletionItem
 from .decorators import _parse_positionals
 from .exceptions import Cmd2ArgparseError
 from .rich_utils import Cmd2HelpFormatter, HelpContent
-from .types import CmdOrSetT, UnboundChoicesProvider, UnboundCompleter
+from .types import (
+    CmdOrSetT,
+    UnboundChoicesProvider,
+    UnboundCompleter,
+)
 
 if TYPE_CHECKING:
     from .argparse_completer import ArgparseCompleter
@@ -240,7 +256,7 @@ class Cmd2ParserKwargs(TypedDict, total=False):
     exit_on_error: bool
     suggest_on_error: bool
     color: bool
-    ap_completer_type: "type[ArgparseCompleter] | None"
+    completer_class: "type[ArgparseCompleter] | None"
 
 
 # ---------------------------------------------------------------------------
@@ -1687,7 +1703,7 @@ def _const_mismatches_type(a: _ArgparseArgument) -> bool:
 
 # Parameters handled specially by the decorator and not added to the parser.  The first positional
 # parameter (self/cls) is always skipped by position; these cover additional decorator-managed names.
-_SKIP_PARAMS = frozenset({"cmd2_handler", "cmd2_statement"})
+_SKIP_PARAMS = frozenset({constants.NS_ATTR_SUBCOMMAND_FUNC, constants.NS_ATTR_STATEMENT})
 
 
 def _link_group_membership(
@@ -1718,14 +1734,17 @@ def _resolve_parameters(
     """Resolve a function signature into a list of argparse-argument builders.
 
     ``base_command`` marks each argument's context for the base-command :data:`_CONSTRAINTS` rows and
-    drives the function-level ``cmd2_handler`` check below.  ``groups``/``mutually_exclusive_groups``
+    drives the function-level ``cmd2_subcommand_func`` check below.  ``groups``/``mutually_exclusive_groups``
     are linked onto each argument as membership facts for the cross-config constraint rows.
     """
     sig = inspect.signature(func)
     # Function-level check (not a per-argument _CONSTRAINTS row): a base command dispatches through
-    # cmd2_handler, so it must exist.  Here so it also fires when the function has zero parameters.
-    if base_command and "cmd2_handler" not in sig.parameters:
-        raise TypeError(f"with_annotated(base_command=True) requires a 'cmd2_handler' parameter in {func.__qualname__}")
+    # cmd2_subcommand_func, so it must exist.  Here so it also fires when the function has zero parameters.
+    if base_command and constants.NS_ATTR_SUBCOMMAND_FUNC not in sig.parameters:
+        raise TypeError(
+            f"with_annotated(base_command=True) requires a '{constants.NS_ATTR_SUBCOMMAND_FUNC}' "
+            f"parameter in {func.__qualname__}"
+        )
     try:
         hints = get_type_hints(func, include_extras=True)
     except (NameError, AttributeError, TypeError) as exc:
@@ -1828,14 +1847,10 @@ def _filtered_namespace_kwargs(
     exclude_subcommand: bool = False,
 ) -> dict[str, Any]:
     """Filter a parsed Namespace down to user-visible kwargs."""
-    from .constants import NS_ATTR_SUBCMD_HANDLER
-
     filtered: dict[str, Any] = {}
     for key, value in vars(ns).items():
         if accepted is not None and key not in accepted:
             continue
-        if key == NS_ATTR_SUBCMD_HANDLER:
-            continue
         if exclude_subcommand and key == "subcommand":
             continue
         filtered[key] = value
@@ -1952,7 +1967,9 @@ def build_parser_from_function(
     :param parser_kwargs: forwarded [`Cmd2ParserKwargs`][cmd2.annotated.Cmd2ParserKwargs]
     :return: a fully configured ``Cmd2ArgumentParser``
     """
-    parser_cls = parser_class or DEFAULT_ARGUMENT_PARSER
+    from . import argparse_utils
+
+    parser_cls = parser_class or argparse_utils.DEFAULT_ARGUMENT_PARSER
     if "description" not in parser_kwargs:
         auto_description = _docstring_first_paragraph(func.__doc__)
         if auto_description is not None:
@@ -2105,10 +2122,10 @@ def _build_subcommand_handler(
     def handler(self_arg: Any, ns: Any) -> Any:
         """Unpack Namespace into typed kwargs for the subcommand handler."""
         filtered = _filtered_namespace_kwargs(ns, accepted=_accepted)
-        if "cmd2_handler" in filtered:
-            cmd2_h = filtered["cmd2_handler"]
+        if constants.NS_ATTR_SUBCOMMAND_FUNC in filtered:
+            cmd2_h = filtered[constants.NS_ATTR_SUBCOMMAND_FUNC]
             if isinstance(cmd2_h, functools.partial) and cmd2_h.func is handler:
-                filtered["cmd2_handler"] = None
+                filtered[constants.NS_ATTR_SUBCOMMAND_FUNC] = None
         return _invoke_command_func(
             func, self_arg, filtered, leading_names=_leading_names, var_positional_name=_var_positional_name
         )
@@ -2170,7 +2187,7 @@ def with_annotated(
     :param ns_provider: callable returning a prepopulated Namespace (not with ``subcommand_to``)
     :param preserve_quotes: preserve quotes in arguments (not with ``subcommand_to``)
     :param with_unknown_args: capture unknown args as the ``_unknown`` kwarg (not with ``subcommand_to``)
-    :param base_command: add ``add_subparsers()``; requires a ``cmd2_handler`` param and no positionals
+    :param base_command: add ``add_subparsers()``; requires a ``cmd2_subcommand_func`` param and no positionals
     :param subcommand_to: parent command name; function must be named ``{parent_underscored}_{subcommand}``
     :param help: subcommand help text (only with ``subcommand_to``)
     :param aliases: alternative subcommand names (only with ``subcommand_to``)
@@ -2232,9 +2249,10 @@ def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
             if unknown_param.kind is inspect.Parameter.POSITIONAL_ONLY:
                 raise TypeError("Parameter _unknown must be keyword-compatible when with_unknown_args=True")
 
-        if not base_command and "cmd2_handler" in inspect.signature(fn).parameters:
+        if not base_command and constants.NS_ATTR_SUBCOMMAND_FUNC in inspect.signature(fn).parameters:
             raise TypeError(
-                f"Parameter 'cmd2_handler' in {fn.__qualname__} is only valid when with_annotated(base_command=True) is used."
+                f"Parameter '{constants.NS_ATTR_SUBCOMMAND_FUNC}' in {fn.__qualname__} "
+                "is only valid when with_annotated(base_command=True) is used."
             )
 
         if subcommand_to is not None:
@@ -2244,15 +2262,15 @@ def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
                 base_command=base_command,
                 options=options,
             )
-            spec = SubcommandSpec(
+            subcommand_spec = SubcommandSpec(
                 name=subcmd_name,
                 command=subcommand_to,
                 help=help,
                 aliases=tuple(aliases),
                 deprecated=deprecated,
                 parser_source=subcmd_parser_builder,
             )
-            setattr(handler, constants.SUBCMD_ATTR_SPEC, spec)
+            setattr(handler, constants.SUBCOMMAND_ATTR_SPEC, subcommand_spec)
             return handler
 
         command_name = fn.__name__[len(constants.COMMAND_FUNC_PREFIX) :]
@@ -2296,10 +2314,10 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
                 raise Cmd2ArgparseError from exc
 
             setattr(ns, constants.NS_ATTR_STATEMENT, statement)
-            handler = getattr(ns, constants.NS_ATTR_SUBCMD_HANDLER, None)
+            handler = getattr(ns, constants.NS_ATTR_SUBCOMMAND_FUNC, None)
             if base_command and handler is not None:
                 handler = functools.partial(handler, ns)
-            ns.cmd2_handler = handler
+            setattr(ns, constants.NS_ATTR_SUBCOMMAND_FUNC, handler)
 
             func_kwargs = _filtered_namespace_kwargs(ns, accepted=accepted, exclude_subcommand=base_command)
 
@@ -2312,8 +2330,11 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
             )
             return result
 
-        setattr(cmd_wrapper, constants.CMD_ATTR_PARSER_SOURCE, parser_builder)
-        setattr(cmd_wrapper, constants.CMD_ATTR_PRESERVE_QUOTES, preserve_quotes)
+        argparse_command_spec = ArgparseCommandSpec(
+            parser_source=parser_builder,
+            preserve_quotes=preserve_quotes,
+        )
+        setattr(cmd_wrapper, constants.ARGPARSE_COMMAND_ATTR_SPEC, argparse_command_spec)
 
         return cmd_wrapper
 

cmd2/argparse_completer.py

@@ -366,8 +366,7 @@ def consume_argument(arg_state: _ArgumentState, arg_token: str) -> None:
                                 parent_tokens[action.dest] = [token]
 
                             parser = self._subcommand_action.choices[token]
-                            completer_type = self._cmd_app._determine_ap_completer_type(parser)
-                            completer = completer_type(parser, self._cmd_app, parent_tokens=parent_tokens)
+                            completer = parser.completer_class(parser, self._cmd_app, parent_tokens=parent_tokens)
                             return completer.complete(text, line, begidx, endidx, tokens[token_index + 1 :], cmd_set=cmd_set)
 
                         # Invalid subcommand entered, so no way to complete remaining tokens
@@ -668,8 +667,7 @@ def complete_subcommand_help(self, text: str, line: str, begidx: int, endidx: in
             for token_index, token in enumerate(tokens):
                 if token in self._subcommand_action.choices:
                     parser = self._subcommand_action.choices[token]
-                    completer_type = self._cmd_app._determine_ap_completer_type(parser)
-                    completer = completer_type(parser, self._cmd_app)
+                    completer = parser.completer_class(parser, self._cmd_app)
                     return completer.complete_subcommand_help(text, line, begidx, endidx, tokens[token_index + 1 :])
 
                 if token_index == len(tokens) - 1:
@@ -690,8 +688,7 @@ def print_help(self, tokens: Sequence[str], file: IO[str] | None = None) -> None
         if tokens and self._subcommand_action is not None:
             parser = self._subcommand_action.choices.get(tokens[0])
             if parser is not None:
-                completer_type = self._cmd_app._determine_ap_completer_type(parser)
-                completer = completer_type(parser, self._cmd_app)
+                completer = parser.completer_class(parser, self._cmd_app)
                 completer.print_help(tokens[1:], file)
                 return
         self._parser.print_help(file)
@@ -800,13 +797,13 @@ def _complete_arg(
 
 
 # The default ArgparseCompleter class for a cmd2 app
-DEFAULT_AP_COMPLETER: type[ArgparseCompleter] = ArgparseCompleter
+DEFAULT_ARGPARSE_COMPLETER: type[ArgparseCompleter] = ArgparseCompleter
 
 
-def set_default_ap_completer_type(completer_type: type[ArgparseCompleter]) -> None:
+def set_default_argparse_completer(completer_class: type[ArgparseCompleter]) -> None:
     """Set the default ArgparseCompleter class for a cmd2 app.
 
-    :param completer_type: Type that is a subclass of ArgparseCompleter.
+    :param completer_class: Type that is a subclass of ArgparseCompleter.
     """
-    global DEFAULT_AP_COMPLETER  # noqa: PLW0603
-    DEFAULT_AP_COMPLETER = completer_type
+    global DEFAULT_ARGPARSE_COMPLETER  # noqa: PLW0603
+    DEFAULT_ARGPARSE_COMPLETER = completer_class