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 89
