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