Simplified type aliases in decorators.py.

Author: kmvanbrunt

CHANGELOG.md

@@ -109,9 +109,9 @@ prompt is displayed.
         - For more details and examples, see the [Help](docs/features/help.md) documentation and the
           `examples/default_categories.py` file.
     - `CommandSet` is now a generic class, which allows developers to parameterize it with their
-      specific`cmd2.Cmd`subclass (e.g.,`class MyCommandSet(CommandSet[MyApp]):`). This provides full
-      type hints and IDE autocompletion for `self._cmd` without needing to override and cast the
-      property.
+      specific `cmd2.Cmd`subclass (e.g.,`class MyCommandSet(CommandSet[MyApp]):`). This provides
+      full type hints and IDE autocompletion for `self._cmd` without needing to override and cast
+      the property.
 
 ## 3.5.0 (April 13, 2026)
 

cmd2/decorators.py

@@ -8,6 +8,7 @@
 from typing import (
     TYPE_CHECKING,
     Any,
+    ParamSpec,
     TypeAlias,
 )
 
@@ -19,14 +20,18 @@
 from .types import (
     CmdOrSetClassT,
     CmdOrSetT,
-    UnboundCommandFuncT,
+    UnboundCommandFunc,
 )
 
 if TYPE_CHECKING:  # pragma: no cover
     from .cmd2 import Cmd
 
+P = ParamSpec("P")
 
-def with_category(category: str) -> Callable[[UnboundCommandFuncT], UnboundCommandFuncT]:
+
+def with_category(
+    category: str,
+) -> Callable[[UnboundCommandFunc[CmdOrSetT, P]], UnboundCommandFunc[CmdOrSetT, P]]:
     """Decorate a ``do_*`` command method to apply a category.
 
     :param category: the name of the category in which this command should
@@ -45,7 +50,7 @@ def do_echo(self, args)
 
     """
 
-    def cat_decorator(func: UnboundCommandFuncT) -> UnboundCommandFuncT:
+    def cat_decorator(func: UnboundCommandFunc[CmdOrSetT, P]) -> UnboundCommandFunc[CmdOrSetT, P]:
         from .utils import categorize
 
         categorize(func, category)
@@ -54,7 +59,8 @@ def cat_decorator(func: UnboundCommandFuncT) -> UnboundCommandFuncT:
     return cat_decorator
 
 
-RawCommandFuncOptionalBoolReturn: TypeAlias = Callable[[CmdOrSetT, Statement | str], bool | None]
+# The standard cmd2 command function signature (e.g. do_command(self, statement))
+RawCommandFunc: TypeAlias = UnboundCommandFunc[CmdOrSetT, [Statement | str]]
 
 
 ##########################
@@ -102,37 +108,20 @@ def _arg_swap(args: Sequence[Any], search_arg: Any, *replace_arg: Any) -> list[A
 
 
 # Function signature for a command function that accepts a pre-processed argument list from user input
-# and optionally returns a boolean
-ArgListCommandFuncOptionalBoolReturn: TypeAlias = Callable[[CmdOrSetT, list[str]], bool | None]
-# Function signature for a command function that accepts a pre-processed argument list from user input
-# and returns a boolean
-ArgListCommandFuncBoolReturn: TypeAlias = Callable[[CmdOrSetT, list[str]], bool]
-# Function signature for a command function that accepts a pre-processed argument list from user input
-# and returns Nothing
-ArgListCommandFuncNoneReturn: TypeAlias = Callable[[CmdOrSetT, list[str]], None]
-
-# Aggregate of all accepted function signatures for command functions that accept a pre-processed argument list
-ArgListCommandFunc: TypeAlias = (
-    ArgListCommandFuncOptionalBoolReturn[CmdOrSetT]
-    | ArgListCommandFuncBoolReturn[CmdOrSetT]
-    | ArgListCommandFuncNoneReturn[CmdOrSetT]
-)
+ArgListCommandFunc: TypeAlias = UnboundCommandFunc[CmdOrSetT, [list[str]]]
 
 
 def with_argument_list(
     func_arg: ArgListCommandFunc[CmdOrSetT] | None = None,
     *,
     preserve_quotes: bool = False,
-) -> (
-    RawCommandFuncOptionalBoolReturn[CmdOrSetT]
-    | Callable[[ArgListCommandFunc[CmdOrSetT]], RawCommandFuncOptionalBoolReturn[CmdOrSetT]]
-):
+) -> RawCommandFunc[CmdOrSetT] | Callable[[ArgListCommandFunc[CmdOrSetT]], RawCommandFunc[CmdOrSetT]]:
     """Decorate a ``do_*`` method to alter the arguments passed to it so it is passed a list[str].
 
     Default passes a string of whatever the user typed. With this decorator, the
     decorated method will receive a list of arguments parsed from user input.
 
-    :param func_arg: Single-element positional argument list containing ``doi_*`` method
+    :param func_arg: Single-element positional argument list containing ``do_*`` method
                  this decorator is wrapping
     :param preserve_quotes: if ``True``, then argument quotes will not be stripped
     :return: function that gets passed a list of argument strings
@@ -148,7 +137,7 @@ def do_echo(self, arglist):
     """
     import functools
 
-    def arg_decorator(func: ArgListCommandFunc[CmdOrSetT]) -> RawCommandFuncOptionalBoolReturn[CmdOrSetT]:
+    def arg_decorator(func: ArgListCommandFunc[CmdOrSetT]) -> RawCommandFunc[CmdOrSetT]:
         """Decorate function that ingests an Argument List function and returns a raw command function.
 
         The returned function will process the raw input into an argument list to be passed to the wrapped function.
@@ -182,30 +171,11 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
 
 
 # Function signatures for command functions that use a Cmd2ArgumentParser to process user input
-# and optionally return a boolean
-ArgparseCommandFuncOptionalBoolReturn: TypeAlias = Callable[[CmdOrSetT, argparse.Namespace], bool | None]
-ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn: TypeAlias = Callable[
-    [CmdOrSetT, argparse.Namespace, list[str]], bool | None
-]
-
-# Function signatures for command functions that use a Cmd2ArgumentParser to process user input
-# and return a boolean
-ArgparseCommandFuncBoolReturn: TypeAlias = Callable[[CmdOrSetT, argparse.Namespace], bool]
-ArgparseCommandFuncWithUnknownArgsBoolReturn: TypeAlias = Callable[[CmdOrSetT, argparse.Namespace, list[str]], bool]
-
-# Function signatures for command functions that use a Cmd2ArgumentParser to process user input
-# and return nothing
-ArgparseCommandFuncNoneReturn: TypeAlias = Callable[[CmdOrSetT, argparse.Namespace], None]
-ArgparseCommandFuncWithUnknownArgsNoneReturn: TypeAlias = Callable[[CmdOrSetT, argparse.Namespace, list[str]], None]
-
-# Aggregate of all accepted function signatures for an argparse command function
 ArgparseCommandFunc: TypeAlias = (
-    ArgparseCommandFuncOptionalBoolReturn[CmdOrSetT]
-    | ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn[CmdOrSetT]
-    | ArgparseCommandFuncBoolReturn[CmdOrSetT]
-    | ArgparseCommandFuncWithUnknownArgsBoolReturn[CmdOrSetT]
-    | ArgparseCommandFuncNoneReturn[CmdOrSetT]
-    | ArgparseCommandFuncWithUnknownArgsNoneReturn[CmdOrSetT]
+    # (self, args: argparse.Namespace)
+    UnboundCommandFunc[CmdOrSetT, [argparse.Namespace]]
+    # (self, args: argparse.Namespace, unknown_args: list[str])
+    | UnboundCommandFunc[CmdOrSetT, [argparse.Namespace, list[str]]]
 )
 
 
@@ -217,7 +187,7 @@ def with_argparser(
     ns_provider: Callable[..., argparse.Namespace] | None = None,
     preserve_quotes: bool = False,
     with_unknown_args: bool = False,
-) -> Callable[[ArgparseCommandFunc[CmdOrSetT]], RawCommandFuncOptionalBoolReturn[CmdOrSetT]]:
+) -> Callable[[ArgparseCommandFunc[CmdOrSetT]], RawCommandFunc[CmdOrSetT]]:
     """Decorate a ``do_*`` method to populate its ``args`` argument with the given instance of Cmd2ArgumentParser.
 
     :param parser: instance of Cmd2ArgumentParser or a callable that returns a Cmd2ArgumentParser for this command
@@ -265,7 +235,7 @@ def do_argprint(self, args, unknown):
     """
     import functools
 
-    def arg_decorator(func: ArgparseCommandFunc[CmdOrSetT]) -> RawCommandFuncOptionalBoolReturn[CmdOrSetT]:
+    def arg_decorator(func: ArgparseCommandFunc[CmdOrSetT]) -> RawCommandFunc[CmdOrSetT]:
         """Decorate function that ingests an Argparse Command Function and returns a raw command function.
 
         The returned function will process the raw input into an argparse Namespace to be passed to the wrapped function.

cmd2/types.py

@@ -9,6 +9,7 @@
     TYPE_CHECKING,
     Any,
     Concatenate,
+    ParamSpec,
     TypeAlias,
     TypeVar,
     Union,
@@ -19,6 +20,10 @@
     from .command_set import CommandSet
     from .completion import Choices, Completions
 
+# TypeVar for function parameters
+P = ParamSpec("P")
+
+
 ##################################################################################################
 # Cmd and CommandSet Aliases (For basic inputs)
 #
@@ -67,11 +72,7 @@
 
 # An unbound cmd2 command function (e.g. the class method do_command).
 # The 'self' argument can be either a Cmd or CommandSet instance.
-UnboundCommandFunc: TypeAlias = Callable[Concatenate[CmdOrSetT, ...], bool | None]
-
-# TypeVar for unbound command methods that preserves the specific signature.
-# This allows decorators to return a function with the same argument types as the original.
-UnboundCommandFuncT = TypeVar("UnboundCommandFuncT", bound=UnboundCommandFunc[Any])
+UnboundCommandFunc: TypeAlias = Callable[Concatenate[CmdOrSetT, P], bool | None]
 
 
 ##################################################################################################