src/third_party/chromite/cros/__init__.py

   1 # Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
   2 # Use of this source code is governed by a BSD-style license that can be
   3 # found in the LICENSE file.
   4
   5 """Module that contains meta-logic related to Cros Commands.
   6
   7 This module contains two important definitions used by all commands.
   8
   9   CrosCommand: The parent class of all cros commands.
  10   CommandDecorator: Decorator that must be used to ensure that the command shows
  11     up in _commands and is discoverable by cros.
  12 """
  13
  14 from __future__ import print_function
  15
  16
  17 _commands = dict()
  18
  19
  20 class InvalidCommandError(Exception):
  21   """Error that occurs when command class fails sanity checks."""
  22   pass
  23
  24
  25 def CommandDecorator(command_name):
  26   """Decorator that sanity checks and adds class to list of usable commands."""
  27
  28   def InnerCommandDecorator(original_class):
  29     """"Inner Decorator that actually wraps the class."""
  30     if not hasattr(original_class, '__doc__'):
  31       raise InvalidCommandError('All handlers must have docstrings: %s' %
  32                                 original_class)
  33
  34     if not issubclass(original_class, CrosCommand):
  35       raise InvalidCommandError('All Commands must derive from CrosCommand: '
  36                                 '%s' % original_class)
  37
  38     _commands[command_name] = original_class
  39     original_class.command_name = command_name
  40
  41     return original_class
  42
  43   return InnerCommandDecorator
  44
  45
  46 class CrosCommand(object):
  47   """All CrosCommands must derive from this class.
  48
  49   This class provides the abstract interface for all Cros Commands. When
  50   designing a new command, you must sub-class from this class and use the
  51   CommandDecorator decorator. You must specify a class docstring as that will be
  52   used as the usage for the sub-command.
  53
  54   In addition your command should implement AddParser which is passed in a
  55   parser that you can add your own custom arguments. See argparse for more
  56   information.
  57   """
  58   # Indicates whether command stats should be uploaded for this command.
  59   # Override to enable command stats uploading.
  60   upload_stats = False
  61   # We set the default timeout to 1 second, to prevent overly long waits for
  62   # commands to complete.  From manual tests, stat uploads usually take
  63   # between 0.35s-0.45s in MTV.
  64   upload_stats_timeout = 1
  65
  66   # Indicates whether command uses cache related commandline options.
  67   use_caching_options = False
  68
  69   def __init__(self, options):
  70     self.options = options
  71
  72   @classmethod
  73   def AddParser(cls, parser):
  74     """Add arguments for this command to the parser."""
  75     parser.set_defaults(cros_class=cls)
  76
  77   def Run(self):
  78     """The command to run."""
  79     raise NotImplementedError()