class Formats(base.Command): """Resource formats supplementary help.""" def Run(self, args): self.cli.Execute(args.command_path[1:] + ['--document=style=topic']) return None detailed_help = { 'DESCRIPTION': textwrap.dedent("""\ {description} ### Formats A format expression has 3 parts: _NAME_:: _name_ _ATTRIBUTES_:: *[* [no-]_attribute-name_[=_value_] [, ... ] *]* _PROJECTION_:: *(* _resource-key_ [, ...] *)* _NAME_ is required, _ATTRIBUTES_ are optional, and _PROJECTIONS_ may be required for some formats. Unknown attribute names are silently ignored. Each *gcloud* *list* command has a default format expression. The *--format* flag can alter or replace the default. For example, --format='[box]' adds box decorations to a default table, and --format=json lists the resource in *json* format. {format_registry} """).format( description=resource_topics.ResourceDescription('format'), format_registry=resource_topics.FormatRegistryDescriptions()), 'EXAMPLES': """\ List a table of compute instance resources sorted by *name* with box decorations and title *Instances*: $ gcloud compute instances list --format='table[box,title=Instances](name:sort=1, zone:title=zone, status)' List the disk interfaces for all compute instances as a compact comma separated list: $ gcloud compute instances list --format='value(disks[].interface.list())' List the URIs for all compute instances: $ gcloud compute instances list --format='value(uri())' List the project authenticated user email address: $ gcloud info --format='value(config.account)' """, }
class Formats(base.TopicCommand): """Resource formats supplementary help.""" detailed_help = { 'DESCRIPTION': textwrap.dedent("""\ {description} ### Formats A format expression is used to change the default output format of a command. Many output formats are available; some for pretty printing human-readable output and others for returning machine-readable output. A format expression has 3 parts: _NAME_:: _name_ _ATTRIBUTES_:: *[* [no-]_attribute-name_[=_value_] [, ... ] *]* _PROJECTION_:: *(* _resource-key_ [, ...] *)* _NAME_ is required, _ATTRIBUTES_ are optional, and _PROJECTIONS_ may be required for some formats. Unknown attribute names are silently ignored. Each *gcloud* *list* command has a default format expression. The *--format* flag can alter or replace the default. For example, --format='[box]' adds box decorations to a default table, and --format=json lists the resource in *json* format. {format_registry} """).format( description=resource_topics.ResourceDescription('format'), format_registry=resource_topics.FormatRegistryDescriptions()), 'EXAMPLES': """\ List a table of compute instance resources sorted by *name* with box decorations and title *Instances*: $ gcloud compute instances list --format='table[box,title=Instances](name:sort=1, zone:label=zone, status)' List a nested table of the quotas of a region: $ gcloud compute regions describe us-central1 --format="table(quotas:format='table(metric,limit,usage)')" Print a flattened list of global quotas in CSV format: $ gcloud compute project-info describe --flatten='quotas[]' --format='csv(quotas.metric,quotas.limit,quotas.usage)' List the disk interfaces for all compute instances as a compact comma separated list: $ gcloud compute instances list --format='value(disks[].interface.list())' List the URIs for all compute instances: $ gcloud compute instances list --format='value(uri())' List the project authenticated user email address: $ gcloud info --format='value(config.account)' List resources filtered on repeated fields by projecting subfields on a repeated message: $ gcloud alpha genomics readgroupsets list --format 'default(readGroups[].name)' Return the scope of the current instance: $ gcloud compute zones list --format="value(selfLink.scope())" selfLink is a fully qualified name. (e.g. 'https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a') The previous example returns a list of just the names of each zone (e.g. 'us-central1-a'). This is because selfLink.scope() grabs the last part of the URL segment. To extract selfLink starting from /projects and return the scope of the current instance: $ gcloud compute zones list --format="value(selfLink.scope(projects))" List all scopes enabled for a Compute Engine instance and flatten the multi-valued resource: $ gcloud compute instances list --format="flattened(name,serviceAccounts[].email,serviceAccounts[].scopes[].basename())" Display a multi-valued resource's service account keys with the corresponding service account, extracting just the first '/' delimited part with segment(0): $ gcloud iam service-accounts keys list --iam-account [email protected] --project test-minutia-123 --format="table(name.scope(serviceAccounts).segment(0):label='service Account',name.scope(keys):label='keyID',validAfterTime)" The last example returns a table with service account names without their full paths, keyID and validity. """, }
def testFormatRegistryDescriptions(self): class ComplexPrinter(object): """This line should be skipped. This line describes the complex format. It needs a few lines of details. Printer attributes: ellipse: Draws an ellipse around the output. no-bar: Eliminates bar from the foo. Attributes: _rows: This line should not be seen. """ class DefaultPrinter(ComplexPrinter): """An alias for YamlPrinter. An alias for the yaml format. """ class NonePrinter(object): """Disables formatted output. Disables formatted output. """ def __new__(cls, **unused_kwargs): return None class SimplePrinter(object): """This line should be skipped. This line describes the simple format. """ registry = { 'complex': ComplexPrinter, 'default': DefaultPrinter, 'none': NonePrinter, 'simple': SimplePrinter, } self.StartObjectPatch(resource_printer, 'GetFormatRegistry').side_effect = [registry] expected = """\ The formats and format specific attributes are: *complex*:: This line describes the complex format. It needs a few lines of details. + The format attributes are: *ellipse*::: Draws an ellipse around the output. *no-bar*::: Eliminates bar from the foo. *default*:: An alias for the yaml format. *none*:: Disables formatted output. *simple*:: This line describes the simple format. All formats have these attributes: + *disable*:: Disables formatted output and does not consume the resources. *json-decode*:: Decodes string values that are JSON compact encodings of list and dictionary objects. This may become the default. *pager*:: If True, sends output to a pager. *private*:: Disables log file output. Use this for sensitive resource data that should not be displayed in log files. Explicit command line IO redirection overrides this attribute. *transforms*:: Apply projection transforms to the resource values. The default is format specific. Use *no-transforms* to disable. """ actual = resource_topics.FormatRegistryDescriptions() self.assertMultiLineEqual(expected, actual)