"""Variant on standard library's cmd with extra features.

To use, simply import cmd2.Cmd instead of cmd.Cmd; use precisely as though you

were using the standard library's cmd, while enjoying the extra features.

Searchable command history (commands: "history")

Run commands from file, save to file, edit commands in file

Multi-line commands

Special-character shortcut commands (beyond cmd's "?" and "!")

Settable environment parameters

Parsing commands with `argparse` argument parsers (flags)

Redirection to file or paste buffer (clipboard) with > or >>

Easy transcript-based testing of applications (see examples/transcript_example.py)

Bash-style ``select`` available

Note, if self.stdout is different than sys.stdout, then redirection with > and |

will only work if `self.poutput()` is used in place of `print`.

- Catherine Devlin, Jan 03 2008 - catherinedevlin.blogspot.com

Git repository on GitHub at https://github.com/python-cmd2/cmd2

"""

# This module has many imports, quite a few of which are only

# infrequently utilized. To reduce the initial overhead of

# import this module, many of these imports are lazy-loaded

# i.e. we only import the module when we use it.

import argparse

import cmd

import contextlib

import copy

import functools

import glob

import inspect

import os

import pydoc

import re

import sys

import tempfile

import threading

from code import InteractiveConsole

from collections import (

OrderedDict,

namedtuple,

)

from collections.abc import (

Callable,

Iterable,

Mapping,

)

from types import (

FrameType,

ModuleType,

)

from typing import (

IO,

TYPE_CHECKING,

Any,

ClassVar,

TextIO,

TypeVar,

Union,

cast,

)

import rich.box

from rich.console import Group

from rich.highlighter import ReprHighlighter

from rich.rule import Rule

from rich.style import Style, StyleType

from rich.table import (

Column,

Table,

)

from rich.text import Text

from rich.traceback import Traceback

from . import (

argparse_completer,

argparse_custom,

constants,

plugin,

utils,

)

from . import rich_utils as ru

from . import string_utils as su

from .argparse_custom import (

ChoicesProviderFunc,

Cmd2ArgumentParser,

CompleterFunc,

CompletionItem,

)

from .clipboard import (

get_paste_buffer,

write_to_paste_buffer,

)

from .command_definition import (

CommandFunc,

CommandSet,

)

from .constants import (

CLASS_ATTR_DEFAULT_HELP_CATEGORY,

COMMAND_FUNC_PREFIX,

COMPLETER_FUNC_PREFIX,

HELP_FUNC_PREFIX,

)

from .decorators import (

CommandParent,

as_subcommand_to,

with_argparser,

)

from .exceptions import (

Cmd2ShlexError,

CommandSetRegistrationError,

CompletionError,

EmbeddedConsoleExit,

EmptyStatement,

PassThroughException,

RedirectionError,

SkipPostcommandHooks,

)

from .history import (

History,

HistoryItem,

single_line_format,

)

from .parsing import (

Macro,

MacroArg,

Statement,

StatementParser,

shlex_split,

)

from .rich_utils import (

Cmd2ExceptionConsole,

Cmd2GeneralConsole,

RichPrintKwargs,

)

from .styles import Cmd2Style

# NOTE: When using gnureadline with Python 3.13, start_ipython needs to be imported before any readline-related stuff

with contextlib.suppress(ImportError):

from IPython import start_ipython

from .rl_utils import (

RlType,

rl_escape_prompt,

rl_get_display_prompt,

rl_get_point,

rl_get_prompt,

rl_in_search_mode,

rl_set_prompt,

rl_type,

rl_warning,

vt100_support,

)

from .utils import (

Settable,

get_defining_class,

get_types,

strip_doc_annotations,

suggest_similar,

)

# Set up readline

if rl_type == RlType.NONE: # pragma: no cover

Cmd2GeneralConsole(sys.stderr).print(rl_warning, style=Cmd2Style.WARNING)

else:

from .rl_utils import (

readline,

rl_force_redisplay,

)

# Used by rlcompleter in Python console loaded by py command

orig_rl_delims = readline.get_completer_delims()

if rl_type == RlType.PYREADLINE:

# Save the original pyreadline3 display completion function since we need to override it and restore it

orig_pyreadline_display = readline.rl.mode._display_completions

elif rl_type == RlType.GNU:

# Get the readline lib so we can make changes to it

import ctypes

from .rl_utils import (

readline_lib,

)

rl_basic_quote_characters = ctypes.c_char_p.in_dll(readline_lib, "rl_basic_quote_characters")

orig_rl_basic_quotes = cast(bytes, ctypes.cast(rl_basic_quote_characters, ctypes.c_void_p).value)

class _SavedReadlineSettings:

"""readline settings that are backed up when switching between readline environments."""

def __init__(self) -> None:

self.completer = None

self.delims = ''

self.basic_quotes: bytes | None = None

class _SavedCmd2Env:

"""cmd2 environment settings that are backed up when entering an interactive Python shell."""

def __init__(self) -> None:

self.readline_settings = _SavedReadlineSettings()

self.readline_module: ModuleType | None = None

self.history: list[str] = []

# Contains data about a disabled command which is used to restore its original functions when the command is enabled

DisabledCommand = namedtuple('DisabledCommand', ['command_function', 'help_function', 'completer_function']) # noqa: PYI024

if TYPE_CHECKING: # pragma: no cover

StaticArgParseBuilder = staticmethod[[], argparse.ArgumentParser]

ClassArgParseBuilder = classmethod['Cmd' | CommandSet, [], argparse.ArgumentParser]

else:

StaticArgParseBuilder = staticmethod

ClassArgParseBuilder = classmethod

class _CommandParsers:

"""Create and store all command method argument parsers for a given Cmd instance.

Parser creation and retrieval are accomplished through the get() method.

"""

def __init__(self, cmd: 'Cmd') -> None:

self._cmd = cmd

# Keyed by the fully qualified method names. This is more reliable than

# the methods themselves, since wrapping a method will change its address.

self._parsers: dict[str, argparse.ArgumentParser] = {}

@staticmethod

def _fully_qualified_name(command_method: CommandFunc) -> str:

"""Return the fully qualified name of a method or None if a method wasn't passed in."""

try:

return f"{command_method.__module__}.{command_method.__qualname__}"

except AttributeError:

return ""

def __contains__(self, command_method: CommandFunc) -> bool:

"""Return whether a given method's parser is in self.

If the parser does not yet exist, it will be created if applicable.

This is basically for checking if a method is argarse-based.

"""

parser = self.get(command_method)

return bool(parser)

def get(self, command_method: CommandFunc) -> argparse.ArgumentParser | None:

"""Return a given method's parser or None if the method is not argparse-based.

If the parser does not yet exist, it will be created.

"""

full_method_name = self._fully_qualified_name(command_method)

if not full_method_name:

return None

if full_method_name not in self._parsers:

if not command_method.__name__.startswith(COMMAND_FUNC_PREFIX):

return None

command = command_method.__name__[len(COMMAND_FUNC_PREFIX) :]

parser_builder = getattr(command_method, constants.CMD_ATTR_ARGPARSER, None)

if parser_builder is None:

return None

parent = self._cmd.find_commandset_for_command(command) or self._cmd

parser = self._cmd._build_parser(parent, parser_builder, command)

# If the description has not been set, then use the method docstring if one exists

if parser.description is None and command_method.__doc__:

parser.description = strip_doc_annotations(command_method.__doc__)

self._parsers[full_method_name] = parser

return self._parsers.get(full_method_name)

def remove(self, command_method: CommandFunc) -> None:

"""Remove a given method's parser if it exists."""

full_method_name = self._fully_qualified_name(command_method)

if full_method_name in self._parsers:

del self._parsers[full_method_name]

class Cmd(cmd.Cmd):

"""An easy but powerful framework for writing line-oriented command interpreters.

Extends the Python Standard Library's cmd package by adding a lot of useful features

to the out of the box configuration.

Line-oriented command interpreters are often useful for test harnesses, internal tools, and rapid prototypes.

"""

DEFAULT_EDITOR = utils.find_editor()

# Sorting keys for strings

ALPHABETICAL_SORT_KEY = su.norm_fold

NATURAL_SORT_KEY = utils.natural_keys

# List for storing transcript test file names

testfiles: ClassVar[list[str]] = []

def __init__(

self,

completekey: str = 'tab',

stdin: TextIO | None = None,

stdout: TextIO | None = None,

*,

persistent_history_file: str = '',

persistent_history_length: int = 1000,

startup_script: str = '',

silence_startup_script: bool = False,

include_py: bool = False,

include_ipy: bool = False,

allow_cli_args: bool = True,

transcript_files: list[str] | None = None,

allow_redirection: bool = True,

multiline_commands: list[str] | None = None,

terminators: list[str] | None = None,

shortcuts: dict[str, str] | None = None,

command_sets: Iterable[CommandSet] | None = None,

auto_load_commands: bool = True,

allow_clipboard: bool = True,

suggest_similar_command: bool = False,

) -> None:

"""Easy but powerful framework for writing line-oriented command interpreters, extends Python's cmd package.

:param completekey: readline name of a completion key, default to Tab

: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 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 startup_script: file path to a script to execute at startup

:param silence_startup_script: if ``True``, then the startup script's output will be

suppressed. Anything written to stderr will still display.

:param include_py: should the "py" command be included for an embedded Python shell

:param include_ipy: should the "ipy" command be included for an embedded IPython shell

:param allow_cli_args: if ``True``, then [cmd2.Cmd.__init__][] will process command

line arguments as either commands to be run or, if ``-t`` or

``--test`` are given, transcript files to run. This should be

set to ``False`` if your application parses its own command line

arguments.

:param transcript_files: pass a list of transcript files to be run on initialization.

This allows running transcript tests when ``allow_cli_args``

is ``False``. If ``allow_cli_args`` is ``True`` this parameter

is ignored.

: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 multiline_commands: list of commands allowed to accept multi-line input

:param terminators: list 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 an empty list.

:param shortcuts: dictionary containing shortcuts for commands. If not supplied,

then defaults to constants.DEFAULT_SHORTCUTS. If you do not want

any shortcuts, pass an empty dictionary.

: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 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 allow_clipboard: If False, cmd2 will disable clipboard interactions

:param suggest_similar_command: If ``True``, ``cmd2`` will attempt to suggest the most

similar command when the user types a command that does

not exist. Default: ``False``.

"""

# 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 call __init__(0)

self._initialize_plugin_system()

# Call super class constructor

super().__init__(completekey=completekey, stdin=stdin, stdout=stdout)

# Attributes which should NOT be dynamically settable via the set command at runtime

self.default_to_shell = False # Attempt to run unrecognized commands as shell commands

self.allow_redirection = allow_redirection # Security setting to prevent redirection of stdout

# Attributes which ARE dynamically settable via the set command at runtime

self.always_show_hint = False

self.debug = False

self.echo = False

self.editor = Cmd.DEFAULT_EDITOR

self.feedback_to_output = False # Do not include nonessentials in >, | output by default (things like timing)

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

# The maximum number of CompletionItems to display during tab completion. If the number of completion

# suggestions exceeds this number, they will be displayed in the typical columnized format and will

# not include the description value of the CompletionItems.

self.max_completion_items: int = 50

# 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] = set()

self._cmd_to_command_sets: dict[str, CommandSet] = {}

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 tab completion

self.hidden_commands = ['eof', '_relative_run_script']

# Initialize history

self.persistent_history_file = ''

self._persistent_history_length = persistent_history_length

self._initialize_history(persistent_history_file)

# 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

# Used to keep track of whether a continuation prompt is being displayed

self._at_continuation_prompt = False

# The multiline command currently being typed which is used to tab complete multiline commands.

self._multiline_in_progress = ''

# Characters used to draw a horizontal rule. Should not be blank.

self.ruler = "─"

# Set text which prints right before all of the help tables are listed.

self.doc_leader = ""

# Set header for table listing documented commands.

self.doc_header = "Documented Commands"

# Set header for table listing help topics not related to a command.

self.misc_header = "Miscellaneous Help Topics"

# Set header for table listing commands that have no help info.

self.undoc_header = "Undocumented Commands"

# If any command has been categorized, then all other documented commands that

# haven't been categorized will display under this section in the help output.

self.default_category = "Uncategorized Commands"

# 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] = []

# 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_OUTPUT} {os.devnull}"

self._startup_commands.append(script_cmd)

# Transcript files to run instead of interactive command loop

self._transcript_files: list[str] | None = None

# Check for command line args

if allow_cli_args:

parser = argparse_custom.DEFAULT_ARGUMENT_PARSER()

parser.add_argument('-t', '--test', action="store_true", help='Test against transcript(s) in FILE (wildcards OK)')

callopts, callargs = parser.parse_known_args()

# If transcript testing was called for, use other arguments as transcript files

if callopts.test:

self._transcript_files = callargs

# If commands were supplied at invocation, then add them to the command queue

elif callargs:

self._startup_commands.extend(callargs)

elif transcript_files:

self._transcript_files = transcript_files

# 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

# This lock should be acquired before doing any asynchronous changes to the terminal to

# ensure the updates to the terminal don't interfere with the input being typed or output

# being printed by a command.

self.terminal_lock = threading.RLock()

# Commands that have been disabled from use. This is to support commands that are only available

# during specific states of the application. This dictionary's keys are the command names and its

# values are DisabledCommand objects.

self.disabled_commands: dict[str, DisabledCommand] = {}

# The default key for sorting string results. Its default value performs a case-insensitive alphabetical sort.

# If natural sorting is preferred, then set this to NATURAL_SORT_KEY.

# cmd2 uses this key for sorting:

# command and category names

# alias, macro, settable, and shortcut names

# tab completion results when self.matches_sorted is False

self.default_sort_key: Callable[[str], str] = Cmd.ALPHABETICAL_SORT_KEY

############################################################################################################

# The following variables are used by tab completion functions. They are reset each time complete() is run

# in _reset_completion_defaults() and it is up to completer functions to set them before returning results.

############################################################################################################

# If True and a single match is returned to complete(), then a space will be appended

# if the match appears at the end of the line

self.allow_appended_space = True

# If True and a single match is returned to complete(), then a closing quote

# will be added if there is an unmatched opening quote

self.allow_closing_quote = True

# An optional hint which prints above tab completion suggestions

self.completion_hint: str = ''

# Normally cmd2 uses readline's formatter to columnize the list of completion suggestions.

# If a custom format is preferred, write the formatted completions to this string. cmd2 will

# then print it instead of the readline format. ANSI style sequences and newlines are supported

# when using this value. Even when using formatted_completions, the full matches must still be returned

# from your completer function. ArgparseCompleter writes its tab completion tables to this string.

self.formatted_completions: str = ''

# Used by complete() for readline tab completion

self.completion_matches: list[str] = []

# Use this list if you need to display tab completion suggestions that are different than the actual text

# of the matches. For instance, if you are completing strings that contain a common delimiter and you only

# want to display the final portion of the matches as the tab completion suggestions. The full matches

# still must be returned from your completer function. For an example, look at path_complete() which

# uses this to show only the basename of paths as the suggestions. delimiter_complete() also populates

# this list. These are ignored if self.formatted_completions is populated.

self.display_matches: list[str] = []

# Used by functions like path_complete() and delimiter_complete() to properly

# quote matches that are completed in a delimited fashion

self.matches_delimited = False

# Set to True before returning matches to complete() in cases where matches have already been sorted.

# If False, then complete() will sort the matches using self.default_sort_key before they are displayed.

# This does not affect self.formatted_completions.

self.matches_sorted: bool = False

# Command parsers for this Cmd instance.

self._command_parsers: _CommandParsers = _CommandParsers(self)

# 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

def find_commandsets(self, commandset_type: type[CommandSet], *, subclass_match: bool = False) -> list[CommandSet]:

"""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 | 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 _autoload_commands(self) -> None:

"""Load modular command definitions."""

# Search for all subclasses of CommandSet, instantiate them if they weren't already provided in the constructor

all_commandset_defs = CommandSet.__subclasses__()

existing_commandset_types = [type(command_set) for command_set in self._installed_command_sets]

def load_commandset_by_type(commandset_types: list[type[CommandSet]]) -> None:

for cmdset_type in commandset_types:

# check if the type has sub-classes. We will only auto-load leaf class types.

subclasses = cmdset_type.__subclasses__()

if subclasses:

load_commandset_by_type(subclasses)

else:

init_sig = inspect.signature(cmdset_type.__init__)

if not (

cmdset_type in existing_commandset_types

or len(init_sig.parameters) != 1

or 'self' not in init_sig.parameters

):

cmdset = cmdset_type()

self.register_command_set(cmdset)

load_commandset_by_type(all_commandset_defs)

def register_command_set(self, cmdset: CommandSet) -> 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: isinstance(meth, Callable) # type: ignore[arg-type]

and hasattr(meth, '__name__')

and meth.__name__.startswith(COMMAND_FUNC_PREFIX),

),

)

default_category = getattr(cmdset, CLASS_ATTR_DEFAULT_HELP_CATEGORY, None)

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 default_category and not hasattr(command_method, constants.CMD_ATTR_HELP_CATEGORY):

utils.categorize(command_method, default_category)

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 _build_parser(

self,

parent: CommandParent,

parser_builder: argparse.ArgumentParser

| Callable[[], argparse.ArgumentParser]

| StaticArgParseBuilder

| ClassArgParseBuilder,

prog: str,

) -> argparse.ArgumentParser:

"""Build argument parser for a command/subcommand.

:param parent: CommandParent object which owns the command using the parser.

When parser_builder is a classmethod, this function passes

parent's class to it.

:param parser_builder: means used to build the parser

:param prog: prog value to set in new parser

:return: new parser

:raises TypeError: if parser_builder is invalid type

"""

if isinstance(parser_builder, staticmethod):

parser = parser_builder.__func__()

elif isinstance(parser_builder, classmethod):

parser = parser_builder.__func__(parent.__class__)

elif callable(parser_builder):

parser = parser_builder()

elif isinstance(parser_builder, argparse.ArgumentParser):

parser = copy.deepcopy(parser_builder)

else:

raise TypeError(f"Invalid type for parser_builder: {type(parser_builder)}")

argparse_custom.set_parser_prog(parser, prog)

return parser

def _install_command_function(self, command_func_name: str, command_method: CommandFunc, context: str = '') -> None:

"""Install a new command function into the CLI.

:param command_func_name: name of command function to add

This points to the command method and may differ from the method's

name if it's being used as a synonym. (e.g. do_exit = do_quit)

:param command_method: the actual command method which runs when the command function is called

:param context: optional info to provide in error message. (e.g. class this function belongs to)

:raises CommandSetRegistrationError: if the command function fails to install

"""

# command_func_name must begin with COMMAND_FUNC_PREFIX to be identified as a command by cmd2.

if not command_func_name.startswith(COMMAND_FUNC_PREFIX):

raise CommandSetRegistrationError(f"{command_func_name} does not begin with '{COMMAND_FUNC_PREFIX}'")

# command_method must start with COMMAND_FUNC_PREFIX for use in self._command_parsers.

if not command_method.__name__.startswith(COMMAND_FUNC_PREFIX):

raise CommandSetRegistrationError(f"{command_method.__name__} does not begin with '{COMMAND_FUNC_PREFIX}'")

command = command_func_name[len(COMMAND_FUNC_PREFIX) :]

# Make sure command function doesn't share name with existing attribute

if hasattr(self, command_func_name):

raise CommandSetRegistrationError(f'Attribute already exists: {command_func_name} ({context})')

# Check if command has an invalid name

valid, errmsg = self.statement_parser.is_valid_command(command)

if not valid:

raise CommandSetRegistrationError(f"Invalid command name '{command}': {errmsg}")

# Check if command shares a name with an alias

if command in self.aliases:

self.pwarning(f"Deleting alias '{command}' because it shares its name with a new command")

del self.aliases[command]

# Check if command shares a name with a macro

if command in self.macros:

self.pwarning(f"Deleting macro '{command}' because it shares its name with a new command")

del self.macros[command]

setattr(self, command_func_name, command_method)

def _install_completer_function(self, cmd_name: str, cmd_completer: CompleterFunc) -> None:

completer_func_name = COMPLETER_FUNC_PREFIX + cmd_name

if hasattr(self, completer_func_name):

raise CommandSetRegistrationError(f'Attribute already exists: {completer_func_name}')

setattr(self, completer_func_name, cmd_completer)

def _install_help_function(self, cmd_name: str, cmd_help: Callable[..., None]) -> None:

help_func_name = HELP_FUNC_PREFIX + cmd_name

if hasattr(self, help_func_name):

raise CommandSetRegistrationError(f'Attribute already exists: {help_func_name}')

setattr(self, help_func_name, cmd_help)

def unregister_command_set(self, cmdset: CommandSet) -> 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: 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 _check_uninstallable(self, cmdset: CommandSet) -> None:

def check_parser_uninstallable(parser: argparse.ArgumentParser) -> None:

for action in parser._actions:

if isinstance(action, argparse._SubParsersAction):

for subparser in action.choices.values():

attached_cmdset = getattr(subparser, constants.PARSER_ATTR_COMMANDSET, None)

if attached_cmdset is not None and attached_cmdset is not cmdset:

raise CommandSetRegistrationError(

'Cannot uninstall CommandSet when another CommandSet depends on it'

)

check_parser_uninstallable(subparser)

break

methods: list[tuple[str, Callable[..., Any]]] = inspect.getmembers(

cmdset,

predicate=lambda meth: 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:

# We only need to check if it's safe to remove the parser if this

# is the actual command since command synonyms don't own it.

if cmd_func_name == command_method.__name__:

command_parser = self._command_parsers.get(command_method)

if command_parser is not None:

check_parser_uninstallable(command_parser)

def _register_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:

"""Register subcommands with their base command.

:param cmdset: CommandSet or cmd2.Cmd subclass containing subcommands

"""

if not (cmdset is self or cmdset in self._installed_command_sets):

raise CommandSetRegistrationError('Cannot register subcommands with an unregistered CommandSet')

# find methods that have the required attributes necessary to be recognized as a sub-command

methods = inspect.getmembers(

cmdset,

predicate=lambda meth: isinstance(meth, Callable) # type: ignore[arg-type]

and hasattr(meth, constants.SUBCMD_ATTR_NAME)

and hasattr(meth, constants.SUBCMD_ATTR_COMMAND)

and hasattr(meth, constants.CMD_ATTR_ARGPARSER),

)

# iterate through all matching methods

for _method_name, method in methods:

subcommand_name: str = getattr(method, constants.SUBCMD_ATTR_NAME)

full_command_name: str = getattr(method, constants.SUBCMD_ATTR_COMMAND)

subcmd_parser_builder = getattr(method, constants.CMD_ATTR_ARGPARSER)

subcommand_valid, errmsg = self.statement_parser.is_valid_command(subcommand_name, is_subcommand=True)

if not subcommand_valid:

raise CommandSetRegistrationError(f'Subcommand {subcommand_name} is not valid: {errmsg}')

command_tokens = full_command_name.split()

command_name = command_tokens[0]

subcommand_names = command_tokens[1:]

# Search for the base command function and verify it has an argparser defined

if command_name in self.disabled_commands:

command_func = self.disabled_commands[command_name].command_function

else:

command_func = self.cmd_func(command_name)

if command_func is None:

raise CommandSetRegistrationError(f"Could not find command '{command_name}' needed by subcommand: {method}")

command_parser = self._command_parsers.get(command_func)

if command_parser is None:

raise CommandSetRegistrationError(

f"Could not find argparser for command '{command_name}' needed by subcommand: {method}"

)

def find_subcommand(action: argparse.ArgumentParser, subcmd_names: list[str]) -> argparse.ArgumentParser:

if not subcmd_names:

return action

cur_subcmd = subcmd_names.pop(0)

for sub_action in action._actions:

if isinstance(sub_action, argparse._SubParsersAction):

for choice_name, choice in sub_action.choices.items():

if choice_name == cur_subcmd:

return find_subcommand(choice, subcmd_names)

break

raise CommandSetRegistrationError(f"Could not find subcommand '{action}'")

target_parser = find_subcommand(command_parser, subcommand_names)

# Create the subcommand parser and configure it

subcmd_parser = self._build_parser(cmdset, subcmd_parser_builder, f'{command_name} {subcommand_name}')

if subcmd_parser.description is None and method.__doc__:

subcmd_parser.description = strip_doc_annotations(method.__doc__)

# Set the subcommand handler

defaults = {constants.NS_ATTR_SUBCMD_HANDLER: method}

subcmd_parser.set_defaults(**defaults)

# Set what instance the handler is bound to

setattr(subcmd_parser, constants.PARSER_ATTR_COMMANDSET, cmdset)