cmd2 2.6.2__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

cmd2/colors.py

@@ -0,0 +1,270 @@
+"""Provides a convenient StrEnum for Rich color names."""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    from backports.strenum import StrEnum
+
+
+class Color(StrEnum):
+    """An enumeration of all color names supported by the Rich library.
+
+    Using this enum allows for autocompletion and prevents typos when referencing
+    color names. The members can be used for both foreground and background colors.
+
+    Aside from DEFAULT, these colors come from the rich.color.ANSI_COLOR_NAMES dictionary.
+
+    Note: The terminal color settings determines the appearance of the follow 16 colors.
+
+    |                |               |
+    |----------------|---------------|
+    | BLACK          | BRIGHT_WHITE  |
+    | BLUE           | BRIGHT_YELLOW |
+    | BRIGHT_BLACK   | CYAN          |
+    | BRIGHT_BLUE    | GREEN         |
+    | BRIGHT_CYAN    | MAGENTA       |
+    | BRIGHT_GREEN   | RED           |
+    | BRIGHT_MAGENTA | WHITE         |
+    | BRIGHT_RED     | YELLOW        |
+    """
+
+    DEFAULT = "default"
+    """Represents the terminal's default foreground or background color."""
+
+    AQUAMARINE1 = "aquamarine1"
+    AQUAMARINE3 = "aquamarine3"
+    BLACK = "black"
+    BLUE = "blue"
+    BLUE1 = "blue1"
+    BLUE3 = "blue3"
+    BLUE_VIOLET = "blue_violet"
+    BRIGHT_BLACK = "bright_black"
+    BRIGHT_BLUE = "bright_blue"
+    BRIGHT_CYAN = "bright_cyan"
+    BRIGHT_GREEN = "bright_green"
+    BRIGHT_MAGENTA = "bright_magenta"
+    BRIGHT_RED = "bright_red"
+    BRIGHT_WHITE = "bright_white"
+    BRIGHT_YELLOW = "bright_yellow"
+    CADET_BLUE = "cadet_blue"
+    CHARTREUSE1 = "chartreuse1"
+    CHARTREUSE2 = "chartreuse2"
+    CHARTREUSE3 = "chartreuse3"
+    CHARTREUSE4 = "chartreuse4"
+    CORNFLOWER_BLUE = "cornflower_blue"
+    CORNSILK1 = "cornsilk1"
+    CYAN = "cyan"
+    CYAN1 = "cyan1"
+    CYAN2 = "cyan2"
+    CYAN3 = "cyan3"
+    DARK_BLUE = "dark_blue"
+    DARK_CYAN = "dark_cyan"
+    DARK_GOLDENROD = "dark_goldenrod"
+    DARK_GREEN = "dark_green"
+    DARK_KHAKI = "dark_khaki"
+    DARK_MAGENTA = "dark_magenta"
+    DARK_OLIVE_GREEN1 = "dark_olive_green1"
+    DARK_OLIVE_GREEN2 = "dark_olive_green2"
+    DARK_OLIVE_GREEN3 = "dark_olive_green3"
+    DARK_ORANGE = "dark_orange"
+    DARK_ORANGE3 = "dark_orange3"
+    DARK_RED = "dark_red"
+    DARK_SEA_GREEN = "dark_sea_green"
+    DARK_SEA_GREEN1 = "dark_sea_green1"
+    DARK_SEA_GREEN2 = "dark_sea_green2"
+    DARK_SEA_GREEN3 = "dark_sea_green3"
+    DARK_SEA_GREEN4 = "dark_sea_green4"
+    DARK_SLATE_GRAY1 = "dark_slate_gray1"
+    DARK_SLATE_GRAY2 = "dark_slate_gray2"
+    DARK_SLATE_GRAY3 = "dark_slate_gray3"
+    DARK_TURQUOISE = "dark_turquoise"
+    DARK_VIOLET = "dark_violet"
+    DEEP_PINK1 = "deep_pink1"
+    DEEP_PINK2 = "deep_pink2"
+    DEEP_PINK3 = "deep_pink3"
+    DEEP_PINK4 = "deep_pink4"
+    DEEP_SKY_BLUE1 = "deep_sky_blue1"
+    DEEP_SKY_BLUE2 = "deep_sky_blue2"
+    DEEP_SKY_BLUE3 = "deep_sky_blue3"
+    DEEP_SKY_BLUE4 = "deep_sky_blue4"
+    DODGER_BLUE1 = "dodger_blue1"
+    DODGER_BLUE2 = "dodger_blue2"
+    DODGER_BLUE3 = "dodger_blue3"
+    GOLD1 = "gold1"
+    GOLD3 = "gold3"
+    GRAY0 = "gray0"
+    GRAY3 = "gray3"
+    GRAY7 = "gray7"
+    GRAY11 = "gray11"
+    GRAY15 = "gray15"
+    GRAY19 = "gray19"
+    GRAY23 = "gray23"
+    GRAY27 = "gray27"
+    GRAY30 = "gray30"
+    GRAY35 = "gray35"
+    GRAY37 = "gray37"
+    GRAY39 = "gray39"
+    GRAY42 = "gray42"
+    GRAY46 = "gray46"
+    GRAY50 = "gray50"
+    GRAY53 = "gray53"
+    GRAY54 = "gray54"
+    GRAY58 = "gray58"
+    GRAY62 = "gray62"
+    GRAY63 = "gray63"
+    GRAY66 = "gray66"
+    GRAY69 = "gray69"
+    GRAY70 = "gray70"
+    GRAY74 = "gray74"
+    GRAY78 = "gray78"
+    GRAY82 = "gray82"
+    GRAY84 = "gray84"
+    GRAY85 = "gray85"
+    GRAY89 = "gray89"
+    GRAY93 = "gray93"
+    GRAY100 = "gray100"
+    GREEN = "green"
+    GREEN1 = "green1"
+    GREEN3 = "green3"
+    GREEN4 = "green4"
+    GREEN_YELLOW = "green_yellow"
+    GREY0 = "grey0"
+    GREY3 = "grey3"
+    GREY7 = "grey7"
+    GREY11 = "grey11"
+    GREY15 = "grey15"
+    GREY19 = "grey19"
+    GREY23 = "grey23"
+    GREY27 = "grey27"
+    GREY30 = "grey30"
+    GREY35 = "grey35"
+    GREY37 = "grey37"
+    GREY39 = "grey39"
+    GREY42 = "grey42"
+    GREY46 = "grey46"
+    GREY50 = "grey50"
+    GREY53 = "grey53"
+    GREY54 = "grey54"
+    GREY58 = "grey58"
+    GREY62 = "grey62"
+    GREY63 = "grey63"
+    GREY66 = "grey66"
+    GREY69 = "grey69"
+    GREY70 = "grey70"
+    GREY74 = "grey74"
+    GREY78 = "grey78"
+    GREY82 = "grey82"
+    GREY84 = "grey84"
+    GREY85 = "grey85"
+    GREY89 = "grey89"
+    GREY93 = "grey93"
+    GREY100 = "grey100"
+    HONEYDEW2 = "honeydew2"
+    HOT_PINK = "hot_pink"
+    HOT_PINK2 = "hot_pink2"
+    HOT_PINK3 = "hot_pink3"
+    INDIAN_RED = "indian_red"
+    INDIAN_RED1 = "indian_red1"
+    KHAKI1 = "khaki1"
+    KHAKI3 = "khaki3"
+    LIGHT_CORAL = "light_coral"
+    LIGHT_CYAN1 = "light_cyan1"
+    LIGHT_CYAN3 = "light_cyan3"
+    LIGHT_GOLDENROD1 = "light_goldenrod1"
+    LIGHT_GOLDENROD2 = "light_goldenrod2"
+    LIGHT_GOLDENROD3 = "light_goldenrod3"
+    LIGHT_GREEN = "light_green"
+    LIGHT_PINK1 = "light_pink1"
+    LIGHT_PINK3 = "light_pink3"
+    LIGHT_PINK4 = "light_pink4"
+    LIGHT_SALMON1 = "light_salmon1"
+    LIGHT_SALMON3 = "light_salmon3"
+    LIGHT_SEA_GREEN = "light_sea_green"
+    LIGHT_SKY_BLUE1 = "light_sky_blue1"
+    LIGHT_SKY_BLUE3 = "light_sky_blue3"
+    LIGHT_SLATE_BLUE = "light_slate_blue"
+    LIGHT_SLATE_GRAY = "light_slate_gray"
+    LIGHT_SLATE_GREY = "light_slate_grey"
+    LIGHT_STEEL_BLUE = "light_steel_blue"
+    LIGHT_STEEL_BLUE1 = "light_steel_blue1"
+    LIGHT_STEEL_BLUE3 = "light_steel_blue3"
+    LIGHT_YELLOW3 = "light_yellow3"
+    MAGENTA = "magenta"
+    MAGENTA1 = "magenta1"
+    MAGENTA2 = "magenta2"
+    MAGENTA3 = "magenta3"
+    MEDIUM_ORCHID = "medium_orchid"
+    MEDIUM_ORCHID1 = "medium_orchid1"
+    MEDIUM_ORCHID3 = "medium_orchid3"
+    MEDIUM_PURPLE = "medium_purple"
+    MEDIUM_PURPLE1 = "medium_purple1"
+    MEDIUM_PURPLE2 = "medium_purple2"
+    MEDIUM_PURPLE3 = "medium_purple3"
+    MEDIUM_PURPLE4 = "medium_purple4"
+    MEDIUM_SPRING_GREEN = "medium_spring_green"
+    MEDIUM_TURQUOISE = "medium_turquoise"
+    MEDIUM_VIOLET_RED = "medium_violet_red"
+    MISTY_ROSE1 = "misty_rose1"
+    MISTY_ROSE3 = "misty_rose3"
+    NAVAJO_WHITE1 = "navajo_white1"
+    NAVAJO_WHITE3 = "navajo_white3"
+    NAVY_BLUE = "navy_blue"
+    ORANGE1 = "orange1"
+    ORANGE3 = "orange3"
+    ORANGE4 = "orange4"
+    ORANGE_RED1 = "orange_red1"
+    ORCHID = "orchid"
+    ORCHID1 = "orchid1"
+    ORCHID2 = "orchid2"
+    PALE_GREEN1 = "pale_green1"
+    PALE_GREEN3 = "pale_green3"
+    PALE_TURQUOISE1 = "pale_turquoise1"
+    PALE_TURQUOISE4 = "pale_turquoise4"
+    PALE_VIOLET_RED1 = "pale_violet_red1"
+    PINK1 = "pink1"
+    PINK3 = "pink3"
+    PLUM1 = "plum1"
+    PLUM2 = "plum2"
+    PLUM3 = "plum3"
+    PLUM4 = "plum4"
+    PURPLE = "purple"
+    PURPLE3 = "purple3"
+    PURPLE4 = "purple4"
+    RED = "red"
+    RED1 = "red1"
+    RED3 = "red3"
+    ROSY_BROWN = "rosy_brown"
+    ROYAL_BLUE1 = "royal_blue1"
+    SALMON1 = "salmon1"
+    SANDY_BROWN = "sandy_brown"
+    SEA_GREEN1 = "sea_green1"
+    SEA_GREEN2 = "sea_green2"
+    SEA_GREEN3 = "sea_green3"
+    SKY_BLUE1 = "sky_blue1"
+    SKY_BLUE2 = "sky_blue2"
+    SKY_BLUE3 = "sky_blue3"
+    SLATE_BLUE1 = "slate_blue1"
+    SLATE_BLUE3 = "slate_blue3"
+    SPRING_GREEN1 = "spring_green1"
+    SPRING_GREEN2 = "spring_green2"
+    SPRING_GREEN3 = "spring_green3"
+    SPRING_GREEN4 = "spring_green4"
+    STEEL_BLUE = "steel_blue"
+    STEEL_BLUE1 = "steel_blue1"
+    STEEL_BLUE3 = "steel_blue3"
+    TAN = "tan"
+    THISTLE1 = "thistle1"
+    THISTLE3 = "thistle3"
+    TURQUOISE2 = "turquoise2"
+    TURQUOISE4 = "turquoise4"
+    VIOLET = "violet"
+    WHEAT1 = "wheat1"
+    WHEAT4 = "wheat4"
+    WHITE = "white"
+    YELLOW = "yellow"
+    YELLOW1 = "yellow1"
+    YELLOW2 = "yellow2"
+    YELLOW3 = "yellow3"
+    YELLOW4 = "yellow4"

cmd2/command_definition.py

@@ -3,7 +3,6 @@
 from collections.abc import Callable, Mapping
 from typing import (
     TYPE_CHECKING,
-    Optional,
     TypeVar,
 )
 
@@ -23,7 +22,7 @@ if TYPE_CHECKING:  # pragma: no cover
 
 #: Callable signature for a basic command  function
 #: Further refinements are needed to define the input parameters
-CommandFunc = Callable[..., Optional[bool]]
+CommandFunc = Callable[..., bool | None]
 
 CommandSetType = TypeVar('CommandSetType', bound=type['CommandSet'])
 
@@ -91,7 +90,7 @@ class CommandSet:
         This will be set when the CommandSet is registered and it should be
         accessed by child classes using the self._cmd property.
         """
-        self.__cmd_internal: Optional[cmd2.Cmd] = None
+        self.__cmd_internal: cmd2.Cmd | None = None
 
         self._settables: dict[str, Settable] = {}
         self._settable_prefix = self.__class__.__name__
@@ -103,8 +102,17 @@ class CommandSet:
         Using this property ensures that self.__cmd_internal has been set
         and it tells type checkers that it's no longer a None type.
 
-        Override this property if you need to change its return type to a
-        child class of Cmd.
+        Override this property to specify a more specific return type for static
+        type checking. The typing.cast function can be used to assert to the
+        type checker that the parent cmd2.Cmd instance is of a more specific
+        subclass, enabling better autocompletion and type safety in the child class.
+
+        For example:
+
+            @property
+            def _cmd(self) -> CustomCmdApp:
+                return cast(CustomCmdApp, super()._cmd)
+
 
         :raises CommandSetRegistrationError: if CommandSet is not registered.
         """

cmd2/constants.py

@@ -18,9 +18,6 @@ MULTILINE_TERMINATOR = ';'
 
 LINE_FEED = '\n'
 
-# One character ellipsis
-HORIZONTAL_ELLIPSIS = '…'
-
 DEFAULT_SHORTCUTS = {'?': 'help', '!': 'shell', '@': 'run_script', '@@': '_relative_run_script'}
 
 # Used as the command name placeholder in disabled command messages.
@@ -55,6 +52,3 @@ PARSER_ATTR_COMMANDSET = 'command_set'
 
 # custom attributes added to argparse Namespaces
 NS_ATTR_SUBCMD_HANDLER = '__subcmd_handler__'
-
-# For cases prior to Python 3.11 when shutil.get_terminal_size().columns can return 0.
-DEFAULT_TERMINAL_WIDTH = 80

cmd2/decorators.py

@@ -5,7 +5,6 @@ from collections.abc import Callable, Sequence
 from typing import (
     TYPE_CHECKING,
     Any,
-    Optional,
     TypeVar,
     Union,
 )
@@ -62,10 +61,10 @@ def with_category(category: str) -> Callable[[CommandFunc], CommandFunc]:
 
 
 CommandParent = TypeVar('CommandParent', bound=Union['cmd2.Cmd', CommandSet])
-CommandParentType = TypeVar('CommandParentType', bound=Union[type['cmd2.Cmd'], type[CommandSet]])
+CommandParentType = TypeVar('CommandParentType', bound=type['cmd2.Cmd'] | type[CommandSet])
 
 
-RawCommandFuncOptionalBoolReturn = Callable[[CommandParent, Union[Statement, str]], Optional[bool]]
+RawCommandFuncOptionalBoolReturn = Callable[[CommandParent, Statement | str], bool | None]
 
 
 ##########################
@@ -73,7 +72,7 @@ RawCommandFuncOptionalBoolReturn = Callable[[CommandParent, Union[Statement, str
 # in cmd2 command functions/callables. As long as the 2-ple of arguments we expect to be there can be
 # found we can swap out the statement with each decorator's specific parameters
 ##########################
-def _parse_positionals(args: tuple[Any, ...]) -> tuple['cmd2.Cmd', Union[Statement, str]]:
+def _parse_positionals(args: tuple[Any, ...]) -> tuple['cmd2.Cmd', Statement | str]:
     """Inspect the positional arguments until the cmd2.Cmd argument is found.
 
     Assumes that we will find cmd2.Cmd followed by the command statement object or string.
@@ -98,7 +97,7 @@ def _parse_positionals(args: tuple[Any, ...]) -> tuple['cmd2.Cmd', Union[Stateme
     raise TypeError('Expected arguments: cmd: cmd2.Cmd, statement: Union[Statement, str] Not found')
 
 
-def _arg_swap(args: Union[Sequence[Any]], search_arg: Any, *replace_arg: Any) -> list[Any]:
+def _arg_swap(args: Sequence[Any], search_arg: Any, *replace_arg: Any) -> list[Any]:
     """Swap the Statement parameter with one or more decorator-specific parameters.
 
     :param args: The original positional arguments
@@ -114,7 +113,7 @@ def _arg_swap(args: Union[Sequence[Any]], search_arg: Any, *replace_arg: Any) ->
 
 #: Function signature for a command function that accepts a pre-processed argument list from user input
 #: and optionally returns a boolean
-ArgListCommandFuncOptionalBoolReturn = Callable[[CommandParent, list[str]], Optional[bool]]
+ArgListCommandFuncOptionalBoolReturn = Callable[[CommandParent, 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 = Callable[[CommandParent, list[str]], bool]
@@ -123,21 +122,21 @@ ArgListCommandFuncBoolReturn = Callable[[CommandParent, list[str]], bool]
 ArgListCommandFuncNoneReturn = Callable[[CommandParent, list[str]], None]
 
 #: Aggregate of all accepted function signatures for command functions that accept a pre-processed argument list
-ArgListCommandFunc = Union[
-    ArgListCommandFuncOptionalBoolReturn[CommandParent],
-    ArgListCommandFuncBoolReturn[CommandParent],
-    ArgListCommandFuncNoneReturn[CommandParent],
-]
+ArgListCommandFunc = (
+    ArgListCommandFuncOptionalBoolReturn[CommandParent]
+    | ArgListCommandFuncBoolReturn[CommandParent]
+    | ArgListCommandFuncNoneReturn[CommandParent]
+)
 
 
 def with_argument_list(
-    func_arg: Optional[ArgListCommandFunc[CommandParent]] = None,
+    func_arg: ArgListCommandFunc[CommandParent] | None = None,
     *,
     preserve_quotes: bool = False,
-) -> Union[
-    RawCommandFuncOptionalBoolReturn[CommandParent],
-    Callable[[ArgListCommandFunc[CommandParent]], RawCommandFuncOptionalBoolReturn[CommandParent]],
-]:
+) -> (
+    RawCommandFuncOptionalBoolReturn[CommandParent]
+    | Callable[[ArgListCommandFunc[CommandParent]], RawCommandFuncOptionalBoolReturn[CommandParent]]
+):
     """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
@@ -169,7 +168,7 @@ def with_argument_list(
         """
 
         @functools.wraps(func)
-        def cmd_wrapper(*args: Any, **kwargs: Any) -> Optional[bool]:
+        def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
             """Command function wrapper which translates command line into an argument list and calls actual command function.
 
             :param args: All positional arguments to this function.  We're expecting there to be:
@@ -181,7 +180,7 @@ def with_argument_list(
             cmd2_app, statement = _parse_positionals(args)
             _, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(command_name, statement, preserve_quotes)
             args_list = _arg_swap(args, statement, parsed_arglist)
-            return func(*args_list, **kwargs)  # type: ignore[call-arg]
+            return func(*args_list, **kwargs)
 
         command_name = func.__name__[len(constants.COMMAND_FUNC_PREFIX) :]
         cmd_wrapper.__doc__ = func.__doc__
@@ -192,60 +191,10 @@ def with_argument_list(
     return arg_decorator
 
 
-def _set_parser_prog(parser: argparse.ArgumentParser, prog: str) -> None:
-    """Recursively set prog attribute of a parser and all of its subparsers.
-
-    Does so that the root command is a command name and not sys.argv[0].
-
-    :param parser: the parser being edited
-    :param prog: new value for the parser's prog attribute
-    """
-    # Set the prog value for this parser
-    parser.prog = prog
-    req_args: list[str] = []
-
-    # Set the prog value for the parser's subcommands
-    for action in parser._actions:
-        if isinstance(action, argparse._SubParsersAction):
-            # Set the _SubParsersAction's _prog_prefix value. That way if its add_parser() method is called later,
-            # the correct prog value will be set on the parser being added.
-            action._prog_prefix = parser.prog
-
-            # The keys of action.choices are subcommand names as well as subcommand aliases. The aliases point to the
-            # same parser as the actual subcommand. We want to avoid placing an alias into a parser's prog value.
-            # Unfortunately there is nothing about an action.choices entry which tells us it's an alias. In most cases
-            # we can filter out the aliases by checking the contents of action._choices_actions. This list only contains
-            # help information and names for the subcommands and not aliases. However, subcommands without help text
-            # won't show up in that list. Since dictionaries are ordered in Python 3.6 and above and argparse inserts the
-            # subcommand name into choices dictionary before aliases, we should be OK assuming the first time we see a
-            # parser, the dictionary key is a subcommand and not alias.
-            processed_parsers = []
-
-            # Set the prog value for each subcommand's parser
-            for subcmd_name, subcmd_parser in action.choices.items():
-                # Check if we've already edited this parser
-                if subcmd_parser in processed_parsers:
-                    continue
-
-                subcmd_prog = parser.prog
-                if req_args:
-                    subcmd_prog += " " + " ".join(req_args)
-                subcmd_prog += " " + subcmd_name
-                _set_parser_prog(subcmd_parser, subcmd_prog)
-                processed_parsers.append(subcmd_parser)
-
-            # We can break since argparse only allows 1 group of subcommands per level
-            break
-
-        # Need to save required args so they can be prepended to the subcommand usage
-        if action.required:
-            req_args.append(action.dest)
-
-
 #: Function signatures for command functions that use an argparse.ArgumentParser to process user input
 #: and optionally return a boolean
-ArgparseCommandFuncOptionalBoolReturn = Callable[[CommandParent, argparse.Namespace], Optional[bool]]
-ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn = Callable[[CommandParent, argparse.Namespace, list[str]], Optional[bool]]
+ArgparseCommandFuncOptionalBoolReturn = Callable[[CommandParent, argparse.Namespace], bool | None]
+ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn = Callable[[CommandParent, argparse.Namespace, list[str]], bool | None]
 
 #: Function signatures for command functions that use an argparse.ArgumentParser to process user input
 #: and return a boolean
@@ -258,30 +207,28 @@ ArgparseCommandFuncNoneReturn = Callable[[CommandParent, argparse.Namespace], No
 ArgparseCommandFuncWithUnknownArgsNoneReturn = Callable[[CommandParent, argparse.Namespace, list[str]], None]
 
 #: Aggregate of all accepted function signatures for an argparse command function
-ArgparseCommandFunc = Union[
-    ArgparseCommandFuncOptionalBoolReturn[CommandParent],
-    ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn[CommandParent],
-    ArgparseCommandFuncBoolReturn[CommandParent],
-    ArgparseCommandFuncWithUnknownArgsBoolReturn[CommandParent],
-    ArgparseCommandFuncNoneReturn[CommandParent],
-    ArgparseCommandFuncWithUnknownArgsNoneReturn[CommandParent],
-]
+ArgparseCommandFunc = (
+    ArgparseCommandFuncOptionalBoolReturn[CommandParent]
+    | ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn[CommandParent]
+    | ArgparseCommandFuncBoolReturn[CommandParent]
+    | ArgparseCommandFuncWithUnknownArgsBoolReturn[CommandParent]
+    | ArgparseCommandFuncNoneReturn[CommandParent]
+    | ArgparseCommandFuncWithUnknownArgsNoneReturn[CommandParent]
+)
 
 
 def with_argparser(
-    parser: Union[
-        argparse.ArgumentParser,  # existing parser
-        Callable[[], argparse.ArgumentParser],  # function or staticmethod
-        Callable[[CommandParentType], argparse.ArgumentParser],  # Cmd or CommandSet classmethod
-    ],
+    parser: argparse.ArgumentParser  # existing parser
+    | Callable[[], argparse.ArgumentParser]  # function or staticmethod
+    | Callable[[CommandParentType], argparse.ArgumentParser],  # Cmd or CommandSet classmethod
     *,
-    ns_provider: Optional[Callable[..., argparse.Namespace]] = None,
+    ns_provider: Callable[..., argparse.Namespace] | None = None,
     preserve_quotes: bool = False,
     with_unknown_args: bool = False,
 ) -> Callable[[ArgparseCommandFunc[CommandParent]], RawCommandFuncOptionalBoolReturn[CommandParent]]:
     """Decorate a ``do_*`` method to populate its ``args`` argument with the given instance of argparse.ArgumentParser.
 
-    :param parser: unique instance of ArgumentParser or a callable that returns an ArgumentParser
+    :param parser: instance of ArgumentParser or a callable that returns an ArgumentParser for this command
     :param ns_provider: An optional function that accepts a cmd2.Cmd or cmd2.CommandSet object as an argument and returns an
                         argparse.Namespace. This is useful if the Namespace needs to be prepopulated with state data that
                         affects parsing.
@@ -336,7 +283,7 @@ def with_argparser(
         """
 
         @functools.wraps(func)
-        def cmd_wrapper(*args: Any, **kwargs: dict[str, Any]) -> Optional[bool]:
+        def cmd_wrapper(*args: Any, **kwargs: dict[str, Any]) -> bool | None:
             """Command function wrapper which translates command line into argparse Namespace and call actual command function.
 
             :param args: All positional arguments to this function.  We're expecting there to be:
@@ -367,7 +314,7 @@ def with_argparser(
                 namespace = ns_provider(provider_self if provider_self is not None else cmd2_app)
 
             try:
-                new_args: Union[tuple[argparse.Namespace], tuple[argparse.Namespace, list[str]]]
+                new_args: tuple[argparse.Namespace] | tuple[argparse.Namespace, list[str]]
                 if with_unknown_args:
                     new_args = arg_parser.parse_known_args(parsed_arglist, namespace)
                 else:
@@ -389,18 +336,10 @@ def with_argparser(
                     delattr(ns, constants.NS_ATTR_SUBCMD_HANDLER)
 
                 args_list = _arg_swap(args, statement_arg, *new_args)
-                return func(*args_list, **kwargs)  # type: ignore[call-arg]
+                return func(*args_list, **kwargs)
 
         command_name = func.__name__[len(constants.COMMAND_FUNC_PREFIX) :]
 
-        if isinstance(parser, argparse.ArgumentParser):
-            # Set parser's prog value for backward compatibility within the cmd2 2.0 family.
-            # This will be removed in cmd2 3.0 since we never reference this parser object's prog value.
-            # Since it's possible for the same parser object to be passed into multiple with_argparser()
-            # calls, we only set prog on the deep copies of this parser based on the specific do_xxxx
-            # instance method they are associated with.
-            _set_parser_prog(parser, command_name)
-
         # Set some custom attributes for this command
         setattr(cmd_wrapper, constants.CMD_ATTR_ARGPARSER, parser)
         setattr(cmd_wrapper, constants.CMD_ATTR_PRESERVE_QUOTES, preserve_quotes)
@@ -413,20 +352,18 @@ def with_argparser(
 def as_subcommand_to(
     command: str,
     subcommand: str,
-    parser: Union[
-        argparse.ArgumentParser,  # existing parser
-        Callable[[], argparse.ArgumentParser],  # function or staticmethod
-        Callable[[CommandParentType], argparse.ArgumentParser],  # Cmd or CommandSet classmethod
-    ],
+    parser: argparse.ArgumentParser  # existing parser
+    | Callable[[], argparse.ArgumentParser]  # function or staticmethod
+    | Callable[[CommandParentType], argparse.ArgumentParser],  # Cmd or CommandSet classmethod
     *,
-    help: Optional[str] = None,  # noqa: A002
-    aliases: Optional[list[str]] = None,
+    help: str | None = None,  # noqa: A002
+    aliases: list[str] | None = None,
 ) -> Callable[[ArgparseCommandFunc[CommandParent]], ArgparseCommandFunc[CommandParent]]:
     """Tag this method as a subcommand to an existing argparse decorated command.
 
     :param command: Command Name. Space-delimited subcommands may optionally be specified
     :param subcommand: Subcommand name
-    :param parser: argparse Parser for this subcommand
+    :param parser: instance of ArgumentParser or a callable that returns an ArgumentParser for this subcommand
     :param help: Help message for this subcommand which displays in the list of subcommands of the command we are adding to.
                  This is passed as the help argument to subparsers.add_parser().
     :param aliases: Alternative names for this subcommand. This is passed as the alias argument to

cmd2/exceptions.py

@@ -40,7 +40,7 @@ class CompletionError(Exception):
     def __init__(self, *args: Any, apply_style: bool = True) -> None:
         """Initialize CompletionError instance.
 
-        :param apply_style: If True, then ansi.style_error will be applied to the message text when printed.
+        :param apply_style: If True, then styles.ERROR will be applied to the message text when printed.
                             Set to False in cases where the message text already has the desired style.
                             Defaults to True.
         """

cmd2/history.py

@@ -11,14 +11,10 @@ from dataclasses import (
 )
 from typing import (
     Any,
-    Optional,
-    Union,
     overload,
 )
 
-from . import (
-    utils,
-)
+from . import string_utils as su
 from .parsing import (
     Statement,
     shlex_split,
@@ -164,7 +160,7 @@ class History(list[HistoryItem]):
         """Start a new session, thereby setting the next index as the first index in the new session."""
         self.session_start_index = len(self)
 
-    def _zero_based_index(self, onebased: Union[int, str]) -> int:
+    def _zero_based_index(self, onebased: int | str) -> int:
         """Convert a one-based index to a zero-based index."""
         result = int(onebased)
         if result > 0:
@@ -177,7 +173,7 @@ class History(list[HistoryItem]):
     @overload
     def append(self, new: Statement) -> None: ...  # pragma: no cover
 
-    def append(self, new: Union[Statement, HistoryItem]) -> None:
+    def append(self, new: Statement | HistoryItem) -> None:
         """Append a new statement to the end of the History list.
 
         :param new: Statement object which will be composed into a HistoryItem
@@ -289,9 +285,9 @@ class History(list[HistoryItem]):
 
         def isin(history_item: HistoryItem) -> bool:
             """Filter function for string search of history."""
-            sloppy = utils.norm_fold(search)
-            inraw = sloppy in utils.norm_fold(history_item.raw)
-            inexpanded = sloppy in utils.norm_fold(history_item.expanded)
+            sloppy = su.norm_fold(search)
+            inraw = sloppy in su.norm_fold(history_item.raw)
+            inexpanded = sloppy in su.norm_fold(history_item.expanded)
             return inraw or inexpanded
 
         start = 0 if include_persisted else self.session_start_index
@@ -332,7 +328,7 @@ class History(list[HistoryItem]):
             del self[0:last_element]
 
     def _build_result_dictionary(
-        self, start: int, end: int, filter_func: Optional[Callable[[HistoryItem], bool]] = None
+        self, start: int, end: int, filter_func: Callable[[HistoryItem], bool] | None = None
     ) -> 'OrderedDict[int, HistoryItem]':
         """Build history search results.