Update checked in version of gsutil to version 4.6

gslib/addlhelp/metadata.py

+# -*- coding: utf-8 -*-
 # Copyright 2012 Google Inc. 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.
+"""Additional help about object metadata."""
 
-from gslib.help_provider import HELP_NAME
-from gslib.help_provider import HELP_NAME_ALIASES
-from gslib.help_provider import HELP_ONE_LINE_SUMMARY
+from __future__ import absolute_import
+
 from gslib.help_provider import HelpProvider
-from gslib.help_provider import HELP_TEXT
-from gslib.help_provider import HelpType
-from gslib.help_provider import HELP_TYPE
 
-_detailed_help_text = ("""
+_DETAILED_HELP_TEXT = ("""
 <B>OVERVIEW OF METADATA</B>
   Objects can have associated metadata, which control aspects of how
   GET requests are handled, including Content-Type, Cache-Control,
   Content-Disposition, and Content-Encoding (discussed in more detail in
   the subsections below). In addition, you can set custom metadata that
   can be used by applications (e.g., tagging that particular objects possess
   some property).
 
   There are two ways to set metadata on objects:
 
@@ skipping 10 matching lines @@
 
   - You can set or remove metadata fields from already uploaded objects using
     the gsutil setmeta command. See "gsutil help setmeta".
 
   More details about specific pieces of metadata are discussed below.
 
 
 <B>CONTENT TYPE</B>
   The most commonly set metadata is Content-Type (also known as MIME type),
   which allows browsers to render the object properly.
-  gsutil sets the Content-Type
-  automatically at upload time, based on each filename extension. For
-  example, uploading files with names ending in .txt will set Content-Type
-  to text/plain. If you're running gsutil on Linux or MacOS and would prefer
-  to have content type set based on naming plus content examination, see the
-  use_magicfile configuration variable in the gsutil/boto configuration file
-  (See also "gsutil help config"). In general, using use_magicfile is more
-  robust and configurable, but is not available on Windows.
+  gsutil sets the Content-Type automatically at upload time, based on each
+  filename extension. For example, uploading files with names ending in .txt
+  will set Content-Type to text/plain. If you're running gsutil on Linux or
+  MacOS and would prefer to have content type set based on naming plus content
+  examination, see the use_magicfile configuration variable in the gsutil/boto
+  configuration file (See also "gsutil help config"). In general, using
+  use_magicfile is more robust and configurable, but is not available on
+  Windows.
 
-  If you specify a -h header when uploading content (like the example gsutil
-  command given in the previous section), it overrides the Content-Type that
-  would have been set based on filename extension or content.  This can be
-  useful if the Content-Type detection algorithm doesn't work as desired
-  for some of your files.
+  If you specify a Content-Type header with -h when uploading content (like the
+  example gsutil command given in the previous section), it overrides the
+  Content-Type that would have been set based on filename extension or content.
+  This can be useful if the Content-Type detection algorithm doesn't work as
+  desired for some of your files.
 
   You can also completely suppress content type detection in gsutil, by
   specifying an empty string on the Content-Type header:
 
     gsutil -h 'Content-Type:' cp -r images gs://bucket/images
 
-  In this case, the Google Cloud Storage service will attempt to detect
+  In this case, the Google Cloud Storage service will not attempt to detect
   the content type. In general this approach will work better than using
   filename extension-based content detection in gsutil, because the list of
   filename extensions is kept more current in the server-side content detection
   system than in the Python library upon which gsutil content type detection
   depends. (For example, at the time of writing this, the filename extension
   ".webp" was recognized by the server-side content detection system, but
   not by gsutil.)
 
 
 <B>CACHE-CONTROL</B>
@@ skipping 12 matching lines @@
   one hour.
 
   Note that if you allow caching, at download time you may see older versions
   of objects after uploading a newer replacement object. Note also that because
   objects can be cached at various places on the Internet there is no way to
   force a cached object to expire globally (unlike the way you can force your
   browser to refresh its cache).
 
   Another use of the Cache-Control header is through the "no-transform" value,
   which instructs Google Cloud Storage to not apply any content transformations
-  based on specifics of a download request, such such as removing gzip
-  content-encoding for incompatible clients.
+  based on specifics of a download request, such as removing gzip
+  content-encoding for incompatible clients.  Note that this parameter is only
+  respected by the XML API. The Google Cloud Storage JSON API respects only the
+  no-cache and max-age Cache-Control parameters.
 
 
 <B>CONTENT-ENCODING</B>
   You can specify a Content-Encoding to indicate that an object is compressed
   (for example, with gzip compression) while maintaining its Content-Type.
   You will need to ensure that the files have been compressed using the
   specified Content-Encoding before using gsutil to upload them. Consider the
   following example for Linux:
 
     echo "Highly compressible text" | gzip > foo.txt
@@ skipping 42 matching lines @@
 <B>SETTABLE FIELDS; FIELD VALUES</B>
   You can't set some metadata fields, such as ETag and Content-Length. The
   fields you can set are:
 
   - Cache-Control
   - Content-Disposition
   - Content-Encoding
   - Content-Language
   - Content-MD5
   - Content-Type
-  - Any field starting with X-GOOG-META- (i.e., custom metadata).
+  - Any field starting with a matching Cloud Storage Provider
+    prefix, such as x-goog-meta- (i.e., custom metadata).
 
   Header names are case-insensitive.
 
-  X-GOOG-META- fields can have data set to arbitrary Unicode values. All
+  x-goog-meta- fields can have data set to arbitrary Unicode values. All
   other fields must have ASCII values.
 
 
 <B>VIEWING CURRENTLY SET METADATA</B>
   You can see what metadata is currently set on an object by using:
 
     gsutil ls -L gs://the_bucket/the_object
 """)
 
 
 class CommandOptions(HelpProvider):
   """Additional help about object metadata."""
 
-  help_spec = {
-    # Name of command or auxiliary help info for which this help applies.
-    HELP_NAME : 'metadata',
-    # List of help name aliases.
-    HELP_NAME_ALIASES : ['cache-control', 'caching', 'content type',
-                         'mime type', 'mime', 'type'],
-    # Type of help:
-    HELP_TYPE : HelpType.ADDITIONAL_HELP,
-    # One line summary of this help.
-    HELP_ONE_LINE_SUMMARY : 'Working With Object Metadata',
-    # The full help text.
-    HELP_TEXT : _detailed_help_text,
-  }
+  # Help specification. See help_provider.py for documentation.
+  help_spec = HelpProvider.HelpSpec(
+      help_name='metadata',
+      help_name_aliases=[
+          'cache-control', 'caching', 'content type', 'mime type', 'mime',
+          'type'],
+      help_type='additional_help',
+      help_one_line_summary='Working With Object Metadata',
+      help_text=_DETAILED_HELP_TEXT,
+      subcommand_help_text={},
+  )