Method attach_subcommand

cmd2/argparse_utils.py:772–830

Attach a parser as a subcommand to a command at the specified path. :param subcommand_path: sequence of subcommand names leading to the parser that will host the new subcommand. An empty sequence indicates this parser. :param subcommand: name of the n

(
        self,
        subcommand_path: Iterable[str],
        subcommand: str,
        subcommand_parser: "Cmd2ArgumentParser",
        **add_parser_kwargs: Any,
    )

        return parser

    def attach_subcommand(
        self,
        subcommand_path: Iterable[str],
        subcommand: str,
        subcommand_parser: "Cmd2ArgumentParser",
        **add_parser_kwargs: Any,
    ) -> None:
        """Attach a parser as a subcommand to a command at the specified path.

        :param subcommand_path: sequence of subcommand names leading to the parser that will
                                host the new subcommand. An empty sequence indicates this parser.
        :param subcommand: name of the new subcommand
        :param subcommand_parser: the parser to attach
        :param add_parser_kwargs: additional arguments for the subparser registration (e.g. help, aliases)
        :raises TypeError: if subcommand_parser is not an instance of the following or their subclasses:
                           1. Cmd2ArgumentParser
                           2. The parser_class configured for the target subcommand group
        :raises ValueError: if the command path is invalid, doesn't support subcommands, or the
                            subcommand already exists
        """
        if not isinstance(subcommand_parser, Cmd2ArgumentParser):
            raise TypeError(
                f"The attached parser must be an instance of 'Cmd2ArgumentParser' (or a subclass). "
                f"Received: '{type(subcommand_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(subcommand_parser, subparsers_action._parser_class):
            raise TypeError(
                f"The attached parser must be an instance of '{subparsers_action._parser_class.__name__}' "
                f"(or a subclass) to match the 'parser_class' configured for this subcommand group. "
                f"Received: '{type(subcommand_parser).__name__}'."
            )

        # Do not overwrite existing subcommands or aliases
        all_names = (subcommand, *add_parser_kwargs.get("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}'")

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

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

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

        # Remap any aliases to our pre-configured parser
        for alias in add_parser_kwargs.get("aliases", ()):