tools/telemetry/third_party/gsutilz/gslib/help_provider.py

   1 # -*- coding: utf-8 -*-
   2 # Copyright 2012 Google Inc. All Rights Reserved.
   3 #
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at
   7 #
   8 #     http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15 """Module defining help types and providers for gsutil commands."""
  16
  17 from __future__ import absolute_import
  18
  19 import collections
  20 from gslib.exception import CommandException
  21
  22 ALL_HELP_TYPES = ['command_help', 'additional_help']
  23
  24 # Constants enforced by SanityCheck
  25 MAX_HELP_NAME_LEN = 15
  26 MIN_ONE_LINE_SUMMARY_LEN = 10
  27 MAX_ONE_LINE_SUMMARY_LEN = 80 - MAX_HELP_NAME_LEN
  28
  29 DESCRIPTION_PREFIX = """
  30 <B>DESCRIPTION</B>"""
  31
  32 SYNOPSIS_PREFIX = """
  33 <B>SYNOPSIS</B>"""
  34
  35
  36 class HelpProvider(object):
  37   """Interface for providing help."""
  38
  39   # Each subclass of HelpProvider define a property named 'help_spec' that is
  40   # an instance of the following class.
  41   HelpSpec = collections.namedtuple('HelpSpec', [
  42       # Name of command or auxiliary help info for which this help applies.
  43       'help_name',
  44       # List of help name aliases.
  45       'help_name_aliases',
  46       # Type of help.
  47       'help_type',
  48       # One line summary of this help.
  49       'help_one_line_summary',
  50       # The full help text.
  51       'help_text',
  52       # Help text for subcommands of the command's help being specified.
  53       'subcommand_help_text',
  54   ])
  55
  56   # Each subclass must override this with an instance of HelpSpec.
  57   help_spec = None
  58
  59
  60 # This is a static helper instead of a class method because the help loader
  61 # (gslib.commands.help._LoadHelpMaps()) operates on classes not instances.
  62 def SanityCheck(help_provider, help_name_map):
  63   """Helper for checking that a HelpProvider has minimally adequate content."""
  64   # Sanity check the content.
  65   assert (len(help_provider.help_spec.help_name) > 1
  66           and len(help_provider.help_spec.help_name) < MAX_HELP_NAME_LEN)
  67   for hna in help_provider.help_spec.help_name_aliases:
  68     assert hna
  69   one_line_summary_len = len(help_provider.help_spec.help_one_line_summary)
  70   assert (one_line_summary_len > MIN_ONE_LINE_SUMMARY_LEN
  71           and one_line_summary_len < MAX_ONE_LINE_SUMMARY_LEN)
  72   assert len(help_provider.help_spec.help_text) > 10
  73
  74   # Ensure there are no dupe help names or aliases across commands.
  75   name_check_list = [help_provider.help_spec.help_name]
  76   name_check_list.extend(help_provider.help_spec.help_name_aliases)
  77   for name_or_alias in name_check_list:
  78     if help_name_map.has_key(name_or_alias):
  79       raise CommandException(
  80           'Duplicate help name/alias "%s" found while loading help from %s. '
  81           'That name/alias was already taken by %s' % (
  82               name_or_alias, help_provider.__module__,
  83               help_name_map[name_or_alias].__module__))
  84
  85
  86 def CreateHelpText(synopsis, description):
  87   """Helper for adding help text headers given synopsis and description."""
  88   return SYNOPSIS_PREFIX + synopsis + DESCRIPTION_PREFIX + description