File: //snap/google-cloud-cli/current/lib/googlecloudsdk/core/resource/resource_topics.py
# -*- coding: utf-8 -*- #
# Copyright 2014 Google LLC. 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.
"""Common resource topic text."""
from __future__ import absolute_import
from __future__ import division
from __future__ import unicode_literals
import pkgutil
import textwrap
from googlecloudsdk import api_lib
from googlecloudsdk.core.resource import resource_printer
from googlecloudsdk.core.resource import resource_transform
import six
from six.moves import range # pylint: disable=redefined-builtin
def ResourceDescription(name):
"""Generates resource help DESCRIPTION help text for name.
This puts common text for the key, formats and projections topics in one
place.
Args:
name: One of ['filter', 'format', 'key', 'projection'].
Raises:
ValueError: If name is not one of the expected topic names.
Returns:
A detailed_help DESCRIPTION markdown string.
"""
description = """\
Most *gcloud* commands return a list of resources on success. By default they
are pretty-printed on the standard output. The
*--format=*_NAME_[_ATTRIBUTES_]*(*_PROJECTION_*)* and
*--filter=*_EXPRESSION_ flags along with projections can be used to format and
change the default output to a more meaningful result.
Use the `--format` flag to change the default output format of a command. \
{see_format}
Use the `--filter` flag to select resources to be listed. {see_filter}
Use resource-keys to reach resource items through a unique path of names from the root. {see_key}
Use projections to list a subset of resource keys in a resource. \
{see_projection}
Note: To refer to a list of fields you can sort, filter, and format by for
each resource, you can run a list command with the format set to `text` or
`json`. For
example, $ gcloud compute instances list --limit=1 --format=text.
To work through an interactive tutorial about using the filter and format
flags instead, see: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/cloud-shell-tutorials&page=editor&tutorial=cloudsdk/tutorial.md
"""
# topic <name> => gcloud topic <command>
topics = {
'filter': 'filters',
'format': 'formats',
'key': 'resource-keys',
'projection': 'projections',
}
if name not in topics:
raise ValueError('Expected one of [{topics}], got [{name}].'.format(
topics=','.join(sorted(topics)), name=name))
see = {}
for topic, command in six.iteritems(topics):
if topic == name:
see[topic] = 'Resource {topic}s are described in detail below.'.format(
topic=topic)
else:
see[topic] = 'For details run $ gcloud topic {command}.'.format(
command=command)
return textwrap.dedent(description).format(see_filter=see['filter'],
see_format=see['format'],
see_key=see['key'],
see_projection=see['projection'])
_DOC_MAIN, _DOC_ARGS, _DOC_ATTRIBUTES, _DOC_EXAMPLE, _DOC_SKIP = range(5)
def _AppendParagraph(lines):
"""Appends paragraph markdown to lines.
Paragraph markdown is used to add paragraphs in nested lists at the list
prevaling indent. _AppendParagraph does not append the markdown if the last
line in lines is already a paragraph markdown.
A line containing only the + character is a paragraph markdown. It renders
a blank line and starts the next paragraph of lines using the prevailing
indent. A blank line would also start a new paragraph but would decrease the
prevailing indent.
Args:
lines: The lines to append to.
"""
if lines and not lines[-1].endswith('\n+\n'):
# The last line in lines is not a paragrpah markdown.
if lines[-1].endswith('\n'):
# Don't append a blank line -- that would decrease the indentation.
lines.append('+\n')
else:
lines.append('\n+\n')
def _AppendLine(lines, line, paragraph):
"""Appends line to lines handling list markdown.
Args:
lines: The lines to append to.
line: The line to append.
paragraph: Start a new paragraph if True.
Returns:
The new paragraph value. This will always be False.
"""
if paragraph:
paragraph = False
_AppendParagraph(lines)
elif lines and not lines[-1].endswith('\n'):
lines.append(' ')
if line.startswith('* ') or line.endswith('::'):
if lines and not lines[-1].endswith('\n'):
lines.append('\n')
lines.append(line)
lines.append('\n')
else:
lines.append(line)
return paragraph
def _ParseFormatDocString(printer):
"""Parses the doc string for printer.
Args:
printer: The doc string will be parsed from this resource format printer.
Returns:
A (description, attributes) tuple:
description - The format description.
attributes - A list of (name, description) tuples, one tuple for each
format-specific attribute.
Example resource printer docstring parsed by this method:
'''This line is skipped. Printer attributes and Example sections optional.
These lines describe the format.
Another description line.
Printer attributes:
attribute-1-name: The description for attribute-1-name.
attribute-N-name: The description for attribute-N-name.
Example:
One or more example lines for the 'For example:' section.
'''
"""
descriptions = []
attributes = []
example = []
if not printer.__doc__:
return '', '', ''
_, _, doc = printer.__doc__.partition('\n')
collect = _DOC_MAIN
attribute = None
attribute_description = []
paragraph = False
for line in textwrap.dedent(doc).split('\n'):
if not line.startswith(' ') and line.endswith(':'):
# The start of a new section.
paragraph = False
if attribute:
# The current attribute description is done.
attributes.append((attribute, ''.join(attribute_description)))
attribute = None
if line == 'Printer attributes:':
# Now collecting Printer attributes: section lines.
collect = _DOC_ATTRIBUTES
elif line == 'Example:':
# Now collecting Example: section lines.
collect = _DOC_EXAMPLE
else:
collect = _DOC_SKIP
elif collect == _DOC_SKIP:
# Only interested in the description body and the Printer args: section.
continue
elif not line:
# Blank line for new paragraph at current indendataion.
paragraph = True
elif collect == _DOC_MAIN:
# The main description line.
paragraph = _AppendLine(descriptions, line, paragraph)
elif line.startswith(' '):
if collect == _DOC_ATTRIBUTES:
# An attribute description line.
paragraph = _AppendLine(attribute_description, line.strip(), paragraph)
elif collect == _DOC_EXAMPLE and line.startswith(' '):
# An example section line.
paragraph = _AppendLine(example, line, paragraph)
else:
# The current attribute description is done.
if attribute:
attributes.append((attribute, ''.join(attribute_description)))
# A new attribute description.
attribute, _, text = line.partition(':')
attribute = attribute.strip()
attribute = attribute.lstrip('*')
attribute_description = [text.strip()]
if attribute:
attributes.append((attribute, ''.join(attribute_description)))
return ''.join(descriptions), attributes, example
def FormatRegistryDescriptions():
"""Returns help markdown for all registered resource printer formats."""
# Generate the printer markdown.
descriptions = ['The formats and format specific attributes are:\n']
for name, printer in sorted(
six.iteritems(resource_printer.GetFormatRegistry())):
description, attributes, example = _ParseFormatDocString(printer)
descriptions.append('\n*{name}*::\n{description}\n'.format(
name=name, description=description))
if attributes:
_AppendParagraph(descriptions)
descriptions.append('The format attributes are:\n\n')
for attribute, description in attributes:
descriptions.append('*{attribute}*:::\n{description}\n'.format(
attribute=attribute, description=description))
descriptions.append(':::\n')
if example:
_AppendParagraph(descriptions)
descriptions.append('For example:\n+\n{example}\n'.format(
example=''.join(example)))
descriptions.append('::\n')
# Generate the "attributes for all printers" markdown.
description, attributes, example = _ParseFormatDocString(
resource_printer.PrinterAttributes)
if attributes:
descriptions.append('\n{description}:\n+\n'.format(
description=description[:-1]))
for attribute, description in attributes:
descriptions.append('*{attribute}*::\n{description}\n'.format(
attribute=attribute, description=description))
if example:
_AppendParagraph(descriptions)
descriptions.append('For example:\n+\n{example}\n'.format(
example=''.join(example)))
descriptions.append('\n')
return ''.join(descriptions)
def _StripUnusedNotation(string):
"""Returns string with Pythonic unused notation stripped."""
if string.startswith('_'):
return string.lstrip('_')
unused = 'unused_'
if string.startswith(unused):
return string[len(unused):]
return string
def _ParseTransformDocString(func):
"""Parses the doc string for func.
Args:
func: The doc string will be parsed from this function.
Returns:
A (description, prototype, args) tuple:
description - The function description.
prototype - The function prototype string.
args - A list of (name, description) tuples, one tuple for each arg.
Example transform function docstring parsed by this method:
'''Transform description. Example sections optional.
These lines are skipped.
Another skipped line.
Args:
r: The resource arg is always sepcified but omitted from the docs.
arg-2-name[=default-2]: The description for arg-2-name.
arg-N-name[=default-N]: The description for arg-N-name.
kwargs: Omitted from the description.
Example:
One or more example lines for the 'For example:' section.
'''
"""
hidden_args = ('kwargs', 'projection', 'r')
if not func.__doc__:
return '', '', '', ''
description, _, doc = func.__doc__.partition('\n')
collect = _DOC_MAIN
arg = None
descriptions = [description]
example = []
args = []
arg_description = []
paragraph = False
for line in textwrap.dedent(doc).split('\n'):
if not line:
paragraph = True
elif line == 'Args:':
# Now collecting Args: section lines.
collect = _DOC_ARGS
paragraph = False
elif line == 'Example:':
# Now collecting Example: section lines.
collect = _DOC_EXAMPLE
paragraph = False
elif collect == _DOC_SKIP:
# Not interested in this line.
continue
elif collect == _DOC_MAIN:
# The main description line.
paragraph = _AppendLine(descriptions, line, paragraph)
elif collect == _DOC_ARGS and line.startswith(' '):
# An arg description line.
paragraph = _AppendLine(arg_description, line, paragraph)
elif collect == _DOC_EXAMPLE and line.startswith(' '):
# An example description line.
paragraph = _AppendLine(example, line[2:], paragraph)
else:
# The current arg description is done.
if arg:
arg = _StripUnusedNotation(arg)
if arg and arg not in hidden_args:
args.append((arg, ' '.join(arg_description)))
if not line.startswith(' ') and line.endswith(':'):
# The start of a new section.
collect = _DOC_SKIP
continue
# A new arg description.
arg, _, text = line.partition(':')
arg = arg.strip()
arg = arg.lstrip('*')
arg_description = [text.strip()]
# Collect the formal arg list with defaults for the function prototype.
import inspect # pylint: disable=g-import-not-at-top, For startup efficiency.
# getfullargspec() may fail in the future if the "func" method passed in has
# kwargs-only arguments, in which case refactoring will be needed. See
# b/287663703 for more details.
argspec = inspect.getfullargspec(func)
default_index_start = len(argspec.args) - len(argspec.defaults or [])
formals = []
for formal_index, formal in enumerate(argspec.args):
if formal:
formal = _StripUnusedNotation(formal)
if formal in hidden_args:
continue
default_index = formal_index - default_index_start
default = argspec.defaults[default_index] if default_index >= 0 else None
if default is not None:
default_display = repr(default).replace("'", '"')
# Trim off the unicode 'u'.
if default_display.startswith('u"'):
default_display = default_display[1:]
if default_display == 'False':
default_display = 'false'
elif default_display == 'True':
default_display = 'true'
formals.append('{formal}={default_display}'.format(
formal=formal, default_display=default_display))
else:
formals.append(formal)
if argspec.varargs:
formals.append(argspec.varargs)
prototype = '({formals})'.format(formals=', '.join(formals))
return ''.join(descriptions), prototype, args, example
def TransformsDescriptions(transforms):
"""Generates resource transform help text markdown for transforms.
Args:
transforms: The transform name=>method symbol table.
Returns:
The resource transform help text markdown for transforms.
"""
descriptions = []
for name, transform in sorted(six.iteritems(transforms)):
description, prototype, args, example = _ParseTransformDocString(transform)
if not description:
continue
descriptions.append('\n\n*{name}*{prototype}::\n{description}'.format(
name=name, prototype=prototype, description=description))
if args:
_AppendParagraph(descriptions)
descriptions.append('The arguments are:\n+\n')
for arg, description in args:
descriptions.append('*```{arg}```*:::\n{description}\n'.format(
arg=arg, description=description))
descriptions.append(':::\n')
if example:
_AppendParagraph(descriptions)
descriptions.append('For example:\n+\n{example}\n'.format(
example=''.join(example)))
descriptions.append('::\n')
return ''.join(descriptions)
def _GetApiTransforms(api):
"""Returns the transforms for api if it has a transforms module."""
if api == 'builtin':
return resource_transform.GetTransforms()
# Include all api_lib.*.transforms modules that have GetTransforms().
method_name = 'GetTransforms'
module_path = 'googlecloudsdk.api_lib.{api}.transforms'.format(api=api)
try:
module = __import__(module_path, fromlist=[method_name])
method = getattr(module, method_name)
return method()
except ImportError:
return None
def TransformRegistryDescriptions():
"""Returns help markdown for all registered resource transforms."""
descriptions = []
apis = set(
[name for _, name, _ in pkgutil.iter_modules(api_lib.__path__) if name])
for api in ['builtin'] + sorted(apis):
transforms = _GetApiTransforms(api)
if transforms:
descriptions.append(
'\nThe {api} transform functions are:\n{desc}\n'.format(
api=api, desc=TransformsDescriptions(transforms)))
return ''.join(descriptions)