• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
17from __future__ import absolute_import
18
19import collections
20from gslib.exception import CommandException
21
22ALL_HELP_TYPES = ['command_help', 'additional_help']
23
24# Constants enforced by SanityCheck
25MAX_HELP_NAME_LEN = 15
26MIN_ONE_LINE_SUMMARY_LEN = 10
27MAX_ONE_LINE_SUMMARY_LEN = 80 - MAX_HELP_NAME_LEN
28
29DESCRIPTION_PREFIX = """
30<B>DESCRIPTION</B>"""
31
32SYNOPSIS_PREFIX = """
33<B>SYNOPSIS</B>"""
34
35
36class 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.
62def 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
86def CreateHelpText(synopsis, description):
87  """Helper for adding help text headers given synopsis and description."""
88  return SYNOPSIS_PREFIX + synopsis + DESCRIPTION_PREFIX + description
89