tools/telemetry/third_party/gsutilz/gslib/addlhelp/apis.py

   1 # -*- coding: utf-8 -*-
   2 # Copyright 2014 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 """Additional help about gsutil's interaction with Cloud Storage APIs."""
  16
  17 from gslib.help_provider import HelpProvider
  18
  19 _DETAILED_HELP_TEXT = ("""
  20 <B>OVERVIEW</B>
  21   Google Cloud Storage offers two APIs: an XML and a JSON API. Gsutil can
  22   interact with both APIs. By default, gsutil versions starting with 4.0
  23   interact with the JSON API. If it is not possible to perform a command using
  24   one of the APIs (for example, the notification command is not supported in
  25   the XML API), gsutil will silently fall back to using the other API. Also,
  26   gsutil will automatically fall back to using the XML API when interacting
  27   with cloud storage providers that only support that API.
  28
  29 <B>CONFIGURING WHICH API IS USED</B>
  30   To use a certain API for interacting with Google Cloud Storage, you can set
  31   the 'prefer_api' variable in the "GSUtil" section of .boto config file to
  32   'xml' or 'json' like so:
  33
  34     prefer_api = json
  35
  36   This will cause gsutil to use that API where possible (falling back to the
  37   other API in cases as noted above). This applies to the gsutil test command
  38   as well; it will run integration tests against the preferred API.
  39
  40 <B>PERFORMANCE AND COST DIFFERENCES BETWEEN APIS</B>
  41   The XML API uses the boto framework.  This framework re-reads downloaded files
  42   to compute an MD5 hash if one is not present. For objects that do not
  43   include MD5 hashes in their metadata (for example Google Cloud Storage
  44   composite objects), this doubles the bandwidth consumed and elapsed time
  45   needed by the download. Therefore, if you are working with composite objects,
  46   it is recommended that you use the default value for prefer_api.
  47
  48   The XML API also requires separate calls to get different object and bucket
  49   metadata fields, such as ACLs or bucket configuration. Thus, using the JSON
  50   API when possible uses fewer operations (and thus has a lower cost).
  51 """)
  52
  53
  54 class CommandOptions(HelpProvider):
  55   """Additional help about gsutil's interaction with Cloud Storage APIs."""
  56
  57   # Help specification. See help_provider.py for documentation.
  58   help_spec = HelpProvider.HelpSpec(
  59       help_name='apis',
  60       help_name_aliases=['XML', 'JSON', 'api', 'force_api', 'prefer_api'],
  61       help_type='additional_help',
  62       help_one_line_summary='Cloud Storage APIs',
  63       help_text=_DETAILED_HELP_TEXT,
  64       subcommand_help_text={},
  65   )
  66