Made type hints of with_category() and as_subcommand_to() more permissive

to better support order-independent stacking with other decorators.

Author: kmvanbrunt

cmd2/decorators.py

@@ -9,8 +9,8 @@
 from typing import (
     TYPE_CHECKING,
     Any,
-    ParamSpec,
     TypeAlias,
+    TypeVar,
     overload,
 )
 
@@ -28,14 +28,18 @@
 if TYPE_CHECKING:  # pragma: no cover
     from .cmd2 import Cmd
 
-P = ParamSpec("P")
+F = TypeVar("F", bound=Callable[..., Any])
 
 
 def with_category(
     category: str,
-) -> Callable[[UnboundCommandFunc[CmdOrSetT, P]], UnboundCommandFunc[CmdOrSetT, P]]:
+) -> Callable[[F], F]:
     """Decorate a ``do_*`` command function to apply a category.
 
+    This decorator has permissive type hints to allow for order-independent stacking
+    with other decorators that may modify the function signature or return type of the
+    command function.
+
     :param category: the name of the category in which this command should
                      be grouped when displaying the list of commands.
     :return: a decorator that assigns the specified category to the command function
@@ -53,7 +57,7 @@ def do_echo(self, args)
 
     """
 
-    def cat_decorator(func: UnboundCommandFunc[CmdOrSetT, P]) -> UnboundCommandFunc[CmdOrSetT, P]:
+    def cat_decorator(func: F) -> F:
         from .utils import categorize
 
         categorize(func, category)
@@ -62,10 +66,6 @@ def cat_decorator(func: UnboundCommandFunc[CmdOrSetT, P]) -> UnboundCommandFunc[
     return cat_decorator
 
 
-# The standard cmd2 command function signature (e.g. do_command(self, statement))
-RawCommandFunc: TypeAlias = UnboundCommandFunc[CmdOrSetT, [Statement | str]]
-
-
 ##########################
 # The _parse_positionals and _arg_swap functions allow for additional positional args to be preserved
 # in cmd2 command functions/callables. As long as the 2-ple of arguments we expect to be there can be
@@ -108,6 +108,10 @@ def _arg_swap(args: Sequence[Any], search_arg: Any, *replace_arg: Any) -> list[A
     return args_list
 
 
+# The standard cmd2 command function signature (e.g. do_command(self, statement))
+RawCommandFunc: TypeAlias = UnboundCommandFunc[CmdOrSetT, [Statement | str]]
+
+
 # Function signature for a command function that accepts a pre-processed argument list from user input
 ArgListCommandFunc: TypeAlias = UnboundCommandFunc[CmdOrSetT, [list[str]]]
 
@@ -340,8 +344,12 @@ def as_subcommand_to(
     help: str | None = None,  # noqa: A002
     aliases: Sequence[str] | None = None,
     **add_parser_kwargs: Any,
-) -> Callable[[ArgparseCommandFunc[CmdOrSetT]], ArgparseCommandFunc[CmdOrSetT]]:
-    """Tag this function as a subcommand to an existing argparse decorated command.
+) -> Callable[[F], F]:
+    """Tag a function as a subcommand to an existing argparse decorated command.
+
+    This decorator has permissive type hints to allow for order-independent stacking
+    with other decorators that may modify the function signature or return type of the
+    subcommand function.
 
     :param command: Command Name. Space-delimited subcommands may optionally be specified
     :param subcommand: Subcommand name
@@ -355,7 +363,7 @@ def as_subcommand_to(
     :return: Wrapper function that can receive an argparse.Namespace
     """
 
-    def arg_decorator(func: ArgparseCommandFunc[CmdOrSetT]) -> ArgparseCommandFunc[CmdOrSetT]:
+    def arg_decorator(func: F) -> F:
         # Set some custom attributes for this command
         setattr(func, constants.SUBCMD_ATTR_COMMAND, command)
         setattr(func, constants.CMD_ATTR_ARGPARSER, parser)