Added gsutil/gslib to depot_tools/third_party

third_party/gsutil/gslib/help_provider.py

+# Copyright 2012 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from gslib.exception import CommandException
+
+class HelpType(object):
+  COMMAND_HELP = 'command_help'
+  ADDITIONAL_HELP = 'additional_help'
+
+ALL_HELP_TYPES = [HelpType.COMMAND_HELP, HelpType.ADDITIONAL_HELP]
+
+# help_spec key constants.
+HELP_NAME = 'help_name'
+HELP_NAME_ALIASES = 'help_name_aliases'
+HELP_TYPE = 'help_type'
+HELP_ONE_LINE_SUMMARY = 'help_one_line_summary'
+HELP_TEXT = 'help_text'
+
+# Constants enforced by SanityCheck
+MAX_HELP_NAME_LEN = 15
+MIN_ONE_LINE_SUMMARY_LEN = 10
+MAX_ONE_LINE_SUMMARY_LEN = 80 - MAX_HELP_NAME_LEN
+
+REQUIRED_SPEC_KEYS = [HELP_NAME, HELP_NAME_ALIASES, HELP_TYPE,
+                      HELP_ONE_LINE_SUMMARY, HELP_TEXT]
+
+class HelpProvider(object):
+  """Interface for providing help."""
+
+  # Each subclass must define the following map.
+  help_spec = {
+    # Name of command or auxiliary help info for which this help applies.
+    HELP_NAME : None,
+    # List of help name aliases.
+    HELP_NAME_ALIASES : None,
+    # HelpType.
+    HELP_TYPE : None,
+    # One line summary of this help.
+    HELP_ONE_LINE_SUMMARY : None,
+    # The full help text.
+    HELP_TEXT : None,
+  }
+
+# This is a static helper instead of a class method because the help loader
+# (gslib.commands.help._LoadHelpMaps()) operates on classes not instances.
+def SanityCheck(help_provider, help_name_map):
+  """Helper for checking that a HelpProvider has minimally adequate content."""
+  for k in REQUIRED_SPEC_KEYS:
+    if k not in help_provider.help_spec or help_provider.help_spec[k] is None:
+      raise CommandException('"%s" help implementation is missing %s '
+                             'specification' % (help_provider.help_name, k))
+  # Sanity check the content.
+  assert (len(help_provider.help_spec[HELP_NAME]) > 1
+          and len(help_provider.help_spec[HELP_NAME]) < MAX_HELP_NAME_LEN)
+  for hna in help_provider.help_spec[HELP_NAME_ALIASES]:
+    assert len(hna) > 0
+  one_line_summary_len = len(help_provider.help_spec[HELP_ONE_LINE_SUMMARY])
+  assert (one_line_summary_len > MIN_ONE_LINE_SUMMARY_LEN
+          and one_line_summary_len < MAX_ONE_LINE_SUMMARY_LEN)
+  assert len(help_provider.help_spec[HELP_TEXT]) > 10
+
+  # Ensure there are no dupe help names or aliases across commands.
+  name_check_list = [help_provider.help_spec[HELP_NAME]]
+  name_check_list.extend(help_provider.help_spec[HELP_NAME_ALIASES])
+  for name_or_alias in name_check_list:
+    if help_name_map.has_key(name_or_alias):
+      raise CommandException(
+          'Duplicate help name/alias "%s" found while loading help from %s. '
+          'That name/alias was already taken by %s' % (name_or_alias,
+          help_provider.__module__, help_name_map[name_or_alias].__module__))