cmd2.argparse_utils

@contextlib.contextmanager
def output_to(self, file: IO[str] | None) -> Iterator[None]:
    """Context manager to temporarily set the output stream during argparse operations.

    This is helpful for directing output for functions like `parse_args()`, which
    default to `sys.stdout` and lack a `file` argument.

    :param file: the file stream to use for output
    """
    previous = self._thread_locals.current_output_file
    self._thread_locals.current_output_file = file
    try:
        yield
    finally:
        self._thread_locals.current_output_file = previous

def print_usage(self, file: IO[str] | None = None) -> None:  # type:ignore[override]
    """Override to ensure the formatter is aware of the target file."""
    if file is None:
        file = self._thread_locals.current_output_file

    with self.output_to(file):
        super().print_usage(file)

def print_help(self, file: IO[str] | None = None) -> None:  # type:ignore[override]
    """Override to ensure the formatter is aware of the target file."""
    if file is None:
        file = self._thread_locals.current_output_file

    with self.output_to(file):
        super().print_help(file)

def get_subparsers_action(self) -> "argparse._SubParsersAction[Cmd2ArgumentParser]":
    """Get the _SubParsersAction for this parser if it exists.

    :return: the _SubParsersAction for this parser
    :raises ValueError: if this parser does not support subcommands
    """
    if self._subparsers is not None:
        for action in self._subparsers._group_actions:
            if isinstance(action, argparse._SubParsersAction):
                return action
    raise ValueError(f"Command '{self.prog}' does not support subcommands")

def update_prog(self, prog: str) -> None:
    """Recursively update the prog attribute of this parser and all of its subparsers.

    :param prog: new value for this parser's prog attribute
    """
    # Set the prog value for this parser
    self.prog = prog

    try:
        subparsers_action = self.get_subparsers_action()
    except ValueError:
        # This parser has no subcommands
        return

    # Get all positional arguments which appear before the subcommand.
    positionals: list[argparse.Action] = []
    for action in self._actions:
        if action is subparsers_action:
            break

        # Save positional argument
        if not action.option_strings:
            positionals.append(action)

    # Update _prog_prefix. This ensures that any subcommands added later via
    # add_parser() will have the correct prog value.
    subparsers_action._prog_prefix = self._build_subparsers_prog_prefix(positionals)

    # subparsers_action._name_parser_map includes aliases. Since primary names are inserted
    # first, we skip already updated parsers to ensure primary names are used in 'prog'.
    # We can't rely on subparsers_action._choices_actions to filter out aliases because while
    # it contains only primary names, it omits any subcommands that lack help text.
    updated_parsers: set[Cmd2ArgumentParser] = set()

    # Set the prog value for each subcommand's parser
    for subcmd_name, subcmd_parser in subparsers_action._name_parser_map.items():
        if subcmd_parser in updated_parsers:
            continue

        subcmd_prog = f"{subparsers_action._prog_prefix} {subcmd_name}"
        subcmd_parser.update_prog(subcmd_prog)
        updated_parsers.add(subcmd_parser)

def find_parser(self, subcommand_path: Iterable[str]) -> "Cmd2ArgumentParser":
    """Find a parser in the hierarchy based on a sequence of subcommand names.

    :param subcommand_path: sequence of subcommand names leading to the target parser
    :return: the discovered parser
    :raises ValueError: if any subcommand in the path is not found or a level doesn't support subcommands
    """
    parser = self
    for name in subcommand_path:
        subparsers_action = parser.get_subparsers_action()
        if name not in subparsers_action._name_parser_map:
            raise ValueError(f"Subcommand '{name}' does not exist for '{parser.prog}'")
        parser = subparsers_action._name_parser_map[name]
    return parser

def attach_subcommand(
    self,
    record: SubcommandRecord,
    subcommand_path: Iterable[str] = (),
) -> None:
    """Attach a parser as a subcommand to a command at the specified path.

    Note: `record.command` is not used for navigation here. It is assumed you
    are attaching relative to `self` using `subcommand_path`. However,
    `record.command` will be updated to reflect the final, absolute path
    of the parent parser this subcommand is attached to.

    :param record: SubcommandRecord object describing the subcommand
    :param subcommand_path: sequence of subcommand names leading to the parser that will
                            host the new subcommand. An empty sequence indicates this parser.
    :raises TypeError: if record.parser is not an instance of Cmd2ArgumentParser (or subclass)
    :raises ValueError: if the command path is invalid, doesn't support subcommands, or the
                        subcommand already exists
    """
    if not isinstance(record.parser, Cmd2ArgumentParser):
        raise TypeError(
            f"The attached parser must be an instance of 'Cmd2ArgumentParser' (or subclass). "
            f"Received: '{type(record.parser).__name__}'."
        )

    target_parser = self.find_parser(subcommand_path)
    subparsers_action = target_parser.get_subparsers_action()

    # Verify the parser is compatible with the 'parser_class' configured for this
    # subcommand group. We use isinstance() here to allow for subclasses, providing
    # more flexibility than the standard add_parser() factory approach which enforces
    # a specific class.
    if not isinstance(record.parser, subparsers_action._parser_class):
        raise TypeError(
            f"The attached parser must be an instance of '{subparsers_action._parser_class.__name__}' "
            f"(or subclass) to match the 'parser_class' configured for this subcommand group. "
            f"Received: '{type(record.parser).__name__}'."
        )

    # Do not overwrite existing subcommands or aliases
    all_names = (record.name, *record.aliases)
    for name in all_names:
        if name in subparsers_action._name_parser_map:
            raise ValueError(f"Subcommand '{name}' already exists for '{target_parser.prog}'")

    # Registration kwargs
    kwargs: dict[str, Any] = {"aliases": record.aliases}
    if record.help is not None:
        kwargs["help"] = record.help
    if record.deprecated:
        kwargs["deprecated"] = record.deprecated

    # Use add_parser to register the subcommand name and any aliases
    placeholder_parser = subparsers_action.add_parser(record.name, **kwargs)

    # To ensure accurate usage strings, recursively update 'prog' values
    # within the injected parser to match its new location in the command hierarchy.
    record.parser.update_prog(placeholder_parser.prog)

    # Replace the parser created by add_parser() with our pre-configured one
    subparsers_action._name_parser_map[record.name] = record.parser

    # Remap any aliases to our pre-configured parser
    for alias in record.aliases:
        subparsers_action._name_parser_map[alias] = record.parser

    # Update command to reflect the parent parser's absolute path
    record.command = target_parser.prog

def detach_subcommand(self, subcommand_path: Iterable[str], subcommand: str) -> SubcommandRecord:
    """Detach a subcommand from a command at the specified path.

    :param subcommand_path: sequence of subcommand names leading to the parser hosting the
                            subcommand to be detached. An empty sequence indicates this parser.
    :param subcommand: name of the subcommand to detach
    :return: a SubcommandRecord object describing the detached subcommand
    :raises ValueError: if the command path is invalid or the subcommand doesn't exist
    """
    target_parser = self.find_parser(subcommand_path)
    subparsers_action = target_parser.get_subparsers_action()

    try:
        record = cast(
            SubcommandRecord,
            subparsers_action.remove_parser(subcommand),  # type: ignore[attr-defined]
        )
    except ValueError:
        raise ValueError(f"Subcommand '{subcommand}' does not exist for '{target_parser.prog}'") from None

    # Update command to reflect the parent parser's absolute path
    record.command = target_parser.prog
    return record

def detach_all_subcommands(self, subcommand_path: Iterable[str]) -> list[SubcommandRecord]:
    """Detach all subcommands from a command at the specified path.

    :param subcommand_path: sequence of subcommand names leading to the parser hosting the
                            subcommands to be detached. An empty sequence indicates this parser.
    :return: a list of SubcommandRecord objects describing the detached subcommands
    :raises ValueError: if the command path is invalid or the command doesn't support subcommands
    """
    target_parser = self.find_parser(subcommand_path)
    subparsers_action = target_parser.get_subparsers_action()

    records = cast(
        list[SubcommandRecord],
        subparsers_action.remove_all_parsers(),  # type: ignore[attr-defined]
    )
    # Update command for each detached subcommand
    for record in records:
        record.command = target_parser.prog
    return records

def error(self, message: str) -> NoReturn:
    """Override that applies custom formatting to the error message."""
    lines = message.split("\n")
    formatted_message = ""
    for linum, line in enumerate(lines):
        if linum == 0:
            formatted_message = "Error: " + line
        else:
            formatted_message += "\n       " + line

    with self.output_to(sys.stderr):
        self.print_usage(sys.stderr)

        # Use console to add style since it will respect ALLOW_STYLE's value.
        # Now _get_formatter() will return a formatter bound to stderr.
        console = self._get_formatter().console
        with console.capture() as capture:
            console.print(formatted_message, style=Cmd2Style.ERROR)
        formatted_message = f"{capture.get()}"

    self.exit(2, f"{formatted_message}\n")

def format_help(self) -> str:
    """Override to add a newline."""
    return super().format_help() + "\n"

def register(self, registry_name, value, object):
    registry = self._registries.setdefault(registry_name, {})
    registry[value] = object

def set_defaults(self, **kwargs):
    self._defaults.update(kwargs)

    # if these defaults match any existing arguments, replace
    # the previous default on the object with the new one
    for action in self._actions:
        if action.dest in kwargs:
            action.default = kwargs[action.dest]

def get_default(self, dest):
    for action in self._actions:
        if action.dest == dest and action.default is not None:
            return action.default
    return self._defaults.get(dest, None)

def add_argument(self, *args, **kwargs):
    """
    add_argument(dest, ..., name=value, ...)
    add_argument(option_string, option_string, ..., name=value, ...)
    """

    # if no positional args are supplied or only one is supplied and
    # it doesn't look like an option string, parse a positional
    # argument
    chars = self.prefix_chars
    if not args or len(args) == 1 and args[0][0] not in chars:
        if args and 'dest' in kwargs:
            raise TypeError('dest supplied twice for positional argument,'
                            ' did you mean metavar?')
        kwargs = self._get_positional_kwargs(*args, **kwargs)

    # otherwise, we're adding an optional argument
    else:
        kwargs = self._get_optional_kwargs(*args, **kwargs)

    # if no default was supplied, use the parser-level default
    if 'default' not in kwargs:
        dest = kwargs['dest']
        if dest in self._defaults:
            kwargs['default'] = self._defaults[dest]
        elif self.argument_default is not None:
            kwargs['default'] = self.argument_default

    # create the action object, and add it to the parser
    action_name = kwargs.get('action')
    action_class = self._pop_action_class(kwargs)
    if not callable(action_class):
        raise ValueError(f'unknown action {action_class!r}')
    action = action_class(**kwargs)

    # raise an error if action for positional argument does not
    # consume arguments
    if not action.option_strings and action.nargs == 0:
        raise ValueError(f'action {action_name!r} is not valid for positional arguments')

    # raise an error if the action type is not callable
    type_func = self._registry_get('type', action.type, action.type)
    if not callable(type_func):
        raise TypeError(f'{type_func!r} is not callable')

    if type_func is FileType:
        raise TypeError(f'{type_func!r} is a FileType class object, '
                        f'instance of it must be passed')

    # raise an error if the metavar does not match the type
    if hasattr(self, "_get_formatter"):
        formatter = self._get_formatter()
        try:
            formatter._format_args(action, None)
        except TypeError:
            raise ValueError("length of metavar tuple does not match nargs")
    self._check_help(action)
    return self._add_action(action)

def add_argument_group(self, *args, **kwargs):
    group = _ArgumentGroup(self, *args, **kwargs)
    self._action_groups.append(group)
    return group

def add_mutually_exclusive_group(self, **kwargs):
    group = _MutuallyExclusiveGroup(self, **kwargs)
    self._mutually_exclusive_groups.append(group)
    return group

def add_subparsers(self, **kwargs):
    if self._subparsers is not None:
        raise ValueError('cannot have multiple subparser arguments')

    # add the parser class to the arguments if it's not present
    kwargs.setdefault('parser_class', type(self))

    if 'title' in kwargs or 'description' in kwargs:
        title = kwargs.pop('title', _('subcommands'))
        description = kwargs.pop('description', None)
        self._subparsers = self.add_argument_group(title, description)
    else:
        self._subparsers = self._positionals

    # prog defaults to the usage message of this parser, skipping
    # optional arguments and with no "usage:" prefix
    if kwargs.get('prog') is None:
        formatter = self._get_formatter()
        positionals = self._get_positional_actions()
        groups = self._mutually_exclusive_groups
        formatter.add_usage(None, positionals, groups, '')
        kwargs['prog'] = formatter.format_help().strip()

    # create the parsers action and add it to the positionals list
    parsers_class = self._pop_action_class(kwargs, 'parsers')
    action = parsers_class(option_strings=[], **kwargs)
    action._color = self.color
    self._check_help(action)
    self._subparsers._add_action(action)

    # return the created parsers action
    return action

def parse_args(self, args=None, namespace=None):
    args, argv = self.parse_known_args(args, namespace)
    if argv:
        msg = _('unrecognized arguments: %s') % ' '.join(argv)
        if self.exit_on_error:
            self.error(msg)
        else:
            raise ArgumentError(None, msg)
    return args

def parse_known_args(self, args=None, namespace=None):
    return self._parse_known_args2(args, namespace, intermixed=False)

def convert_arg_line_to_args(self, arg_line):
    return [arg_line]

def parse_intermixed_args(self, args=None, namespace=None):
    args, argv = self.parse_known_intermixed_args(args, namespace)
    if argv:
        msg = _('unrecognized arguments: %s') % ' '.join(argv)
        if self.exit_on_error:
            self.error(msg)
        else:
            raise ArgumentError(None, msg)
    return args

def parse_known_intermixed_args(self, args=None, namespace=None):
    # returns a namespace and list of extras
    #
    # positional can be freely intermixed with optionals.  optionals are
    # first parsed with all positional arguments deactivated.  The 'extras'
    # are then parsed.  If the parser definition is incompatible with the
    # intermixed assumptions (e.g. use of REMAINDER, subparsers) a
    # TypeError is raised.

    positionals = self._get_positional_actions()
    a = [action for action in positionals
         if action.nargs in [PARSER, REMAINDER]]
    if a:
        raise TypeError('parse_intermixed_args: positional arg'
                        ' with nargs=%s'%a[0].nargs)

    return self._parse_known_args2(args, namespace, intermixed=True)

def format_usage(self):
    formatter = self._get_formatter()
    formatter.add_usage(self.usage, self._actions,
                        self._mutually_exclusive_groups)
    return formatter.format_help()

def exit(self, status=0, message=None):
    if message:
        self._print_message(message, _sys.stderr)
    _sys.exit(status)