Roll multiple files from depot_tools into luci.

client/third_party/depot_tools/subcommand.py

 # Copyright 2013 The Chromium Authors. All rights reserved.
-# Use of this source code is governed under the Apache License, Version 2.0 that
-# can be found in the LICENSE file.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
 
 """Manages subcommands in a script.
 
 Each subcommand should look like this:
   @usage('[pet name]')
   def CMDpet(parser, args):
     '''Prints a pet.
 
     Many people likes pet. This command prints a pet for your pleasure.
     '''
@@ skipping 16 matching lines @@
   - Every function in the specified module with a name starting with 'CMD' will
     be a subcommand.
   - The module's docstring will be used in the default 'help' page.
   - If a command has no docstring, it will not be listed in the 'help' page.
     Useful to keep compatibility commands around or aliases.
   - If a command is an alias to another one, it won't be documented. E.g.:
       CMDoldname = CMDnewcmd
     will result in oldname not being documented but supported and redirecting to
     newcmd. Make it a real function that calls the old function if you want it
     to be documented.
+  - CMDfoo_bar will be command 'foo-bar'.
 """
 
 import difflib
 import sys
 import textwrap
 
 
 def usage(more):
   """Adds a 'usage_more' property to a CMD function."""
   def hook(fn):
@@ skipping 25 matching lines @@
 
 
 def _get_color_module():
   """Returns the colorama module if available.
 
   If so, assumes colors are supported and return the module handle.
   """
   return sys.modules.get('colorama') or sys.modules.get('third_party.colorama')
 
 
+def _function_to_name(name):
+  """Returns the name of a CMD function."""
+  return name[3:].replace('_', '-')
+
+
 class CommandDispatcher(object):
   def __init__(self, module):
     """module is the name of the main python module where to look for commands.
 
     The python builtin variable __name__ MUST be used for |module|. If the
     script is executed in the form 'python script.py', __name__ == '__main__'
     and sys.modules['script'] doesn't exist. On the other hand if it is unit
     tested, __main__ will be the unit test's module so it has to reference to
     itself with 'script'. __name__ always match the right value.
     """
     self.module = sys.modules[module]
 
   def enumerate_commands(self):
     """Returns a dict of command and their handling function.
 
     The commands must be in the '__main__' modules. To import a command from a
     submodule, use:
       from mysubcommand import CMDfoo
 
     Automatically adds 'help' if not already defined.
 
+    Normalizes '_' in the commands to '-'.
+
     A command can be effectively disabled by defining a global variable to None,
     e.g.:
       CMDhelp = None
     """
     cmds = dict(
-        (fn[3:], getattr(self.module, fn))
-        for fn in dir(self.module) if fn.startswith('CMD'))
+        (_function_to_name(name), getattr(self.module, name))
+        for name in dir(self.module) if name.startswith('CMD'))
     cmds.setdefault('help', CMDhelp)
     return cmds
 
-  def find_nearest_command(self, name):
-    """Retrieves the function to handle a command.
+  def find_nearest_command(self, name_asked):
+    """Retrieves the function to handle a command as supplied by the user.
 
-    It automatically tries to guess the intended command by handling typos or
-    incomplete names.
+    It automatically tries to guess the _intended command_ by handling typos
+    and/or incomplete names.
     """
     commands = self.enumerate_commands()
-    if name in commands:
-      return commands[name]
+    if name_asked in commands:
+      return commands[name_asked]
 
     # An exact match was not found. Try to be smart and look if there's
     # something similar.
-    commands_with_prefix = [c for c in commands if c.startswith(name)]
+    commands_with_prefix = [c for c in commands if c.startswith(name_asked)]
     if len(commands_with_prefix) == 1:
       return commands[commands_with_prefix[0]]
 
     # A #closeenough approximation of levenshtein distance.
     def close_enough(a, b):
       return difflib.SequenceMatcher(a=a, b=b).ratio()
 
     hamming_commands = sorted(
-        ((close_enough(c, name), c) for c in commands),
+        ((close_enough(c, name_asked), c) for c in commands),
         reverse=True)
     if (hamming_commands[0][0] - hamming_commands[1][0]) < 0.3:
       # Too ambiguous.
       return
 
     if hamming_commands[0][0] < 0.8:
       # Not similar enough. Don't be a fool and run a random command.
       return
 
     return commands[hamming_commands[0][1]]
 
   def _gen_commands_list(self):
     """Generates the short list of supported commands."""
     commands = self.enumerate_commands()
     docs = sorted(
-        (name, self._create_command_summary(name, handler))
-        for name, handler in commands.iteritems())
+        (cmd_name, self._create_command_summary(cmd_name, handler))
+        for cmd_name, handler in commands.iteritems())
     # Skip commands without a docstring.
     docs = [i for i in docs if i[1]]
     # Then calculate maximum length for alignment:
     length = max(len(c) for c in commands)
 
     # Look if color is supported.
     colors = _get_color_module()
     green = reset = ''
     if colors:
       green = colors.Fore.GREEN
       reset = colors.Fore.RESET
     return (
         'Commands are:\n' +
         ''.join(
-            '  %s%-*s%s %s\n' % (green, length, name, reset, doc)
-            for name, doc in docs))
+            '  %s%-*s%s %s\n' % (green, length, cmd_name, reset, doc)
+            for cmd_name, doc in docs))
 
   def _add_command_usage(self, parser, command):
     """Modifies an OptionParser object with the function's documentation."""
-    name = command.__name__[3:]
-    if name == 'help':
-      name = '<command>'
+    cmd_name = _function_to_name(command.__name__)
+    if cmd_name == 'help':
+      cmd_name = '<command>'
       # Use the module's docstring as the description for the 'help' command if
       # available.
       parser.description = (self.module.__doc__ or '').rstrip()
       if parser.description:
         parser.description += '\n\n'
       parser.description += self._gen_commands_list()
       # Do not touch epilog.
     else:
       # Use the command's docstring if available. For commands, unlike module
       # docstring, realign.
       lines = (command.__doc__ or '').rstrip().splitlines()
       if lines[:1]:
         rest = textwrap.dedent('\n'.join(lines[1:]))
         parser.description = '\n'.join((lines[0], rest))
       else:
-        parser.description = lines[0]
+        parser.description = lines[0] if lines else ''
       if parser.description:
         parser.description += '\n'
       parser.epilog = getattr(command, 'epilog', None)
       if parser.epilog:
         parser.epilog = '\n' + parser.epilog.strip() + '\n'
 
     more = getattr(command, 'usage_more', '')
-    parser.set_usage(
-        'usage: %%prog %s [options]%s' % (name, '' if not more else ' ' + more))
+    extra = '' if not more else ' ' + more
+    parser.set_usage('usage: %%prog %s [options]%s' % (cmd_name, extra))
 
   @staticmethod
-  def _create_command_summary(name, command):
-    """Creates a oneline summary from the command's docstring."""
-    if name != command.__name__[3:]:
-      # Skip aliases.
+  def _create_command_summary(cmd_name, command):
+    """Creates a oneliner summary from the command's docstring."""
+    if cmd_name != _function_to_name(command.__name__):
+      # Skip aliases. For example using at module level:
+      # CMDfoo = CMDbar
       return ''
     doc = command.__doc__ or ''
     line = doc.split('\n', 1)[0].rstrip('.')
     if not line:
       return line
     return (line[0].lower() + line[1:]).strip()
 
   def execute(self, parser, args):
     """Dispatches execution to the right command.
 
@@ skipping 24 matching lines @@
         return command(parser, args[1:])
 
     cmdhelp = self.enumerate_commands().get('help')
     if cmdhelp:
       # Not a known command. Default to help.
       self._add_command_usage(parser, cmdhelp)
       return cmdhelp(parser, args)
 
     # Nothing can be done.
     return 2