| # Copyright (c) 2012 The Chromium OS Authors. All rights reserved. |
| # Use of this source code is governed by a BSD-style license that can be |
| # found in the LICENSE file. |
| |
| """Module that contains meta-logic related to CLI commands. |
| |
| CLI commands are the subcommands available to the user, such as "deploy" in |
| `cros deploy` or "shell" in `brillo shell`. |
| |
| This module contains two important definitions used by all commands: |
| CliCommand: The parent class of all CLI commands. |
| CommandDecorator: Decorator that must be used to ensure that the command shows |
| up in |_commands| and is discoverable. |
| |
| Commands can be either imported directly or looked up using this module's |
| ListCommands() function. |
| """ |
| |
| from __future__ import print_function |
| |
| import glob |
| import os |
| import sys |
| |
| from chromite.lib import brick_lib |
| from chromite.lib import commandline |
| from chromite.lib import cros_build_lib |
| from chromite.lib import cros_import |
| from chromite.lib import cros_logging as logging |
| |
| |
| _commands = dict() |
| |
| |
| def UseProgressBar(): |
| """Determine whether the progress bar is to be used or not. |
| |
| We only want the progress bar to display for the brillo commands which operate |
| at logging level NOTICE. If the user wants to see the noisy output, then they |
| can execute the command at logging level INFO or DEBUG. |
| """ |
| return logging.getLogger().getEffectiveLevel() == logging.NOTICE |
| |
| |
| def _GetToolset(): |
| """Return the CLI toolset invoked by the user. |
| |
| For example, if the user is executing `cros flash`, this will return 'cros'. |
| |
| This won't work for unittests so if a certain toolset must be loaded for |
| a unittest this should be mocked out to return the desired string. |
| """ |
| return os.path.basename(sys.argv[0]) |
| |
| |
| def _FindModules(subdir_path, toolset): |
| """Returns a list of all the relevant python modules in |subdir_path|. |
| |
| The modules returned are based on |toolset|, so if |toolset| is 'cros' |
| then cros_xxx.py modules will be found. |
| |
| Args: |
| subdir_path: directory (string) to search for modules in. |
| toolset: toolset (string) to find. |
| |
| Returns: |
| List of filenames (strings). |
| """ |
| modules = [] |
| for file_path in glob.glob(os.path.join(subdir_path, toolset + '_*.py')): |
| if not file_path.endswith('_unittest.py'): |
| modules.append(file_path) |
| return modules |
| |
| |
| def _ImportCommands(toolset): |
| """Directly imports all |toolset| python modules. |
| |
| This method imports the |toolset|_[!unittest] modules which may contain |
| commands. When these modules are loaded, declared commands (those that use |
| CommandDecorator) will automatically get added to |_commands|. |
| |
| Args: |
| toolset: toolset (string) to import. |
| """ |
| subdir_path = os.path.join(os.path.dirname(__file__), toolset) |
| for file_path in _FindModules(subdir_path, toolset): |
| file_name = os.path.basename(file_path) |
| mod_name = os.path.splitext(file_name)[0] |
| cros_import.ImportModule(('chromite', 'cli', toolset, mod_name)) |
| |
| |
| def ListCommands(toolset=None): |
| """Return a dictionary mapping command names to classes. |
| |
| Args: |
| toolset: toolset (string) to list, None to determine from the commandline. |
| |
| Returns: |
| A dictionary mapping names (strings) to commands (classes). |
| """ |
| _ImportCommands(toolset or _GetToolset()) |
| return _commands.copy() |
| |
| |
| class InvalidCommandError(Exception): |
| """Error that occurs when command class fails sanity checks.""" |
| pass |
| |
| |
| def CommandDecorator(command_name): |
| """Decorator that sanity checks and adds class to list of usable commands.""" |
| |
| def InnerCommandDecorator(original_class): |
| """"Inner Decorator that actually wraps the class.""" |
| if not hasattr(original_class, '__doc__'): |
| raise InvalidCommandError('All handlers must have docstrings: %s' % |
| original_class) |
| |
| if not issubclass(original_class, CliCommand): |
| raise InvalidCommandError('All Commands must derive from CliCommand: %s' % |
| original_class) |
| |
| _commands[command_name] = original_class |
| original_class.command_name = command_name |
| |
| return original_class |
| |
| return InnerCommandDecorator |
| |
| |
| class CliCommand(object): |
| """All CLI commands must derive from this class. |
| |
| This class provides the abstract interface for all CLI commands. When |
| designing a new command, you must sub-class from this class and use the |
| CommandDecorator decorator. You must specify a class docstring as that will be |
| used as the usage for the sub-command. |
| |
| In addition your command should implement AddParser which is passed in a |
| parser that you can add your own custom arguments. See argparse for more |
| information. |
| """ |
| # Indicates whether command stats should be uploaded for this command. |
| # Override to enable command stats uploading. |
| upload_stats = False |
| # We set the default timeout to 1 second, to prevent overly long waits for |
| # commands to complete. From manual tests, stat uploads usually take |
| # between 0.35s-0.45s in MTV. |
| upload_stats_timeout = 1 |
| |
| # Indicates whether command uses cache related commandline options. |
| use_caching_options = False |
| |
| def __init__(self, options): |
| self.options = options |
| brick = brick_lib.FindBrickInPath() |
| self.curr_brick_locator = brick.brick_locator if brick else None |
| |
| @classmethod |
| def AddParser(cls, parser): |
| """Add arguments for this command to the parser.""" |
| parser.set_defaults(command_class=cls) |
| |
| @classmethod |
| def AddDeviceArgument(cls, parser, schemes=commandline.DEVICE_SCHEME_SSH, |
| optional=None): |
| """Add a device argument to the parser. |
| |
| This has a few advantages over adding a device argument directly: |
| - Standardizes the device --help message for all tools. |
| - May allow `brillo` and `cros` to use the same source. |
| |
| The device argument is normally positional in cros but optional in |
| brillo. If that is the only difference between a cros and brillo |
| tool, this function allows the same source be shared for both. |
| |
| Args: |
| parser: The parser to add the device argument to. |
| schemes: List of device schemes or single scheme to allow. |
| optional: Whether the device is an optional or positional |
| argument; None to auto-determine based on toolset. |
| """ |
| if optional is None: |
| optional = (_GetToolset() == 'brillo') |
| help_strings = [] |
| schemes = list(cros_build_lib.iflatten_instance(schemes)) |
| if commandline.DEVICE_SCHEME_SSH in schemes: |
| help_strings.append('Target a device with [user@]hostname[:port].') |
| if commandline.DEVICE_SCHEME_USB in schemes: |
| help_strings.append('Target removable media with usb://[path].') |
| if commandline.DEVICE_SCHEME_FILE in schemes: |
| help_strings.append('Target a local file with file://path.') |
| parser.add_argument('--device' if optional else 'device', |
| type=commandline.DeviceParser(schemes), |
| help=' '.join(help_strings)) |
| |
| def Run(self): |
| """The command to run.""" |
| raise NotImplementedError() |