Mike Frysinger | e58c0e2 | 2017-10-04 15:43:30 -0400 | [diff] [blame] | 1 | # -*- coding: utf-8 -*- |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 2 | # Copyright (c) 2012 The Chromium OS Authors. All rights reserved. |
| 3 | # Use of this source code is governed by a BSD-style license that can be |
| 4 | # found in the LICENSE file. |
| 5 | |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 6 | """Module that contains meta-logic related to CLI commands. |
| 7 | |
David Pursell | f1c27c1 | 2015-03-18 09:51:38 -0700 | [diff] [blame] | 8 | This module contains two important definitions used by all commands: |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 9 | CliCommand: The parent class of all CLI commands. |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 10 | CommandDecorator: Decorator that must be used to ensure that the command shows |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 11 | up in |_commands| and is discoverable. |
David Pursell | f1c27c1 | 2015-03-18 09:51:38 -0700 | [diff] [blame] | 12 | |
| 13 | Commands can be either imported directly or looked up using this module's |
| 14 | ListCommands() function. |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 15 | """ |
| 16 | |
Mike Frysinger | 383367e | 2014-09-16 15:06:17 -0400 | [diff] [blame] | 17 | from __future__ import print_function |
| 18 | |
Alex Klein | 665aa07 | 2019-12-12 15:13:53 -0700 | [diff] [blame] | 19 | import importlib |
David Pursell | f1c27c1 | 2015-03-18 09:51:38 -0700 | [diff] [blame] | 20 | import os |
| 21 | |
Aviv Keshet | b7519e1 | 2016-10-04 00:50:00 -0700 | [diff] [blame] | 22 | from chromite.lib import constants |
David Pursell | f80b8c5 | 2015-04-03 12:46:45 -0700 | [diff] [blame] | 23 | from chromite.lib import commandline |
| 24 | from chromite.lib import cros_build_lib |
Ralph Nathan | 6993125 | 2015-04-14 16:49:21 -0700 | [diff] [blame] | 25 | from chromite.lib import cros_logging as logging |
David Pursell | f1c27c1 | 2015-03-18 09:51:38 -0700 | [diff] [blame] | 26 | |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 27 | |
David Pursell | c7ba784 | 2015-07-08 10:48:41 -0700 | [diff] [blame] | 28 | # Paths for finding and importing subcommand modules. |
| 29 | _SUBCOMMAND_MODULE_DIRECTORY = os.path.join(os.path.dirname(__file__), 'cros') |
| 30 | _SUBCOMMAND_MODULE_PREFIX = 'cros_' |
| 31 | |
| 32 | |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 33 | _commands = dict() |
| 34 | |
| 35 | |
Ralph Nathan | 6993125 | 2015-04-14 16:49:21 -0700 | [diff] [blame] | 36 | def UseProgressBar(): |
| 37 | """Determine whether the progress bar is to be used or not. |
| 38 | |
| 39 | We only want the progress bar to display for the brillo commands which operate |
| 40 | at logging level NOTICE. If the user wants to see the noisy output, then they |
| 41 | can execute the command at logging level INFO or DEBUG. |
| 42 | """ |
| 43 | return logging.getLogger().getEffectiveLevel() == logging.NOTICE |
| 44 | |
| 45 | |
Mike Frysinger | 1a47081 | 2019-11-07 01:19:17 -0500 | [diff] [blame] | 46 | def ImportCommand(name): |
| 47 | """Directly import the specified subcommand. |
| 48 | |
| 49 | This method imports the module which must contain the single subcommand. When |
| 50 | the module is loaded, the declared command (those that use CommandDecorator) |
| 51 | will automatically get added to |_commands|. |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 52 | |
| 53 | Args: |
Mike Frysinger | 1a47081 | 2019-11-07 01:19:17 -0500 | [diff] [blame] | 54 | name: The subcommand to load. |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 55 | |
| 56 | Returns: |
Mike Frysinger | 1a47081 | 2019-11-07 01:19:17 -0500 | [diff] [blame] | 57 | A reference to the subcommand class. |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 58 | """ |
Mike Frysinger | 1a47081 | 2019-11-07 01:19:17 -0500 | [diff] [blame] | 59 | module_path = os.path.join(_SUBCOMMAND_MODULE_DIRECTORY, |
| 60 | 'cros_%s' % (name.replace('-', '_'),)) |
| 61 | import_path = os.path.relpath(os.path.realpath(module_path), |
| 62 | os.path.dirname(constants.CHROMITE_DIR)) |
Alex Klein | 665aa07 | 2019-12-12 15:13:53 -0700 | [diff] [blame] | 63 | module_parts = import_path.split(os.path.sep) |
| 64 | importlib.import_module('.'.join(module_parts)) |
Mike Frysinger | 1a47081 | 2019-11-07 01:19:17 -0500 | [diff] [blame] | 65 | return _commands[name] |
David Pursell | f1c27c1 | 2015-03-18 09:51:38 -0700 | [diff] [blame] | 66 | |
| 67 | |
David Pursell | c7ba784 | 2015-07-08 10:48:41 -0700 | [diff] [blame] | 68 | def ListCommands(): |
Mike Frysinger | 1a47081 | 2019-11-07 01:19:17 -0500 | [diff] [blame] | 69 | """Return the set of available subcommands. |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 70 | |
Mike Frysinger | 1a47081 | 2019-11-07 01:19:17 -0500 | [diff] [blame] | 71 | We assume that there is a direct one-to-one relationship between the module |
| 72 | name on disk and the command that module implements. We assume this as a |
| 73 | performance requirement (to avoid importing every subcommand every time even |
| 74 | though we'd only ever run a single one), and to avoid 3rd party module usage |
| 75 | in one subcommand breaking all other subcommands (not a great solution). |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 76 | """ |
Mike Frysinger | 1a47081 | 2019-11-07 01:19:17 -0500 | [diff] [blame] | 77 | # Filenames use underscores due to python naming limitations, but subcommands |
| 78 | # use dashes as they're easier for humans to type. |
| 79 | # Strip off the leading "cros_" and the trailing ".py". |
| 80 | return set(x[5:-3].replace('_', '-') |
| 81 | for x in os.listdir(_SUBCOMMAND_MODULE_DIRECTORY) |
| 82 | if (x.startswith(_SUBCOMMAND_MODULE_PREFIX) and x.endswith('.py') |
| 83 | and not x.endswith('_unittest.py'))) |
David Pursell | f1c27c1 | 2015-03-18 09:51:38 -0700 | [diff] [blame] | 84 | |
| 85 | |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 86 | class InvalidCommandError(Exception): |
| 87 | """Error that occurs when command class fails sanity checks.""" |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 88 | |
| 89 | |
| 90 | def CommandDecorator(command_name): |
| 91 | """Decorator that sanity checks and adds class to list of usable commands.""" |
| 92 | |
| 93 | def InnerCommandDecorator(original_class): |
Mike Frysinger | 07475fa | 2019-08-01 14:44:55 -0400 | [diff] [blame] | 94 | """Inner Decorator that actually wraps the class.""" |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 95 | if not hasattr(original_class, '__doc__'): |
| 96 | raise InvalidCommandError('All handlers must have docstrings: %s' % |
| 97 | original_class) |
| 98 | |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 99 | if not issubclass(original_class, CliCommand): |
| 100 | raise InvalidCommandError('All Commands must derive from CliCommand: %s' % |
| 101 | original_class) |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 102 | |
| 103 | _commands[command_name] = original_class |
Ryan Cui | 47f80e4 | 2013-04-01 19:01:54 -0700 | [diff] [blame] | 104 | original_class.command_name = command_name |
| 105 | |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 106 | return original_class |
| 107 | |
| 108 | return InnerCommandDecorator |
| 109 | |
| 110 | |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 111 | class CliCommand(object): |
| 112 | """All CLI commands must derive from this class. |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 113 | |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 114 | This class provides the abstract interface for all CLI commands. When |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 115 | designing a new command, you must sub-class from this class and use the |
| 116 | CommandDecorator decorator. You must specify a class docstring as that will be |
| 117 | used as the usage for the sub-command. |
| 118 | |
| 119 | In addition your command should implement AddParser which is passed in a |
| 120 | parser that you can add your own custom arguments. See argparse for more |
| 121 | information. |
| 122 | """ |
Ryo Hashimoto | 8bc997b | 2014-01-22 18:46:17 +0900 | [diff] [blame] | 123 | # Indicates whether command uses cache related commandline options. |
| 124 | use_caching_options = False |
| 125 | |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 126 | def __init__(self, options): |
| 127 | self.options = options |
| 128 | |
| 129 | @classmethod |
| 130 | def AddParser(cls, parser): |
| 131 | """Add arguments for this command to the parser.""" |
David Pursell | ffb9004 | 2015-03-23 09:21:41 -0700 | [diff] [blame] | 132 | parser.set_defaults(command_class=cls) |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 133 | |
David Pursell | f80b8c5 | 2015-04-03 12:46:45 -0700 | [diff] [blame] | 134 | @classmethod |
David Pursell | c7ba784 | 2015-07-08 10:48:41 -0700 | [diff] [blame] | 135 | def AddDeviceArgument(cls, parser, schemes=commandline.DEVICE_SCHEME_SSH): |
David Pursell | f80b8c5 | 2015-04-03 12:46:45 -0700 | [diff] [blame] | 136 | """Add a device argument to the parser. |
| 137 | |
David Pursell | c7ba784 | 2015-07-08 10:48:41 -0700 | [diff] [blame] | 138 | This standardizes the help message across all subcommands. |
David Pursell | f80b8c5 | 2015-04-03 12:46:45 -0700 | [diff] [blame] | 139 | |
| 140 | Args: |
| 141 | parser: The parser to add the device argument to. |
| 142 | schemes: List of device schemes or single scheme to allow. |
David Pursell | f80b8c5 | 2015-04-03 12:46:45 -0700 | [diff] [blame] | 143 | """ |
David Pursell | f80b8c5 | 2015-04-03 12:46:45 -0700 | [diff] [blame] | 144 | help_strings = [] |
| 145 | schemes = list(cros_build_lib.iflatten_instance(schemes)) |
| 146 | if commandline.DEVICE_SCHEME_SSH in schemes: |
Mike Frysinger | 7163c3a | 2018-02-08 16:45:10 -0500 | [diff] [blame] | 147 | help_strings.append('Target a device with [user@]hostname[:port]. ' |
| 148 | 'IPv4/IPv6 addresses are allowed, but IPv6 must ' |
| 149 | 'use brackets (e.g. [::1]).') |
David Pursell | f80b8c5 | 2015-04-03 12:46:45 -0700 | [diff] [blame] | 150 | if commandline.DEVICE_SCHEME_USB in schemes: |
| 151 | help_strings.append('Target removable media with usb://[path].') |
Alex Klein | e83d86c | 2019-12-11 15:17:31 -0700 | [diff] [blame^] | 152 | if commandline.DEVICE_SCHEME_SERVO in schemes: |
| 153 | help_strings.append('Target a servo by port or serial number with ' |
| 154 | 'servo:port[:port] or servo:serial:serial-number. ' |
| 155 | 'e.g. servo:port:1234 or servo:serial:C1230024192.') |
David Pursell | f80b8c5 | 2015-04-03 12:46:45 -0700 | [diff] [blame] | 156 | if commandline.DEVICE_SCHEME_FILE in schemes: |
| 157 | help_strings.append('Target a local file with file://path.') |
David Pursell | c7ba784 | 2015-07-08 10:48:41 -0700 | [diff] [blame] | 158 | parser.add_argument('device', |
David Pursell | f80b8c5 | 2015-04-03 12:46:45 -0700 | [diff] [blame] | 159 | type=commandline.DeviceParser(schemes), |
| 160 | help=' '.join(help_strings)) |
| 161 | |
Brian Harring | 984988f | 2012-10-10 22:53:30 -0700 | [diff] [blame] | 162 | def Run(self): |
| 163 | """The command to run.""" |
| 164 | raise NotImplementedError() |