diff --git a/cmd2/__init__.py b/cmd2/__init__.py index 8c07fb808..d96c4a2d6 100644 --- a/cmd2/__init__.py +++ b/cmd2/__init__.py @@ -28,6 +28,7 @@ # Get the current value for argparse_custom.DEFAULT_ARGUMENT_PARSER from .argparse_custom import DEFAULT_ARGUMENT_PARSER from .cmd2 import Cmd +from .command_definition import CommandSet, with_default_category, register_command from .constants import COMMAND_NAME, DEFAULT_SHORTCUTS from .decorators import with_argument_list, with_argparser, with_argparser_and_unknown_args, with_category from .exceptions import Cmd2ArgparseError, SkipPostcommandHooks diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index cdee35232..2215f8188 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -37,6 +37,7 @@ import re import sys import threading +import types from code import InteractiveConsole from collections import namedtuple from contextlib import redirect_stdout @@ -45,6 +46,8 @@ from . import ansi, constants, plugin, utils from .argparse_custom import DEFAULT_ARGUMENT_PARSER, CompletionItem from .clipboard import can_clip, get_paste_buffer, write_to_paste_buffer +from .command_definition import _REGISTERED_COMMANDS, CommandSet, _partial_passthru +from .constants import COMMAND_FUNC_PREFIX, COMPLETER_FUNC_PREFIX, HELP_FUNC_PREFIX from .decorators import with_argparser from .exceptions import Cmd2ShlexError, EmbeddedConsoleExit, EmptyStatement, RedirectionError, SkipPostcommandHooks from .history import History, HistoryItem @@ -130,7 +133,9 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *, startup_script: str = '', use_ipython: bool = False, allow_cli_args: bool = True, transcript_files: Optional[List[str]] = None, allow_redirection: bool = True, multiline_commands: Optional[List[str]] = None, - terminators: Optional[List[str]] = None, shortcuts: Optional[Dict[str, str]] = None) -> None: + terminators: Optional[List[str]] = None, shortcuts: Optional[Dict[str, str]] = None, + command_sets: Optional[Iterable[CommandSet]] = None, + auto_load_commands: bool = True) -> None: """An easy but powerful framework for writing line-oriented command interpreters. Extends Python's cmd package. @@ -200,7 +205,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *, self.max_completion_items = 50 # A dictionary mapping settable names to their Settable instance - self.settables = dict() + self.settables = dict() # type: Dict[str, Settable] self.build_settables() # Use as prompt for multiline commands on the 2nd+ line of input @@ -220,7 +225,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *, self.exclude_from_history = ['eof', 'history'] # Dictionary of macro names and their values - self.macros = dict() + self.macros = dict() # type: Dict[str, Macro] # Keeps track of typed command history in the Python shell self._py_history = [] @@ -238,6 +243,16 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *, multiline_commands=multiline_commands, shortcuts=shortcuts) + # Load modular commands + self._installed_functions = [] # type: List[str] + self._installed_command_sets = [] # type: List[CommandSet] + if command_sets: + for command_set in command_sets: + self.install_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) @@ -249,14 +264,14 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *, self.last_result = None # Used by run_script command to store current script dir as a LIFO queue to support _relative_run_script command - self._script_dir = [] + self._script_dir = [] # type: List[str] # Context manager used to protect critical sections in the main thread from stopping due to a KeyboardInterrupt self.sigint_protection = 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 = None + self._cur_pipe_proc_reader = None # type: Optional[utils.ProcReader] # Used to keep track of whether we are redirecting or piping output self._redirecting = False @@ -280,7 +295,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *, self.broken_pipe_warning = '' # Commands that will run at the beginning of the command loop - self._startup_commands = [] + self._startup_commands = [] # type: List[str] # If a startup script is provided and exists, then execute it in the startup commands if startup_script: @@ -289,7 +304,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *, self._startup_commands.append("run_script {}".format(utils.quote_string(startup_script))) # Transcript files to run instead of interactive command loop - self._transcript_files = None + self._transcript_files = None # type: Optional[List[str]] # Check for command line args if allow_cli_args: @@ -333,7 +348,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *, # 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() + self.disabled_commands = dict() # type: Dict[str, DisabledCommand] # If any command has been categorized, then all other commands that haven't been categorized # will display under this section in the help output. @@ -381,6 +396,193 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *, # If False, then complete() will sort the matches using self.default_sort_key before they are displayed. self.matches_sorted = False + def _autoload_commands(self) -> None: + """ + Load modular command definitions. + :return: None + """ + + # start by loading registered functions as commands + for cmd_name in _REGISTERED_COMMANDS.keys(): + self.install_registered_command(cmd_name) + + # Search for all subclasses of CommandSet, instantiate them if they weren't provided in the constructor + all_commandset_defs = CommandSet.__subclasses__() + existing_commandset_types = [type(command_set) for command_set in self._installed_command_sets] + for cmdset_type in all_commandset_defs: + init_sig = inspect.signature(cmdset_type.__init__) + if cmdset_type in existing_commandset_types or \ + len(init_sig.parameters) != 1 or \ + 'self' not in init_sig.parameters: + continue + cmdset = cmdset_type() + self.install_command_set(cmdset) + + def install_command_set(self, cmdset: CommandSet): + """ + Installs a CommandSet, loading all commands defined in the CommandSet + + :param cmdset: CommandSet to load + :return: None + """ + existing_commandset_types = [type(command_set) for command_set in self._installed_command_sets] + if type(cmdset) in existing_commandset_types: + raise ValueError('CommandSet ' + type(cmdset).__name__ + ' is already installed') + + cmdset.on_register(self) + methods = inspect.getmembers( + cmdset, + predicate=lambda meth: (inspect.ismethod(meth) or isinstance(meth, Callable)) and + meth.__name__.startswith(COMMAND_FUNC_PREFIX)) + + installed_attributes = [] + try: + for method in methods: + command = method[0][len(COMMAND_FUNC_PREFIX):] + command_wrapper = _partial_passthru(method[1], self) + + self.__install_command_function(command, command_wrapper, type(cmdset).__name__) + installed_attributes.append(method[0]) + + completer_func_name = COMPLETER_FUNC_PREFIX + command + cmd_completer = getattr(cmdset, completer_func_name, None) + if cmd_completer is not None: + completer_wrapper = _partial_passthru(cmd_completer, self) + self.__install_completer_function(command, completer_wrapper) + 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: + help_wrapper = _partial_passthru(cmd_help, self) + self.__install_help_function(command, help_wrapper) + installed_attributes.append(help_func_name) + + self._installed_command_sets.append(cmdset) + except Exception: + for attrib in installed_attributes: + delattr(self, attrib) + raise + + def __install_command_function(self, command, command_wrapper, context=''): + cmd_func_name = COMMAND_FUNC_PREFIX + command + + # Make sure command function doesn't share naem with existing attribute + if hasattr(self, cmd_func_name): + raise ValueError('Attribute already exists: {} ({})'.format(cmd_func_name, context)) + + # Check if command has an invalid name + valid, errmsg = self.statement_parser.is_valid_command(command) + if not valid: + raise ValueError("Invalid command name {!r}: {}".format(command, errmsg)) + + # Check if command shares a name with an alias + if command in self.aliases: + self.pwarning("Deleting alias '{}' because it shares its name with a new command".format(command)) + del self.aliases[command] + + # Check if command shares a name with a macro + if command in self.macros: + self.pwarning("Deleting macro '{}' because it shares its name with a new command".format(command)) + del self.macros[command] + + setattr(self, cmd_func_name, command_wrapper) + + def __install_completer_function(self, cmd_name, cmd_completer): + completer_func_name = COMPLETER_FUNC_PREFIX + cmd_name + + if hasattr(self, completer_func_name): + raise ValueError('Attribute already exists: {}'.format(completer_func_name)) + setattr(self, completer_func_name, cmd_completer) + + def __install_help_function(self, cmd_name, cmd_completer): + help_func_name = HELP_FUNC_PREFIX + cmd_name + + if hasattr(self, help_func_name): + raise ValueError('Attribute already exists: {}'.format(help_func_name)) + setattr(self, help_func_name, cmd_completer) + + def uninstall_command_set(self, cmdset: CommandSet): + """ + Uninstalls a CommandSet and unloads all associated commands + :param cmdset: CommandSet to uninstall + """ + if cmdset in self._installed_command_sets: + methods = inspect.getmembers( + cmdset, + predicate=lambda meth: inspect.ismethod(meth) and meth.__name__.startswith(COMMAND_FUNC_PREFIX)) + + for method in methods: + cmd_name = method[0][len(COMMAND_FUNC_PREFIX):] + + delattr(self, COMMAND_FUNC_PREFIX + cmd_name) + + if hasattr(self, COMPLETER_FUNC_PREFIX + cmd_name): + delattr(self, COMPLETER_FUNC_PREFIX + cmd_name) + if hasattr(self, HELP_FUNC_PREFIX + cmd_name): + delattr(self, HELP_FUNC_PREFIX + cmd_name) + + cmdset.on_unregister(self) + self._installed_command_sets.remove(cmdset) + + def install_registered_command(self, cmd_name: str): + cmd_completer = None + cmd_help = None + + if cmd_name not in _REGISTERED_COMMANDS: + raise KeyError('Command ' + cmd_name + ' has not been registered') + + cmd_func = _REGISTERED_COMMANDS[cmd_name] + + module = inspect.getmodule(cmd_func) + + module_funcs = [mf for mf in inspect.getmembers(module) if inspect.isfunction(mf[1])] + for mf in module_funcs: + if mf[0] == COMPLETER_FUNC_PREFIX + cmd_name: + cmd_completer = mf[1] + elif mf[0] == HELP_FUNC_PREFIX + cmd_name: + cmd_help = mf[1] + if cmd_completer is not None and cmd_help is not None: + break + + self.install_command_function(cmd_name, cmd_func, cmd_completer, cmd_help) + + def install_command_function(self, + cmd_name: str, + cmd_func: Callable, + cmd_completer: Optional[Callable], + cmd_help: Optional[Callable]): + """ + Installs a command by passing in functions for the command, completion, and help + + :param cmd_name: name of the command to install + :param cmd_func: function to handle the command + :param cmd_completer: completion function for the command + :param cmd_help: help generator for the command + :return: None + """ + self.__install_command_function(cmd_name, types.MethodType(cmd_func, self)) + + self._installed_functions.append(cmd_name) + if cmd_completer is not None: + self.__install_completer_function(cmd_name, types.MethodType(cmd_completer, self)) + if cmd_help is not None: + self.__install_help_function(cmd_name, types.MethodType(cmd_help, self)) + + def uninstall_command(self, cmd_name: str): + """ + Uninstall an installed command and any associated completer or help functions + :param cmd_name: Command to uninstall + """ + if cmd_name in self._installed_functions: + delattr(self, COMMAND_FUNC_PREFIX + cmd_name) + + if hasattr(self, COMPLETER_FUNC_PREFIX + cmd_name): + delattr(self, COMPLETER_FUNC_PREFIX + cmd_name) + if hasattr(self, HELP_FUNC_PREFIX + cmd_name): + delattr(self, HELP_FUNC_PREFIX + cmd_name) + self._installed_functions.remove(cmd_name) + def add_settable(self, settable: Settable) -> None: """ Convenience method to add a settable parameter to ``self.settables`` @@ -1910,7 +2112,7 @@ def _redirect_output(self, statement: Statement) -> utils.RedirectionSavedState: self._cur_pipe_proc_reader, self._redirecting) # The ProcReader for this command - cmd_pipe_proc_reader = None + cmd_pipe_proc_reader = None # type: Optional[utils.ProcReader] if not self.allow_redirection: # Don't return since we set some state variables at the end of the function @@ -2694,16 +2896,31 @@ def do_help(self, args: argparse.Namespace) -> None: def _help_menu(self, verbose: bool = False) -> None: """Show a list of commands which help can be displayed for""" + cmds_cats, cmds_doc, cmds_undoc, help_topics = self._build_command_info() + + if len(cmds_cats) == 0: + # No categories found, fall back to standard behavior + self.poutput("{}".format(str(self.doc_leader))) + self._print_topics(self.doc_header, cmds_doc, verbose) + else: + # Categories found, Organize all commands by category + self.poutput('{}'.format(str(self.doc_leader))) + self.poutput('{}'.format(str(self.doc_header)), end="\n\n") + for category in sorted(cmds_cats.keys(), key=self.default_sort_key): + self._print_topics(category, cmds_cats[category], verbose) + self._print_topics(self.default_category, cmds_doc, verbose) + + self.print_topics(self.misc_header, help_topics, 15, 80) + self.print_topics(self.undoc_header, cmds_undoc, 15, 80) + + def _build_command_info(self): # Get a sorted list of help topics help_topics = sorted(self.get_help_topics(), key=self.default_sort_key) - # Get a sorted list of visible command names visible_commands = sorted(self.get_visible_commands(), key=self.default_sort_key) - cmds_doc = [] cmds_undoc = [] cmds_cats = {} - for command in visible_commands: func = self.cmd_func(command) has_help_func = False @@ -2724,21 +2941,7 @@ def _help_menu(self, verbose: bool = False) -> None: cmds_doc.append(command) else: cmds_undoc.append(command) - - if len(cmds_cats) == 0: - # No categories found, fall back to standard behavior - self.poutput("{}".format(str(self.doc_leader))) - self._print_topics(self.doc_header, cmds_doc, verbose) - else: - # Categories found, Organize all commands by category - self.poutput('{}'.format(str(self.doc_leader))) - self.poutput('{}'.format(str(self.doc_header)), end="\n\n") - for category in sorted(cmds_cats.keys(), key=self.default_sort_key): - self._print_topics(category, cmds_cats[category], verbose) - self._print_topics(self.default_category, cmds_doc, verbose) - - self.print_topics(self.misc_header, help_topics, 15, 80) - self.print_topics(self.undoc_header, cmds_undoc, 15, 80) + return cmds_cats, cmds_doc, cmds_undoc, help_topics def _print_topics(self, header: str, cmds: List[str], verbose: bool) -> None: """Customized version of print_topics that can switch between verbose or traditional output""" diff --git a/cmd2/command_definition.py b/cmd2/command_definition.py new file mode 100644 index 000000000..d99259694 --- /dev/null +++ b/cmd2/command_definition.py @@ -0,0 +1,129 @@ +# coding=utf-8 +""" +Supports the definition of commands in separate classes to be composed into cmd2.Cmd +""" +import functools +from typing import Callable, Dict, Iterable, Optional, Type + +from .constants import COMMAND_FUNC_PREFIX + +# Allows IDEs to resolve types without impacting imports at runtime, breaking circular dependency issues +try: # pragma: no cover + from typing import TYPE_CHECKING + if TYPE_CHECKING: + import cmd2 + +except ImportError: # pragma: no cover + pass + +_REGISTERED_COMMANDS = {} # type: Dict[str, Callable] +""" +Registered command tuples. (command, ``do_`` function) +""" + + +def _partial_passthru(func: Callable, *args, **kwargs) -> functools.partial: + """ + Constructs a partial function that passes arguments through to the wrapped function. + Must construct a new type every time so that each wrapped function's __doc__ can be copied correctly. + + :param func: wrapped function + :param args: positional arguments + :param kwargs: keyword arguments + :return: partial function that exposes attributes of wrapped function + """ + def __getattr__(self, item): + return getattr(self.func, item) + + def __setattr__(self, key, value): + return setattr(self.func, key, value) + + def __dir__(self) -> Iterable[str]: + return dir(self.func) + + passthru_type = type('PassthruPartial' + func.__name__, + (functools.partial,), + { + '__getattr__': __getattr__, + '__setattr__': __setattr__, + '__dir__': __dir__, + }) + passthru_type.__doc__ = func.__doc__ + return passthru_type(func, *args, **kwargs) + + +def register_command(cmd_func: Callable): + """ + Decorator that allows an arbitrary function to be automatically registered as a command. + If there is a ``help_`` or ``complete_`` function that matches this command, that will also be registered. + + :param cmd_func: Function to register as a cmd2 command + :type cmd_func: Callable[[cmd2.Cmd, Union[Statement, argparse.Namespace]], None] + :return: + """ + assert cmd_func.__name__.startswith(COMMAND_FUNC_PREFIX), 'Command functions must start with `do_`' + + cmd_name = cmd_func.__name__[len(COMMAND_FUNC_PREFIX):] + + if cmd_name not in _REGISTERED_COMMANDS: + _REGISTERED_COMMANDS[cmd_name] = cmd_func + else: + raise KeyError('Command ' + cmd_name + ' is already registered') + return cmd_func + + +def with_default_category(category: str): + """ + Decorator that applies a category to all ``do_*`` command methods in a class that do not already + have a category specified. + + :param category: category to put all uncategorized commands in + :return: decorator function + """ + + def decorate_class(cls: Type[CommandSet]): + from .constants import CMD_ATTR_HELP_CATEGORY + import inspect + from .decorators import with_category + methods = inspect.getmembers( + cls, + predicate=lambda meth: inspect.isfunction(meth) and meth.__name__.startswith(COMMAND_FUNC_PREFIX)) + category_decorator = with_category(category) + for method in methods: + if not hasattr(method[1], CMD_ATTR_HELP_CATEGORY): + setattr(cls, method[0], category_decorator(method[1])) + return cls + return decorate_class + + +class CommandSet(object): + """ + Base class for defining sets of commands to load in cmd2. + + ``with_default_category`` can be used to apply a default category to all commands in the CommandSet. + + ``do_``, ``help_``, and ``complete_`` functions differ only in that they're now required to accept + a reference to ``cmd2.Cmd`` as the first argument after self. + """ + + def __init__(self): + self._cmd = None # type: Optional[cmd2.Cmd] + + def on_register(self, cmd): + """ + Called by cmd2.Cmd when a CommandSet is registered. Subclasses can override this + to perform an initialization requiring access to the Cmd object. + + :param cmd: The cmd2 main application + :type cmd: cmd2.Cmd + """ + self._cmd = cmd + + def on_unregister(self, cmd): + """ + Called by ``cmd2.Cmd`` when a CommandSet is unregistered and removed. + + :param cmd: + :type cmd: cmd2.Cmd + """ + self._cmd = None diff --git a/cmd2/decorators.py b/cmd2/decorators.py index d2fdf9c7e..aad44ac4b 100644 --- a/cmd2/decorators.py +++ b/cmd2/decorators.py @@ -1,7 +1,7 @@ # coding=utf-8 """Decorators for ``cmd2`` commands""" import argparse -from typing import Any, Callable, Dict, List, Optional, Union +from typing import Any, Callable, Dict, List, Optional, Tuple, Union from . import constants from .exceptions import Cmd2ArgparseError @@ -30,6 +30,42 @@ def cat_decorator(func): return func return cat_decorator +########################## +# The _parse_positionals and _swap_args decorators allow for additional positional args to be preserved +# in cmd2 command functions/callables. As long as the 2-ple of arguments we expect to be there can be +# found we can swap out the statement with each decorator's specific parameters +########################## + + +def _parse_positionals(args: Tuple) -> Tuple['cmd2.Cmd', Union[Statement, str]]: + """ + Helper function for cmd2 decorators to inspect the positional arguments until the cmd2.Cmd argument is found + Assumes that we will find cmd2.Cmd followed by the command statement object or string. + :arg args: The positional arguments to inspect + :return: The cmd2.Cmd reference and the command line statement + """ + for pos, arg in enumerate(args): + from cmd2 import Cmd + if isinstance(arg, Cmd) and len(args) > pos: + next_arg = args[pos + 1] + if isinstance(next_arg, (Statement, str)): + return arg, args[pos + 1] + raise TypeError('Expected arguments: cmd: cmd2.Cmd, statement: Union[Statement, str] Not found') + + +def _arg_swap(args: Union[Tuple[Any], List[Any]], search_arg: Any, *replace_arg: Any) -> List[Any]: + """ + Helper function for cmd2 decorators to swap the Statement parameter with one or more decorator-specific parameters + :param args: The original positional arguments + :param search_arg: The argument to search for (usually the Statement) + :param replace_arg: The arguments to substitute in + :return: The new set of arguments to pass to the command function + """ + index = args.index(search_arg) + args_list = list(args) + args_list[index:index + 1] = replace_arg + return args_list + def with_argument_list(*args: List[Callable], preserve_quotes: bool = False) -> Callable[[List], Optional[bool]]: """ @@ -53,20 +89,22 @@ def with_argument_list(*args: List[Callable], preserve_quotes: bool = False) -> def arg_decorator(func: Callable): @functools.wraps(func) - def cmd_wrapper(cmd2_app, statement: Union[Statement, str], **kwargs: Dict[str, Any]) -> Optional[bool]: + def cmd_wrapper(*args, **kwargs: Dict[str, Any]) -> Optional[bool]: """ Command function wrapper which translates command line into an argument list and calls actual command function - :param cmd2_app: CLI instance passed as self parameter to command function - :param statement: command line string or already generated Statement + :param args: All positional arguments to this function. We're expecting there to be: + cmd2_app, statement: Union[Statement, str] + contiguously somewhere in the list :param kwargs: any keyword arguments being passed to command function :return: return value of command function """ + cmd2_app, statement = _parse_positionals(args) _, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(command_name, statement, preserve_quotes) - - return func(cmd2_app, parsed_arglist, **kwargs) + args_list = _arg_swap(args, statement, parsed_arglist) + return func(*args_list, **kwargs) command_name = func.__name__[len(constants.COMMAND_FUNC_PREFIX):] cmd_wrapper.__doc__ = func.__doc__ @@ -159,17 +197,19 @@ def with_argparser_and_unknown_args(parser: argparse.ArgumentParser, *, def arg_decorator(func: Callable): @functools.wraps(func) - def cmd_wrapper(cmd2_app, statement: Union[Statement, str], **kwargs: Dict[str, Any]) -> Optional[bool]: + def cmd_wrapper(*args: Tuple[Any, ...], **kwargs: Dict[str, Any]) -> Optional[bool]: """ Command function wrapper which translates command line into argparse Namespace and calls actual command function - :param cmd2_app: CLI instance passed as self parameter to command function - :param statement: command line string or already generated Statement + :param args: All positional arguments to this function. We're expecting there to be: + cmd2_app, statement: Union[Statement, str] + contiguously somewhere in the list :param kwargs: any keyword arguments being passed to command function :return: return value of command function :raises: Cmd2ArgparseError if argparse has error parsing command line """ + cmd2_app, statement = _parse_positionals(args) statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(command_name, statement, preserve_quotes) @@ -180,12 +220,13 @@ def cmd_wrapper(cmd2_app, statement: Union[Statement, str], **kwargs: Dict[str, namespace = ns_provider(cmd2_app) try: - args, unknown = parser.parse_known_args(parsed_arglist, namespace) + ns, unknown = parser.parse_known_args(parsed_arglist, namespace) except SystemExit: raise Cmd2ArgparseError else: - setattr(args, '__statement__', statement) - return func(cmd2_app, args, unknown, **kwargs) + setattr(ns, '__statement__', statement) + args_list = _arg_swap(args, statement, ns, unknown) + return func(*args_list, **kwargs) # argparser defaults the program name to sys.argv[0], but we want it to be the name of our command command_name = func.__name__[len(constants.COMMAND_FUNC_PREFIX):] @@ -241,17 +282,19 @@ def with_argparser(parser: argparse.ArgumentParser, *, def arg_decorator(func: Callable): @functools.wraps(func) - def cmd_wrapper(cmd2_app, statement: Union[Statement, str], **kwargs: Dict[str, Any]) -> Optional[bool]: + def cmd_wrapper(*args: Any, **kwargs: Dict[str, Any]) -> Optional[bool]: """ Command function wrapper which translates command line into argparse Namespace and calls actual command function - :param cmd2_app: CLI instance passed as self parameter to command function - :param statement: command line string or already generated Statement + :param args: All positional arguments to this function. We're expecting there to be: + cmd2_app, statement: Union[Statement, str] + contiguously somewhere in the list :param kwargs: any keyword arguments being passed to command function :return: return value of command function :raises: Cmd2ArgparseError if argparse has error parsing command line """ + cmd2_app, statement = _parse_positionals(args) statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(command_name, statement, preserve_quotes) @@ -262,12 +305,13 @@ def cmd_wrapper(cmd2_app, statement: Union[Statement, str], **kwargs: Dict[str, namespace = ns_provider(cmd2_app) try: - args = parser.parse_args(parsed_arglist, namespace) + ns = parser.parse_args(parsed_arglist, namespace) except SystemExit: raise Cmd2ArgparseError else: - setattr(args, '__statement__', statement) - return func(cmd2_app, args, **kwargs) + setattr(ns, '__statement__', statement) + args_list = _arg_swap(args, statement, ns) + return func(*args_list, **kwargs) # argparser defaults the program name to sys.argv[0], but we want it to be the name of our command command_name = func.__name__[len(constants.COMMAND_FUNC_PREFIX):] diff --git a/docs/api/command_definition.rst b/docs/api/command_definition.rst new file mode 100644 index 000000000..cfb7082ed --- /dev/null +++ b/docs/api/command_definition.rst @@ -0,0 +1,5 @@ +cmd2.command_definition +======================= + +.. automodule:: cmd2.command_definition + :members: diff --git a/docs/api/index.rst b/docs/api/index.rst index cc899ba1c..17a259072 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -23,6 +23,7 @@ This documentation is for ``cmd2`` version |version|. argparse_completer argparse_custom constants + command_definition decorators exceptions history diff --git a/examples/modular_commands/__init__.py b/examples/modular_commands/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/examples/modular_commands/commandset_basic.py b/examples/modular_commands/commandset_basic.py new file mode 100644 index 000000000..25ba976d6 --- /dev/null +++ b/examples/modular_commands/commandset_basic.py @@ -0,0 +1,121 @@ +# coding=utf-8 +""" +A simple example demonstrating a loadable command set +""" +from typing import List + +from cmd2 import Cmd, CommandSet, Statement, register_command, with_category, with_default_category +from cmd2.utils import CompletionError + + +@register_command +@with_category("AAA") +def do_unbound(cmd: Cmd, statement: Statement): + """This is an example of registering an unbound function + + :param cmd: + :param statement: + :return: + """ + cmd.poutput('Unbound Command: {}'.format(statement.args)) + + +@register_command +@with_category("AAA") +def do_func_with_help(cmd: Cmd, statement: Statement): + """ + This is an example of registering an unbound function + + :param cmd: + :param statement: + :return: + """ + cmd.poutput('Unbound Command: {}'.format(statement.args)) + + +def help_func_with_help(cmd: Cmd): + cmd.poutput('Help for func_with_help') + + +@with_default_category('Basic Completion') +class BasicCompletionCommandSet(CommandSet): + # List of strings used with completion functions + food_item_strs = ['Pizza', 'Ham', 'Ham Sandwich', 'Potato'] + sport_item_strs = ['Bat', 'Basket', 'Basketball', 'Football', 'Space Ball'] + + # This data is used to demonstrate delimiter_complete + file_strs = \ + [ + '/home/user/file.db', + '/home/user/file space.db', + '/home/user/another.db', + '/home/other user/maps.db', + '/home/other user/tests.db' + ] + + def do_flag_based(self, cmd: Cmd, statement: Statement): + """Tab completes arguments based on a preceding flag using flag_based_complete + -f, --food [completes food items] + -s, --sport [completes sports] + -p, --path [completes local file system paths] + """ + cmd.poutput("Args: {}".format(statement.args)) + + def complete_flag_based(self, cmd: Cmd, text: str, line: str, begidx: int, endidx: int) -> List[str]: + """Completion function for do_flag_based""" + flag_dict = \ + { + # Tab complete food items after -f and --food flags in command line + '-f': self.food_item_strs, + '--food': self.food_item_strs, + + # Tab complete sport items after -s and --sport flags in command line + '-s': self.sport_item_strs, + '--sport': self.sport_item_strs, + + # Tab complete using path_complete function after -p and --path flags in command line + '-p': cmd.path_complete, + '--path': cmd.path_complete, + } + + return cmd.flag_based_complete(text, line, begidx, endidx, flag_dict=flag_dict) + + def do_index_based(self, cmd: Cmd, statement: Statement): + """Tab completes first 3 arguments using index_based_complete""" + cmd.poutput("Args: {}".format(statement.args)) + + def complete_index_based(self, cmd: Cmd, text: str, line: str, begidx: int, endidx: int) -> List[str]: + """Completion function for do_index_based""" + index_dict = \ + { + 1: self.food_item_strs, # Tab complete food items at index 1 in command line + 2: self.sport_item_strs, # Tab complete sport items at index 2 in command line + 3: cmd.path_complete, # Tab complete using path_complete function at index 3 in command line + } + + return cmd.index_based_complete(text, line, begidx, endidx, index_dict=index_dict) + + def do_delimiter_complete(self, cmd: Cmd, statement: Statement): + """Tab completes files from a list using delimiter_complete""" + cmd.poutput("Args: {}".format(statement.args)) + + def complete_delimiter_complete(self, cmd: Cmd, text: str, line: str, begidx: int, endidx: int) -> List[str]: + return cmd.delimiter_complete(text, line, begidx, endidx, match_against=self.file_strs, delimiter='/') + + def do_raise_error(self, cmd: Cmd, statement: Statement): + """Demonstrates effect of raising CompletionError""" + cmd.poutput("Args: {}".format(statement.args)) + + def complete_raise_error(self, cmd: Cmd, text: str, line: str, begidx: int, endidx: int) -> List[str]: + """ + CompletionErrors can be raised if an error occurs while tab completing. + + Example use cases + - Reading a database to retrieve a tab completion data set failed + - A previous command line argument that determines the data set being completed is invalid + """ + raise CompletionError("This is how a CompletionError behaves") + + @with_category('Not Basic Completion') + def do_custom_category(self, cmd: Cmd, statement: Statement): + cmd.poutput('Demonstrates a command that bypasses the default category') diff --git a/examples/modular_commands/commandset_custominit.py b/examples/modular_commands/commandset_custominit.py new file mode 100644 index 000000000..d96c5f1c6 --- /dev/null +++ b/examples/modular_commands/commandset_custominit.py @@ -0,0 +1,32 @@ +# coding=utf-8 +""" +A simple example demonstrating a loadable command set +""" +from cmd2 import Cmd, CommandSet, Statement, register_command, with_category, with_default_category + + +@register_command +@with_category("AAA") +def do_another_command(cmd: Cmd, statement: Statement): + """ + This is an example of registering an unbound function + :param cmd: + :param statement: + :return: + """ + cmd.poutput('Another Unbound Command: {}'.format(statement.args)) + + +@with_default_category('Custom Init') +class CustomInitCommandSet(CommandSet): + def __init__(self, arg1, arg2): + super().__init__() + + self._arg1 = arg1 + self._arg2 = arg2 + + def do_show_arg1(self, cmd: Cmd, _: Statement): + cmd.poutput('Arg1: ' + self._arg1) + + def do_show_arg2(self, cmd: Cmd, _: Statement): + cmd.poutput('Arg2: ' + self._arg2) diff --git a/examples/modular_commands_main.py b/examples/modular_commands_main.py new file mode 100644 index 000000000..9e7f79ccd --- /dev/null +++ b/examples/modular_commands_main.py @@ -0,0 +1,127 @@ +#!/usr/bin/env python +# coding=utf-8 +""" +A simple example demonstrating how to integrate tab completion with argparse-based commands. +""" +import argparse +from typing import Dict, Iterable, List, Optional + +from cmd2 import Cmd, Cmd2ArgumentParser, CommandSet, CompletionItem, with_argparser +from cmd2.utils import CompletionError, basic_complete +from modular_commands.commandset_basic import BasicCompletionCommandSet # noqa: F401 +from modular_commands.commandset_custominit import CustomInitCommandSet # noqa: F401 + +# Data source for argparse.choices +food_item_strs = ['Pizza', 'Ham', 'Ham Sandwich', 'Potato'] + + +def choices_function() -> List[str]: + """Choices functions are useful when the choice list is dynamically generated (e.g. from data in a database)""" + return ['a', 'dynamic', 'list', 'goes', 'here'] + + +def completer_function(text: str, line: str, begidx: int, endidx: int) -> List[str]: + """ + A tab completion function not dependent on instance data. Since custom tab completion operations commonly + need to modify cmd2's instance variables related to tab completion, it will be rare to need a completer + function. completer_method should be used in those cases. + """ + match_against = ['a', 'dynamic', 'list', 'goes', 'here'] + return basic_complete(text, line, begidx, endidx, match_against) + + +def choices_completion_item() -> List[CompletionItem]: + """Return CompletionItem instead of strings. These give more context to what's being tab completed.""" + items = \ + { + 1: "My item", + 2: "Another item", + 3: "Yet another item" + } + return [CompletionItem(item_id, description) for item_id, description in items.items()] + + +def choices_arg_tokens(arg_tokens: Dict[str, List[str]]) -> List[str]: + """ + If a choices or completer function/method takes a value called arg_tokens, then it will be + passed a dictionary that maps the command line tokens up through the one being completed + to their argparse argument name. All values of the arg_tokens dictionary are lists, even if + a particular argument expects only 1 token. + """ + # Check if choices_function flag has appeared + values = ['choices_function', 'flag'] + if 'choices_function' in arg_tokens: + values.append('is {}'.format(arg_tokens['choices_function'][0])) + else: + values.append('not supplied') + return values + + +class WithCommandSets(Cmd): + def __init__(self, command_sets: Optional[Iterable[CommandSet]] = None): + super().__init__(command_sets=command_sets) + self.sport_item_strs = ['Bat', 'Basket', 'Basketball', 'Football', 'Space Ball'] + + def choices_method(self) -> List[str]: + """Choices methods are useful when the choice list is based on instance data of your application""" + return self.sport_item_strs + + def choices_completion_error(self) -> List[str]: + """ + CompletionErrors can be raised if an error occurs while tab completing. + + Example use cases + - Reading a database to retrieve a tab completion data set failed + - A previous command line argument that determines the data set being completed is invalid + """ + if self.debug: + return self.sport_item_strs + raise CompletionError("debug must be true") + + # Parser for example command + example_parser = Cmd2ArgumentParser(description="Command demonstrating tab completion with argparse\n" + "Notice even the flags of this command tab complete") + + # Tab complete from a list using argparse choices. Set metavar if you don't + # want the entire choices list showing in the usage text for this command. + example_parser.add_argument('--choices', choices=food_item_strs, metavar="CHOICE", + help="tab complete using choices") + + # Tab complete from choices provided by a choices function and choices method + example_parser.add_argument('--choices_function', choices_function=choices_function, + help="tab complete using a choices_function") + example_parser.add_argument('--choices_method', choices_method=choices_method, + help="tab complete using a choices_method") + + # Tab complete using a completer function and completer method + example_parser.add_argument('--completer_function', completer_function=completer_function, + help="tab complete using a completer_function") + example_parser.add_argument('--completer_method', completer_method=Cmd.path_complete, + help="tab complete using a completer_method") + + # Demonstrate raising a CompletionError while tab completing + example_parser.add_argument('--completion_error', choices_method=choices_completion_error, + help="raise a CompletionError while tab completing if debug is False") + + # Demonstrate returning CompletionItems instead of strings + example_parser.add_argument('--completion_item', choices_function=choices_completion_item, metavar="ITEM_ID", + descriptive_header="Description", + help="demonstrate use of CompletionItems") + + # Demonstrate use of arg_tokens dictionary + example_parser.add_argument('--arg_tokens', choices_function=choices_arg_tokens, + help="demonstrate use of arg_tokens dictionary") + + @with_argparser(example_parser) + def do_example(self, _: argparse.Namespace) -> None: + """The example command""" + self.poutput("I do nothing") + + +if __name__ == '__main__': + import sys + + print("Starting") + my_sets = [CustomInitCommandSet('First argument', 'Second argument')] + app = WithCommandSets(command_sets=my_sets) + sys.exit(app.cmdloop()) diff --git a/tests/conftest.py b/tests/conftest.py index 60074f5cb..adaba062d 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -25,11 +25,14 @@ pass -def verify_help_text(cmd2_app: cmd2.Cmd, help_output: Union[str, List[str]]) -> None: +def verify_help_text(cmd2_app: cmd2.Cmd, + help_output: Union[str, List[str]], + verbose_strings: Optional[List[str]] = None) -> None: """This function verifies that all expected commands are present in the help text. :param cmd2_app: instance of cmd2.Cmd :param help_output: output of help, either as a string or list of strings + :param verbose_strings: optional list of verbose strings to search for """ if isinstance(help_output, str): help_text = help_output @@ -39,7 +42,9 @@ def verify_help_text(cmd2_app: cmd2.Cmd, help_output: Union[str, List[str]]) -> for command in commands: assert command in help_text - # TODO: Consider adding checks for categories and for verbose history + if verbose_strings: + for verbose_string in verbose_strings: + assert verbose_string in help_text # Help text for the history command @@ -147,7 +152,7 @@ def run_cmd(app, cmd): @fixture def base_app(): - return cmd2.Cmd() + return cmd2.Cmd(auto_load_commands=False) # These are odd file names for testing quoting of them diff --git a/tests/test_argparse.py b/tests/test_argparse.py index daf434978..4f5dcf35e 100644 --- a/tests/test_argparse.py +++ b/tests/test_argparse.py @@ -28,7 +28,7 @@ class ArgparseApp(cmd2.Cmd): def __init__(self): self.maxrepeats = 3 - cmd2.Cmd.__init__(self) + cmd2.Cmd.__init__(self, auto_load_commands=False) def namespace_provider(self) -> argparse.Namespace: ns = argparse.Namespace() @@ -223,7 +223,7 @@ class SubcommandApp(cmd2.Cmd): """ Example cmd2 application where we a base command which has a couple subcommands.""" def __init__(self): - cmd2.Cmd.__init__(self) + cmd2.Cmd.__init__(self, auto_load_commands=False) # subcommand functions for the base command def base_foo(self, args): diff --git a/tests/test_argparse_completer.py b/tests/test_argparse_completer.py index 4313647b0..cc692b7c7 100644 --- a/tests/test_argparse_completer.py +++ b/tests/test_argparse_completer.py @@ -58,7 +58,7 @@ def completer_takes_arg_tokens(text: str, line: str, begidx: int, endidx: int, class AutoCompleteTester(cmd2.Cmd): """Cmd2 app that exercises ArgparseCompleter class""" def __init__(self, *args, **kwargs): - super().__init__(*args, **kwargs) + super().__init__(*args, auto_load_commands=False, **kwargs) ############################################################################################################ # Begin code related to help and command name completion diff --git a/tests/test_argparse_custom.py b/tests/test_argparse_custom.py index f4db12b6d..1ad1a4223 100644 --- a/tests/test_argparse_custom.py +++ b/tests/test_argparse_custom.py @@ -33,7 +33,7 @@ def do_range(self, _): @pytest.fixture def cust_app(): - return ApCustomTestApp() + return ApCustomTestApp(auto_load_commands=False) def fake_func(): diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py index bc0e0a94f..85dcd3bf5 100755 --- a/tests/test_cmd2.py +++ b/tests/test_cmd2.py @@ -36,7 +36,7 @@ def CreateOutsimApp(): - c = cmd2.Cmd() + c = cmd2.Cmd(auto_load_commands=False) c.stdout = utils.StdSim(c.stdout) return c @@ -925,7 +925,7 @@ def test_ansi_prompt_not_esacped(base_app): def test_ansi_prompt_escaped(): from cmd2.rl_utils import rl_make_safe_prompt - app = cmd2.Cmd() + app = cmd2.Cmd(auto_load_commands=False) color = 'cyan' prompt = 'InColor' color_prompt = ansi.style(prompt, fg=color) @@ -1025,14 +1025,32 @@ def helpcat_app(): app = HelpCategoriesApp() return app + def test_help_cat_base(helpcat_app): out, err = run_cmd(helpcat_app, 'help') verify_help_text(helpcat_app, out) + cmds_cats, cmds_doc, cmds_undoc, help_topics = helpcat_app._build_command_info() + assert 'Some Category' in cmds_cats + assert 'diddly' in cmds_cats['Some Category'] + assert 'cat_nodoc' in cmds_cats['Some Category'] + assert 'Custom Category' in cmds_cats + assert 'squat' in cmds_cats['Custom Category'] + assert 'edit' in cmds_cats['Custom Category'] + assert 'undoc' in cmds_undoc + assert 'Fake Category' not in cmds_cats + + help_text = ''.join(out) + assert 'This command does diddly squat...' not in help_text + + def test_help_cat_verbose(helpcat_app): out, err = run_cmd(helpcat_app, 'help --verbose') verify_help_text(helpcat_app, out) + help_text = ''.join(out) + assert 'This command does diddly squat...' in help_text + class SelectApp(cmd2.Cmd): def do_eat(self, arg): @@ -1396,7 +1414,7 @@ def test_eof(base_app): assert base_app.do_eof('') def test_echo(capsys): - app = cmd2.Cmd() + app = cmd2.Cmd(auto_load_commands=False) app.echo = True commands = ['help history'] @@ -1409,7 +1427,7 @@ def test_read_input_rawinput_true(capsys, monkeypatch): prompt_str = 'the_prompt' input_str = 'some input' - app = cmd2.Cmd() + app = cmd2.Cmd(auto_load_commands=False) app.use_rawinput = True # Mock out input() to return input_str diff --git a/tests/test_commandset.py b/tests/test_commandset.py new file mode 100644 index 000000000..eedf51de4 --- /dev/null +++ b/tests/test_commandset.py @@ -0,0 +1,367 @@ +# coding=utf-8 +# flake8: noqa E302 +""" +Test CommandSet +""" + +from typing import List + +import pytest + +import cmd2 +from cmd2 import utils + +from .conftest import complete_tester, normalize, run_cmd + + +@cmd2.register_command +@cmd2.with_category("AAA") +def do_unbound(cmd: cmd2.Cmd, statement: cmd2.Statement): + """ + This is an example of registering an unbound function + + :param cmd: + :param statement: + :return: + """ + cmd.poutput('Unbound Command: {}'.format(statement.args)) + + +@cmd2.register_command +@cmd2.with_category("AAA") +def do_command_with_support(cmd: cmd2.Cmd, statement: cmd2.Statement): + """ + This is an example of registering an unbound function + + :param cmd: + :param statement: + :return: + """ + cmd.poutput('Command with support functions: {}'.format(statement.args)) + + +def help_command_with_support(cmd: cmd2.Cmd): + cmd.poutput('Help for command_with_support') + + +def complete_command_with_support(cmd: cmd2.Cmd, text: str, line: str, begidx: int, endidx: int) -> List[str]: + """Completion function for do_index_based""" + food_item_strs = ['Pizza', 'Ham', 'Ham Sandwich', 'Potato'] + sport_item_strs = ['Bat', 'Basket', 'Basketball', 'Football', 'Space Ball'] + + index_dict = \ + { + 1: food_item_strs, # Tab complete food items at index 1 in command line + 2: sport_item_strs, # Tab complete sport items at index 2 in command line + 3: cmd.path_complete, # Tab complete using path_complete function at index 3 in command line + } + + return cmd.index_based_complete(text, line, begidx, endidx, index_dict=index_dict) + + +@cmd2.with_default_category('Command Set') +class CommandSetA(cmd2.CommandSet): + def do_apple(self, cmd: cmd2.Cmd, statement: cmd2.Statement): + cmd.poutput('Apple!') + + def do_banana(self, cmd: cmd2.Cmd, statement: cmd2.Statement): + """Banana Command""" + cmd.poutput('Banana!!') + + def do_cranberry(self, cmd: cmd2.Cmd, statement: cmd2.Statement): + cmd.poutput('Cranberry!!') + + def help_cranberry(self, cmd: cmd2.Cmd): + cmd.stdout.write('This command does diddly squat...\n') + + def do_durian(self, cmd: cmd2.Cmd, statement: cmd2.Statement): + """Durian Command""" + cmd.poutput('Durian!!') + + def complete_durian(self, cmd: cmd2.Cmd, text: str, line: str, begidx: int, endidx: int) -> List[str]: + return utils.basic_complete(text, line, begidx, endidx, ['stinks', 'smells', 'disgusting']) + + @cmd2.with_category('Alone') + def do_elderberry(self, cmd: cmd2.Cmd, statement: cmd2.Statement): + cmd.poutput('Elderberry!!') + + +class WithCommandSets(cmd2.Cmd): + """Class for testing custom help_* methods which override docstring help.""" + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + + +@cmd2.with_default_category('Command Set B') +class CommandSetB(cmd2.CommandSet): + def __init__(self, arg1): + super().__init__() + self._arg1 = arg1 + + def do_aardvark(self, cmd: cmd2.Cmd, statement: cmd2.Statement): + cmd.poutput('Aardvark!') + + def do_bat(self, cmd: cmd2.Cmd, statement: cmd2.Statement): + """Banana Command""" + cmd.poutput('Bat!!') + + def do_crocodile(self, cmd: cmd2.Cmd, statement: cmd2.Statement): + cmd.poutput('Crocodile!!') + + +@pytest.fixture +def command_sets_app(): + app = WithCommandSets() + return app + + +@pytest.fixture() +def command_sets_manual(): + app = WithCommandSets(auto_load_commands=False) + return app + + +def test_autoload_commands(command_sets_app): + # verifies that, when autoload is enabled, CommandSets and registered functions all show up + + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_app._build_command_info() + + assert 'AAA' in cmds_cats + assert 'unbound' in cmds_cats['AAA'] + + assert 'Alone' in cmds_cats + assert 'elderberry' in cmds_cats['Alone'] + + assert 'Command Set' in cmds_cats + assert 'cranberry' in cmds_cats['Command Set'] + + +def test_custom_construct_commandsets(): + # Verifies that a custom initialized CommandSet loads correctly when passed into the constructor + command_set = CommandSetB('foo') + app = WithCommandSets(command_sets=[command_set]) + + cmds_cats, cmds_doc, cmds_undoc, help_topics = app._build_command_info() + assert 'Command Set B' in cmds_cats + + command_set_2 = CommandSetB('bar') + with pytest.raises(ValueError): + assert app.install_command_set(command_set_2) + + +def test_load_commands(command_sets_manual): + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + + # start by verifying none of the installable commands are present + assert 'AAA' not in cmds_cats + assert 'Alone' not in cmds_cats + assert 'Command Set' not in cmds_cats + + # install the `unbound` command + command_sets_manual.install_registered_command('unbound') + + # verify that the same registered command can't be installed twice + with pytest.raises(ValueError): + assert command_sets_manual.install_registered_command('unbound') + + # verifies detection of unregistered commands + with pytest.raises(KeyError): + assert command_sets_manual.install_registered_command('nonexistent_command') + + # verifies that a duplicate function name is detected + def do_unbound(cmd: cmd2.Cmd, statement: cmd2.Statement): + """ + This function duplicates an existing command + """ + cmd.poutput('Unbound Command: {}'.format(statement.args)) + + with pytest.raises(KeyError): + assert cmd2.register_command(do_unbound) + + # verify only the `unbound` command was installed + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + + assert 'AAA' in cmds_cats + assert 'unbound' in cmds_cats['AAA'] + assert 'Alone' not in cmds_cats + assert 'Command Set' not in cmds_cats + + # now install a command set and verify the commands are now present + cmd_set = CommandSetA() + command_sets_manual.install_command_set(cmd_set) + + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + + assert 'AAA' in cmds_cats + assert 'unbound' in cmds_cats['AAA'] + + assert 'Alone' in cmds_cats + assert 'elderberry' in cmds_cats['Alone'] + + assert 'Command Set' in cmds_cats + assert 'cranberry' in cmds_cats['Command Set'] + + # uninstall the `unbound` command and verify only it was uninstalled + command_sets_manual.uninstall_command('unbound') + + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + + assert 'AAA' not in cmds_cats + + assert 'Alone' in cmds_cats + assert 'elderberry' in cmds_cats['Alone'] + + assert 'Command Set' in cmds_cats + assert 'cranberry' in cmds_cats['Command Set'] + + # uninstall the command set and verify it is now also no longer accessible + command_sets_manual.uninstall_command_set(cmd_set) + + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + + assert 'AAA' not in cmds_cats + assert 'Alone' not in cmds_cats + assert 'Command Set' not in cmds_cats + + # reinstall the command set and verifyt is accessible but the `unbound` command isn't + command_sets_manual.install_command_set(cmd_set) + + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + + assert 'AAA' not in cmds_cats + + assert 'Alone' in cmds_cats + assert 'elderberry' in cmds_cats['Alone'] + + assert 'Command Set' in cmds_cats + assert 'cranberry' in cmds_cats['Command Set'] + + +def test_command_functions(command_sets_manual): + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + assert 'AAA' not in cmds_cats + + out, err = run_cmd(command_sets_manual, 'command_with_support') + assert 'is not a recognized command, alias, or macro' in err[0] + + out, err = run_cmd(command_sets_manual, 'help command_with_support') + assert 'No help on command_with_support' in err[0] + + text = '' + line = 'command_with_support' + endidx = len(line) + begidx = endidx - len(text) + + first_match = complete_tester(text, line, begidx, endidx, command_sets_manual) + assert first_match is None + + # A bad command name gets rejected with an exception + with pytest.raises(ValueError): + assert command_sets_manual.install_command_function('>"', + do_command_with_support, + complete_command_with_support, + help_command_with_support) + + # create an alias to verify that it gets removed when the command is created + out, err = run_cmd(command_sets_manual, 'alias create command_with_support run_pyscript') + assert out == normalize("Alias 'command_with_support' created") + + command_sets_manual.install_registered_command('command_with_support') + + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + assert 'AAA' in cmds_cats + assert 'command_with_support' in cmds_cats['AAA'] + + out, err = run_cmd(command_sets_manual, 'command_with_support') + assert 'Command with support functions' in out[0] + + out, err = run_cmd(command_sets_manual, 'help command_with_support') + assert 'Help for command_with_support' in out[0] + + first_match = complete_tester(text, line, begidx, endidx, command_sets_manual) + assert first_match == 'Ham' + + text = '' + line = 'command_with_support Ham' + endidx = len(line) + begidx = endidx - len(text) + + first_match = complete_tester(text, line, begidx, endidx, command_sets_manual) + + assert first_match == 'Basket' + + command_sets_manual.uninstall_command('command_with_support') + + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + assert 'AAA' not in cmds_cats + + out, err = run_cmd(command_sets_manual, 'command_with_support') + assert 'is not a recognized command, alias, or macro' in err[0] + + out, err = run_cmd(command_sets_manual, 'help command_with_support') + assert 'No help on command_with_support' in err[0] + + text = '' + line = 'command_with_support' + endidx = len(line) + begidx = endidx - len(text) + + first_match = complete_tester(text, line, begidx, endidx, command_sets_manual) + assert first_match is None + + # create an alias to verify that it gets removed when the command is created + out, err = run_cmd(command_sets_manual, 'macro create command_with_support run_pyscript') + assert out == normalize("Macro 'command_with_support' created") + + command_sets_manual.install_command_function('command_with_support', + do_command_with_support, + complete_command_with_support, + help_command_with_support) + + cmds_cats, cmds_doc, cmds_undoc, help_topics = command_sets_manual._build_command_info() + assert 'AAA' in cmds_cats + assert 'command_with_support' in cmds_cats['AAA'] + + out, err = run_cmd(command_sets_manual, 'command_with_support') + assert 'Command with support functions' in out[0] + + out, err = run_cmd(command_sets_manual, 'help command_with_support') + assert 'Help for command_with_support' in out[0] + + first_match = complete_tester(text, line, begidx, endidx, command_sets_manual) + assert first_match == 'Ham' + + text = '' + line = 'command_with_support Ham' + endidx = len(line) + begidx = endidx - len(text) + + first_match = complete_tester(text, line, begidx, endidx, command_sets_manual) + + assert first_match == 'Basket' + + + +def test_partial_with_passthru(): + + def test_func(arg1, arg2): + """Documentation Comment""" + print('Do stuff {} - {}'.format(arg1, arg2)) + + my_partial = cmd2.command_definition._partial_passthru(test_func, 1) + + setattr(test_func, 'Foo', 5) + + assert hasattr(my_partial, 'Foo') + + assert getattr(my_partial, 'Foo', None) == 5 + + a = dir(test_func) + b = dir(my_partial) + assert a == b + + assert not hasattr(test_func, 'Bar') + setattr(my_partial, 'Bar', 6) + assert hasattr(test_func, 'Bar') + + assert getattr(test_func, 'Bar', None) == 6 diff --git a/tests/test_completion.py b/tests/test_completion.py index a380d43af..9a611fc02 100755 --- a/tests/test_completion.py +++ b/tests/test_completion.py @@ -1098,7 +1098,7 @@ class SubcommandsWithUnknownExample(cmd2.Cmd): """ def __init__(self): - cmd2.Cmd.__init__(self) + cmd2.Cmd.__init__(self, auto_load_commands=False) # subcommand functions for the base command def base_foo(self, args): diff --git a/tests/test_parsing.py b/tests/test_parsing.py index c2c242fe3..3d6495166 100755 --- a/tests/test_parsing.py +++ b/tests/test_parsing.py @@ -588,7 +588,7 @@ def test_parse_unclosed_quotes(parser): _ = parser.tokenize("command with 'unclosed quotes") def test_empty_statement_raises_exception(): - app = cmd2.Cmd() + app = cmd2.Cmd(auto_load_commands=False) with pytest.raises(exceptions.EmptyStatement): app._complete_statement('') diff --git a/tests/test_plugin.py b/tests/test_plugin.py index e49cbbfc3..6e6a4a427 100644 --- a/tests/test_plugin.py +++ b/tests/test_plugin.py @@ -263,7 +263,7 @@ def cmdfinalization_hook_wrong_return_annotation(self, data: plugin.CommandFinal class PluggedApp(Plugin, cmd2.Cmd): """A sample app with a plugin mixed in""" def __init__(self, *args, **kwargs): - super().__init__(*args, **kwargs) + super().__init__(*args, auto_load_commands=False, **kwargs) def do_say(self, statement): """Repeat back the arguments""" diff --git a/tests/test_transcript.py b/tests/test_transcript.py index 69389b7f2..284e9c370 100644 --- a/tests/test_transcript.py +++ b/tests/test_transcript.py @@ -29,7 +29,7 @@ class CmdLineApp(cmd2.Cmd): def __init__(self, *args, **kwargs): self.maxrepeats = 3 - super().__init__(*args, multiline_commands=['orate'], **kwargs) + super().__init__(*args, multiline_commands=['orate'], auto_load_commands=False, **kwargs) # Make maxrepeats settable at runtime self.add_settable(Settable('maxrepeats', int, 'Max number of `--repeat`s allowed'))