cmd2.Cmd

def find_commandsets(
    self, commandset_type: type[CommandSet[Any]], *, subclass_match: bool = False
) -> list[CommandSet[Any]]:
    """Find all CommandSets that match the provided CommandSet type.

    By default, locates a CommandSet that is an exact type match but may optionally return all CommandSets that
    are sub-classes of the provided type
    :param commandset_type: CommandSet sub-class type to search for
    :param subclass_match: If True, return all sub-classes of provided type, otherwise only search for exact match
    :return: Matching CommandSets
    """
    return [
        cmdset
        for cmdset in self._installed_command_sets
        if type(cmdset) == commandset_type or (subclass_match and isinstance(cmdset, commandset_type))  # noqa: E721
    ]

def find_commandset_for_command(self, command_name: str) -> CommandSet[Any] | None:
    """Find the CommandSet that registered the command name.

    :param command_name: command name to search
    :return: CommandSet that provided the command
    """
    return self._cmd_to_command_sets.get(command_name)

def register_command_set(self, cmdset: CommandSet[Any]) -> None:
    """Installs a CommandSet, loading all commands defined in the CommandSet.

    :param cmdset: CommandSet to load
    """
    existing_commandset_types = [type(command_set) for command_set in self._installed_command_sets]
    if type(cmdset) in existing_commandset_types:
        raise CommandSetRegistrationError("CommandSet " + type(cmdset).__name__ + " is already installed")

    all_settables = self.settables
    if self.always_prefix_settables:
        if not cmdset.settable_prefix.strip():
            raise CommandSetRegistrationError("CommandSet settable prefix must not be empty")
        for key in cmdset.settables:
            prefixed_name = f"{cmdset.settable_prefix}.{key}"
            if prefixed_name in all_settables:
                raise CommandSetRegistrationError(f"Duplicate settable: {key}")

    else:
        for key in cmdset.settables:
            if key in all_settables:
                raise CommandSetRegistrationError(f"Duplicate settable {key} is already registered")

    cmdset.on_register(self)
    methods = cast(
        list[tuple[str, Callable[..., Any]]],
        inspect.getmembers(
            cmdset,
            predicate=lambda meth: (  # type: ignore[arg-type]
                isinstance(meth, Callable)  # type: ignore[arg-type]
                and hasattr(meth, "__name__")
                and meth.__name__.startswith(COMMAND_FUNC_PREFIX)
            ),
        ),
    )

    installed_attributes = []
    try:
        for cmd_func_name, command_method in methods:
            command = cmd_func_name[len(COMMAND_FUNC_PREFIX) :]

            self._install_command_function(cmd_func_name, command_method, type(cmdset).__name__)
            installed_attributes.append(cmd_func_name)

            completer_func_name = COMPLETER_FUNC_PREFIX + command
            cmd_completer = getattr(cmdset, completer_func_name, None)
            if cmd_completer is not None:
                self._install_completer_function(command, cmd_completer)
                installed_attributes.append(completer_func_name)

            help_func_name = HELP_FUNC_PREFIX + command
            cmd_help = getattr(cmdset, help_func_name, None)
            if cmd_help is not None:
                self._install_help_function(command, cmd_help)
                installed_attributes.append(help_func_name)

            self._cmd_to_command_sets[command] = cmdset

            # If this command is in a disabled category, then disable it
            command_category = self._get_command_category(command_method)
            if command_category in self.disabled_categories:
                message_to_print = self.disabled_categories[command_category]
                self.disable_command(command, message_to_print)

        self._installed_command_sets.add(cmdset)

        self._register_subcommands(cmdset)
        cmdset.on_registered()
    except Exception:
        cmdset.on_unregister()
        for attrib in installed_attributes:
            delattr(self, attrib)
        if cmdset in self._installed_command_sets:
            self._installed_command_sets.remove(cmdset)
        if cmdset in self._cmd_to_command_sets.values():
            self._cmd_to_command_sets = {key: val for key, val in self._cmd_to_command_sets.items() if val is not cmdset}
        cmdset.on_unregistered()
        raise

def unregister_command_set(self, cmdset: CommandSet[Any]) -> None:
    """Uninstalls a CommandSet and unloads all associated commands.

    :param cmdset: CommandSet to uninstall
    """
    if cmdset in self._installed_command_sets:
        self._check_uninstallable(cmdset)
        cmdset.on_unregister()
        self._unregister_subcommands(cmdset)

        methods: list[tuple[str, Callable[..., Any]]] = inspect.getmembers(
            cmdset,
            predicate=lambda meth: (  # type: ignore[arg-type]
                isinstance(meth, Callable)  # type: ignore[arg-type]
                and hasattr(meth, "__name__")
                and meth.__name__.startswith(COMMAND_FUNC_PREFIX)
            ),
        )

        for cmd_func_name, command_method in methods:
            command = cmd_func_name[len(COMMAND_FUNC_PREFIX) :]

            # Enable the command before uninstalling it to make sure we remove both
            # the real functions and the ones used by the DisabledCommand object.
            if command in self.disabled_commands:
                self.enable_command(command)

            if command in self._cmd_to_command_sets:
                del self._cmd_to_command_sets[command]

            # Only remove the parser if this is the actual
            # command since command synonyms don't own it.
            if cmd_func_name == command_method.__name__:
                self.command_parsers.remove(command_method)

            if hasattr(self, COMPLETER_FUNC_PREFIX + command):
                delattr(self, COMPLETER_FUNC_PREFIX + command)
            if hasattr(self, HELP_FUNC_PREFIX + command):
                delattr(self, HELP_FUNC_PREFIX + command)

            delattr(self, cmd_func_name)

        cmdset.on_unregistered()
        self._installed_command_sets.remove(cmdset)

def get_root_parser_and_subcmd_path(self, command: str) -> tuple[Cmd2ArgumentParser, list[str]]:
    """Tokenize a command string and resolve the associated root parser and relative subcommand path.

    This helper handles the initial resolution of a command string (e.g., 'foo bar baz') by
    identifying 'foo' as the root command, retrieving its associated parser, and returning
    any remaining tokens (['bar', 'baz']) as a path relative to that parser for further traversal.

    :param command: full space-delimited command path leading to a parser (e.g. 'foo' or 'foo bar')
    :return: a tuple containing the Cmd2ArgumentParser for the root command and a list of
             strings representing the relative path to the desired hosting parser.
    :raises ValueError: if the command is empty, the root command is not found, or
                        the root command does not use an argparse parser.
    """
    tokens = command.split()
    if not tokens:
        raise ValueError("Command path cannot be empty")

    root_command = tokens[0]
    subcommand_path = tokens[1:]

    # Search for the base command function and verify it has a parser defined
    command_func = self.get_command_func(root_command)
    if command_func is None:
        raise ValueError(f"Root command '{root_command}' does not exist")

    root_parser = self.command_parsers.get(command_func)
    if root_parser is None:
        raise ValueError(f"Command '{root_command}' does not use argparse")

    return root_parser, subcommand_path

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

    :param record: SubcommandRecord object describing the subcommand
    :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
    """
    root_parser, subcommand_path = self.get_root_parser_and_subcmd_path(record.command)
    root_parser.attach_subcommand(record, subcommand_path=subcommand_path)

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

    :param command: full command path (space-delimited) leading to the parser hosting the
                    subcommand to be detached (e.g. 'foo bar')
    :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
    """
    root_parser, subcommand_path = self.get_root_parser_and_subcmd_path(command)
    return root_parser.detach_subcommand(subcommand_path, subcommand)

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

    :param command: full command path (space-delimited) leading to the parser hosting the
                    subcommands to be detached (e.g. 'foo bar')
    :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
    """
    root_parser, subcommand_path = self.get_root_parser_and_subcmd_path(command)
    return root_parser.detach_all_subcommands(subcommand_path)

def add_settable(self, settable: Settable) -> None:
    """Add a settable parameter to ``self.settables``.

    :param settable: Settable object being added
    """
    if not self.always_prefix_settables and settable.name in self.settables and settable.name not in self._settables:
        raise KeyError(f"Duplicate settable: {settable.name}")
    self._settables[settable.name] = settable

def remove_settable(self, name: str) -> None:
    """Remove a settable parameter from ``self.settables``.

    :param name: name of the settable being removed
    :raises KeyError: if the Settable matches this name
    """
    try:
        del self._settables[name]
    except KeyError as exc:
        raise KeyError(name + " is not a settable parameter") from exc

def build_settables(self) -> None:
    """Create the dictionary of user-settable parameters."""

    def get_allow_style_choices(_cli_self: Cmd) -> Choices:
        """Complete allow_style values."""
        styles = [val.name.lower() for val in ru.AllowStyle]
        return Choices.from_values(styles)

    def allow_style_type(value: str) -> ru.AllowStyle:
        """Convert a string value into an ru.AllowStyle."""
        try:
            return ru.AllowStyle[value.upper()]
        except KeyError as ex:
            raise ValueError(
                f"must be {ru.AllowStyle.ALWAYS}, {ru.AllowStyle.NEVER}, or {ru.AllowStyle.TERMINAL} (case-insensitive)"
            ) from ex

    settable_description = Text.assemble(
        "Allow styled text in output (Options: ",
        (str(ru.AllowStyle.ALWAYS), Style(bold=True)),
        ", ",
        (str(ru.AllowStyle.NEVER), Style(bold=True)),
        ", ",
        (str(ru.AllowStyle.TERMINAL), Style(bold=True)),
        ")",
    )
    self.add_settable(
        Settable(
            "allow_style",
            allow_style_type,
            ru.rich_text_to_string(settable_description),
            self,
            choices_provider=get_allow_style_choices,
        )
    )
    self.add_settable(Settable("debug", bool, "Show full traceback on exception", self))
    self.add_settable(Settable("echo", bool, "Echo command issued into output", self))

    editor_description = Text.assemble(
        "Program used by ",
        ("'edit'", Style(bold=True)),
        " command",
    )
    self.add_settable(
        Settable(
            "editor",
            str,
            ru.rich_text_to_string(editor_description),
            self,
        )
    )

    self.add_settable(
        Settable(
            "max_completion_table_items",
            int,
            "Max results allowed to display a table",
            self,
        )
    )
    self.add_settable(
        Settable(
            "max_column_completion_results",
            int,
            "Max results to display in a single column",
            self,
        )
    )
    self.add_settable(Settable("quiet", bool, "Don't print nonessential feedback", self))
    self.add_settable(Settable("scripts_add_to_history", bool, "Scripts and pyscripts add commands to history", self))
    self.add_settable(Settable("timing", bool, "Report execution times", self))
    self.add_settable(Settable("traceback_show_locals", bool, "Display local variables in tracebacks", self))

    traceback_width_description = Text.assemble(
        "Maximum display width for tracebacks. Set to ",
        ("None", Style(bold=True)),
        " (case-insensitive) to fill entire terminal width.",
    )
    self.add_settable(
        Settable(
            "traceback_width",
            utils.optional_int,
            ru.rich_text_to_string(traceback_width_description),
            self,
        )
    )

def print_to(
    self,
    file: IO[str],
    *objects: Any,
    sep: str = " ",
    end: str = "\n",
    style: StyleType | None = None,
    soft_wrap: bool = True,
    justify: JustifyMethod | None = None,
    emoji: bool = False,
    markup: bool = False,
    highlight: bool = False,
    rich_print_kwargs: Mapping[str, Any] | None = None,
    **kwargs: Any,  # noqa: ARG002
) -> None:
    """Print objects to a given file stream.

    This method is configured for general-purpose printing. By default, it enables
    soft wrap and disables Rich's automatic detection for markup, emoji, and highlighting.
    These defaults can be overridden by passing explicit keyword arguments.

    :param file: file stream being written to
    :param objects: objects to print
    :param sep: string to write between printed text. Defaults to " ".
    :param end: string to write at end of printed text. Defaults to a newline.
    :param style: optional style to apply to output
    :param soft_wrap: Enable soft wrap mode. Defaults to True.
                      If True, text that doesn't fit will run on to the following line,
                      just like the built-in print() function. This is useful for raw text
                      and logs.
                      If False, Rich wraps text to fit the terminal width.
                      Set this to False when printing structured Renderables like
                      Tables, Panels, or Columns to ensure they render as expected.
                      For example, when soft_wrap is True Panels truncate text
                      which is wider than the terminal.
    :param justify: justify method ("left", "center", "right", "full"). Defaults to None.
    :param emoji: If True, Rich will replace emoji codes (e.g., :smiley:) with their
                  corresponding Unicode characters. Defaults to False.
    :param markup: If True, Rich will interpret strings with tags (e.g., [bold]hello[/bold])
                   as styled output. Defaults to False.
    :param highlight: If True, Rich will automatically apply highlighting to elements within
                      strings, such as common Python data types like numbers, booleans, or None.
                      This is particularly useful when pretty printing objects like lists and
                      dictionaries to display them in color. Defaults to False.
    :param rich_print_kwargs: optional additional keyword arguments to pass to console.print().
    :param kwargs: Arbitrary keyword arguments. This allows subclasses to extend the signature of this
                   method and still call `super()` without encountering unexpected keyword argument errors.
                   These arguments are not passed to console.print().

    See the Rich documentation for more details on emoji codes, markup tags, and highlighting.
    """
    try:
        self._get_core_print_console(
            file=file,
            emoji=emoji,
            markup=markup,
            highlight=highlight,
        ).print(
            *objects,
            sep=sep,
            end=end,
            style=style,
            justify=justify,
            soft_wrap=soft_wrap,
            **(rich_print_kwargs if rich_print_kwargs is not None else {}),
        )
    except BrokenPipeError:
        # This occurs if a command's output is being piped to another
        # process which closes the pipe before the command is finished
        # writing. If you would like your application to print a
        # warning message, then set the broken_pipe_warning attribute
        # to the message you want printed.
        if self.broken_pipe_warning and file != sys.stderr:
            Cmd2GeneralConsole(file=sys.stderr).print(self.broken_pipe_warning)