Initialization

def __init__(
    self,
    completekey: str | None = None,
    stdin: TextIO | None = None,
    stdout: TextIO | None = None,
    *,
    allow_cli_args: bool = True,
    allow_clipboard: bool = True,
    allow_redirection: bool = True,
    auto_load_commands: bool = False,
    auto_suggest: bool = True,
    bottom_toolbar: bool = False,
    command_sets: Iterable[CommandSet[Any]] | None = None,
    include_ipy: bool = False,
    include_py: bool = False,
    intro: RenderableType = "",
    multiline_commands: Iterable[str] | None = None,
    persistent_history_file: str = "",
    persistent_history_length: int = 1000,
    shortcuts: Mapping[str, str] | None = None,
    silence_startup_script: bool = False,
    startup_script: str = "",
    suggest_similar_command: bool = False,
    terminators: Iterable[str] | None = None,
) -> None:
    """Easy but powerful framework for writing line-oriented command interpreters, extends Python's cmd package.

    :param completekey: name of a completion key, default to 'tab'. (If None or an empty string, 'tab' is used)
    :param stdin: alternate input file object, if not specified, sys.stdin is used
    :param stdout: alternate output file object, if not specified, sys.stdout is used
    :param allow_cli_args: if ``True``, then [cmd2.Cmd.__init__][] will process command
                           line arguments as either commands to be run. This should be
                           set to ``False`` if your application parses its own command line
                           arguments.
    :param allow_clipboard: If False, cmd2 will disable clipboard interactions
    :param allow_redirection: If ``False``, prevent output redirection and piping to shell
                              commands. This parameter prevents redirection and piping, but
                              does not alter parsing behavior. A user can still type
                              redirection and piping tokens, and they will be parsed as such
                              but they won't do anything.
    :param auto_load_commands: If True, cmd2 will check for all subclasses of `CommandSet`
                               that are currently loaded by Python and automatically
                               instantiate and register all commands. If False, CommandSets
                               must be manually installed with `register_command_set`.
    :param auto_suggest: If True, cmd2 will provide fish shell style auto-suggestions
                        based on history. User can press right-arrow key to accept the
                        provided suggestion.
    :param bottom_toolbar: if ``True``, then a bottom toolbar will be displayed.
    :param command_sets: Provide CommandSet instances to load during cmd2 initialization.
                         This allows CommandSets with custom constructor parameters to be
                         loaded.  This also allows the a set of CommandSets to be provided
                         when `auto_load_commands` is set to False
    :param include_ipy: should the "ipy" command be included for an embedded IPython shell
    :param include_py: should the "py" command be included for an embedded Python shell
    :param intro: introduction to display at startup
    :param multiline_commands: Iterable of commands allowed to accept multi-line input
    :param persistent_history_file: file path to load a persistent cmd2 command history from
    :param persistent_history_length: max number of history items to write
                                      to the persistent history file
    :param shortcuts: Mapping containing shortcuts for commands. If not supplied,
                      then defaults to constants.DEFAULT_SHORTCUTS. If you do not want
                      any shortcuts, pass None and an empty dictionary will be created.
    :param silence_startup_script: if ``True``, then the startup script's output will be
                                   suppressed. Anything written to stderr will still display.
    :param startup_script: file path to a script to execute at startup
    :param suggest_similar_command: if ``True``, then when a command is not found,
                                    [cmd2.Cmd][] will look for similar commands and suggest them.
    :param terminators: Iterable of characters that terminate a command. These are mainly
                        intended for terminating multiline commands, but will also
                        terminate single-line commands. If not supplied, the default
                        is a semicolon. If your app only contains single-line commands
                        and you want terminators to be treated as literals by the parser,
                        then set this to None.
    """
    # Check if py or ipy need to be disabled in this instance
    if not include_py:
        setattr(self, "do_py", None)  # noqa: B010
    if not include_ipy:
        setattr(self, "do_ipy", None)  # noqa: B010

    # initialize plugin system
    # needs to be done before we most of the other stuff below
    self._initialize_plugin_system()

    # Configure a few defaults
    self.prompt: str = self.DEFAULT_PROMPT
    self.intro = intro

    if not completekey:
        completekey = self.DEFAULT_COMPLETEKEY

    # What to use for standard input
    if stdin is not None:
        self.stdin = stdin
    else:
        self.stdin = sys.stdin

    # Standard output stream. The interactive UI remains attached to this initial
    # stream even when self.stdout is temporarily swapped during command output
    # redirection.
    if stdout is not None:
        self.stdout = stdout
    else:
        self.stdout = sys.stdout

    # Attributes which should NOT be dynamically settable via the set command at runtime
    self.allow_redirection = allow_redirection  # Security setting to prevent redirection of stdout

    # If True, cmd2 treats redirected input (pipes/files) as an interactive session.
    # It will display the prompt before reading each line to synchronize with
    # automation tools (like Pexpect) and will skip echoing the input to prevent
    # duplicate prompts in the output.
    self.interactive_pipe = False

    # Attributes which ARE dynamically settable via the set command at runtime
    self.debug = False
    self.echo = False
    self.editor = self.DEFAULT_EDITOR
    self.quiet = False  # Do not suppress nonessential output
    self.scripts_add_to_history = True  # Scripts and pyscripts add commands to history
    self.timing = False  # Prints elapsed time for each command

    # Default settings for Rich tracebacks created by format_exception().
    # This dictionary can contain any parameter accepted by the
    # rich.traceback.Traceback class. You can modify it to adjust
    # the detail and layout of tracebacks.
    self.traceback_kwargs: dict[str, Any] = {
        "width": 100,
        "code_width": None,  # Show all code characters
        "show_locals": False,
        "max_frames": 100,
        "word_wrap": True,  # Wrap long lines of code instead of truncate
        "indent_guides": True,
    }

    # Cached Rich consoles used by core print methods.
    self._console_cache = _ConsoleCache()

    # The maximum number of items to display in a completion table. If the number of completion
    # suggestions exceeds this number, then no table will appear.
    self.max_completion_table_items: int = 50

    # The maximum number of completion results to display in a single column (CompleteStyle.COLUMN).
    # If the number of results exceeds this, CompleteStyle.MULTI_COLUMN will be used.
    self.max_column_completion_results: int = 7

    # A dictionary mapping settable names to their Settable instance
    self._settables: dict[str, Settable] = {}
    self._always_prefix_settables: bool = False

    # CommandSet containers
    self._installed_command_sets: set[CommandSet[Any]] = set()
    self._cmd_to_command_sets: dict[str, CommandSet[Any]] = {}

    self.build_settables()

    # Use as prompt for multiline commands on the 2nd+ line of input
    self.continuation_prompt: str = "> "

    # Allow access to your application in embedded Python shells and pyscripts via self
    self.self_in_py = False

    # Commands to exclude from the help menu and completion
    self.hidden_commands = ["_eof", "_relative_run_script"]

    # Initialize history from a persistent history file (if present)
    self.persistent_history_file = ""
    self._persistent_history_length = persistent_history_length
    self._initialize_history(persistent_history_file)

    # Create the main PromptSession
    self.bottom_toolbar = bottom_toolbar
    self.main_session = self._create_main_session(auto_suggest, completekey)

    # The session currently holding focus (either the main REPL or a command's
    # custom prompt). Completion and UI logic should reference this variable
    # to ensure they modify the correct session state.
    self.active_session = self.main_session

    # Commands to exclude from the history command
    self.exclude_from_history = ["_eof", "history"]

    # Dictionary of macro names and their values
    self.macros: dict[str, Macro] = {}

    # Keeps track of typed command history in the Python shell
    self._py_history: list[str] = []

    # The name by which Python environments refer to the PyBridge to call app commands
    self.py_bridge_name = "app"

    # Defines app-specific variables/functions available in Python shells and pyscripts
    self.py_locals: dict[str, Any] = {}

    # True if running inside a Python shell or pyscript, False otherwise
    self._in_py = False

    self.statement_parser: StatementParser = StatementParser(
        terminators=terminators, multiline_commands=multiline_commands, shortcuts=shortcuts
    )

    # Stores results from the last command run to enable usage of results in Python shells and pyscripts
    self.last_result: Any = None

    # Used by run_script command to store current script dir as a LIFO queue to support _relative_run_script command
    self._script_dir: list[str] = []

    # Context manager used to protect critical sections in the main thread from stopping due to a KeyboardInterrupt
    self.sigint_protection: utils.ContextFlag = utils.ContextFlag()

    # If the current command created a process to pipe to, then this will be a ProcReader object.
    # Otherwise it will be None. It's used to know when a pipe process can be killed and/or waited upon.
    self._cur_pipe_proc_reader: utils.ProcReader | None = None

    # Used to keep track of whether we are redirecting or piping output
    self._redirecting = False

    # Set text which prints right before all of the help tables are listed.
    self.doc_leader = ""

    # The error that prints when no help information can be found
    self.help_error = "No help on {}"

    # The error that prints when a non-existent command is run
    self.default_error = "{} is not a recognized command, alias, or macro."

    # If non-empty, this string will be displayed if a broken pipe error occurs
    self.broken_pipe_warning = ""

    # Commands that will run at the beginning of the command loop
    self._startup_commands: list[str] = []

    # Store initial termios settings to restore after each command.
    # This is a faster way of accomplishing what "stty sane" does.
    self._initial_termios_settings = None
    if not sys.platform.startswith("win") and self.stdin.isatty():
        try:
            import io
            import termios

            self._initial_termios_settings = termios.tcgetattr(self.stdin.fileno())
        except (ImportError, io.UnsupportedOperation, termios.error):
            # This can happen if termios isn't available or stdin is a pseudo-TTY
            self._initial_termios_settings = None

    # If a startup script is provided and exists, then execute it in the startup commands
    if startup_script:
        startup_script = os.path.abspath(os.path.expanduser(startup_script))
        if os.path.exists(startup_script):
            script_cmd = f"run_script {su.quote(startup_script)}"
            if silence_startup_script:
                script_cmd += f" {constants.REDIRECTION_OVERWRITE} {os.devnull}"
            self._startup_commands.append(script_cmd)

    # Check for command line args
    if allow_cli_args:
        parser = argparse_utils.DEFAULT_ARGUMENT_PARSER()
        _callopts, callargs = parser.parse_known_args()

        # If commands were supplied at invocation, then add them to the command queue
        if callargs:
            self._startup_commands.extend(callargs)

    # Set the pager(s) for use when displaying output using a pager
    if sys.platform.startswith("win"):
        self.pager = self.pager_chop = "more"
    else:
        # Here is the meaning of the various flags we are using with the less command:
        # -S causes lines longer than the screen width to be chopped (truncated) rather than wrapped
        # -R causes ANSI "style" escape sequences to be output in raw form (i.e. colors are displayed)
        # -X disables sending the termcap initialization and deinitialization strings to the terminal
        # -F causes less to automatically exit if the entire file can be displayed on the first screen
        self.pager = "less -RXF"
        self.pager_chop = "less -SRXF"

    # This boolean flag stores whether cmd2 will allow clipboard related features
    self.allow_clipboard = allow_clipboard

    # This determines the value returned by cmdloop() when exiting the application
    self.exit_code = 0

    # Commands disabled during specific application states
    # Key: Command name | Value: DisabledCommand object
    # NOTE: Use disable_command() and enable_command() to modify this dictionary.
    self.disabled_commands: dict[str, DisabledCommand] = {}

    # Categories of commands to be disabled
    # Key: Category name | Value: Message to display
    # NOTE: Use disable_category() and enable_category() to modify this dictionary.
    self.disabled_categories: dict[str, str] = {}

    # Command parsers for this Cmd instance.
    self.command_parsers: CommandParsers = CommandParsers(self)

    # Members related to printing asynchronous alerts
    self._alert_queue: deque[AsyncAlert] = deque()
    self._alert_condition = threading.Condition()
    self._alert_allowed = False
    self._alert_shutdown = False
    self._alert_thread: threading.Thread | None = None
    self._alert_prompt_timestamp: float = 0.0  # Uses time.monotonic()

    # Add functions decorated to be subcommands
    self._register_subcommands(self)

    ############################################################################################################
    # The following code block loads CommandSets, verifies command names, and registers subcommands.
    # This block should appear after all attributes have been created since the registration code
    # depends on them and it's possible a module's on_register() method may need to access some.
    ############################################################################################################
    # Load modular commands
    if command_sets:
        for command_set in command_sets:
            self.register_command_set(command_set)

    if auto_load_commands:
        self._autoload_commands()

    # Verify commands don't have invalid names (like starting with a shortcut)
    for cur_cmd in self.get_all_commands():
        valid, errmsg = self.statement_parser.is_valid_command(cur_cmd)
        if not valid:
            raise ValueError(f"Invalid command name '{cur_cmd}': {errmsg}")

    self.suggest_similar_command = suggest_similar_command
    self.default_suggestion_message = "Did you mean {}?"

    # the current command being executed
    self.current_command: Statement | None = None