Class Cmd2ArgumentParser

cmd2/argparse_utils.py:564–928

Custom ArgumentParser class that improves error and help output.

class Cmd2ArgumentParser(argparse.ArgumentParser):
    """Custom ArgumentParser class that improves error and help output."""

    # Thread-local storage shared by all parser instances (including subparsers)
    _thread_locals: ClassVar[_ParserThreadLocals] = _ParserThreadLocals()

    @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 __init__(
        self,
        prog: str | None = None,
        usage: str | None = None,
        description: HelpContent | None = None,
        epilog: HelpContent | None = None,
        parents: Sequence[argparse.ArgumentParser] = (),
        formatter_class: type[Cmd2HelpFormatter] = Cmd2HelpFormatter,
        prefix_chars: str = "-",
        fromfile_prefix_chars: str | None = None,
        argument_default: str | None = None,
        conflict_handler: str = "error",
        add_help: bool = True,
        allow_abbrev: bool = True,
        exit_on_error: bool = True,
        suggest_on_error: bool = False,
        color: bool = False,
        *,
        ap_completer_type: type["ArgparseCompleter"] | None = None,
    ) -> None:
        """Initialize the Cmd2ArgumentParser instance.

        :param ap_completer_type: optional parameter which specifies a subclass of ArgparseCompleter for custom completion
                                  behavior on this parser. If this is None or not present, then cmd2 will use
                                  argparse_completer.DEFAULT_AP_COMPLETER when completing this parser's arguments
        """
        kwargs: dict[str, bool] = {}
        if sys.version_info >= (3, 14):
            # Python >= 3.14 so pass new arguments to parent argparse.ArgumentParser class
            kwargs = {
                "suggest_on_error": suggest_on_error,
                "color": color,
            }

        super().__init__(
            prog=prog,