tools/telemetry/third_party/gsutilz/gslib/commands/cat.py

   1 # -*- coding: utf-8 -*-
   2 # Copyright 2011 Google Inc. All Rights Reserved.
   3 # Copyright 2011, Nexenta Systems Inc.
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the "License");
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #     http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16 """Implementation of Unix-like cat command for cloud storage providers."""
  17
  18 from __future__ import absolute_import
  19
  20 import re
  21
  22 from gslib.cat_helper import CatHelper
  23 from gslib.command import Command
  24 from gslib.command_argument import CommandArgument
  25 from gslib.cs_api_map import ApiSelector
  26 from gslib.exception import CommandException
  27 from gslib.util import NO_MAX
  28
  29 _SYNOPSIS = """
  30   gsutil cat [-h] url...
  31 """
  32
  33 _DETAILED_HELP_TEXT = ("""
  34 <B>SYNOPSIS</B>
  35 """ + _SYNOPSIS + """
  36
  37
  38 <B>DESCRIPTION</B>
  39   The cat command outputs the contents of one or more URLs to stdout.
  40   It is equivalent to doing:
  41
  42     gsutil cp url... -
  43
  44   (The final '-' causes gsutil to stream the output to stdout.)
  45
  46
  47 <B>WARNING: DATA INTEGRITY CHECKING NOT DONE</B>
  48   The gsutil cat command does not compute a checksum of the downloaded data.
  49   Therefore, we recommend that users either perform their own validation of the
  50   output of gsutil cat or use gsutil cp or rsync (both of which perform
  51   integrity checking automatically).
  52
  53
  54 <B>OPTIONS</B>
  55   -h          Prints short header for each object. For example:
  56
  57                 gsutil cat -h gs://bucket/meeting_notes/2012_Feb/*.txt
  58
  59               This would print a header with the object name before the contents
  60               of each text object that matched the wildcard.
  61
  62   -r range    Causes gsutil to output just the specified byte range of the
  63               object. Ranges are can be of these forms:
  64
  65                 start-end (e.g., -r 256-5939)
  66                 start-    (e.g., -r 256-)
  67                 -numbytes (e.g., -r -5)
  68
  69               where offsets start at 0, start-end means to return bytes start
  70               through end (inclusive), start- means to return bytes start
  71               through the end of the object, and -numbytes means to return the
  72               last numbytes of the object. For example:
  73
  74                 gsutil cat -r 256-939 gs://bucket/object
  75
  76               returns bytes 256 through 939, while:
  77
  78                 gsutil cat -r -5 gs://bucket/object
  79
  80               returns the final 5 bytes of the object.
  81 """)
  82
  83
  84 class CatCommand(Command):
  85   """Implementation of gsutil cat command."""
  86
  87   # Command specification. See base class for documentation.
  88   command_spec = Command.CreateCommandSpec(
  89       'cat',
  90       command_name_aliases=[],
  91       usage_synopsis=_SYNOPSIS,
  92       min_args=1,
  93       max_args=NO_MAX,
  94       supported_sub_args='hr:',
  95       file_url_ok=False,
  96       provider_url_ok=False,
  97       urls_start_arg=0,
  98       gs_api_support=[ApiSelector.XML, ApiSelector.JSON],
  99       gs_default_api=ApiSelector.JSON,
 100       argparse_arguments=[
 101           CommandArgument.MakeZeroOrMoreCloudURLsArgument()
 102       ]
 103   )
 104   # Help specification. See help_provider.py for documentation.
 105   help_spec = Command.HelpSpec(
 106       help_name='cat',
 107       help_name_aliases=[],
 108       help_type='command_help',
 109       help_one_line_summary='Concatenate object content to stdout',
 110       help_text=_DETAILED_HELP_TEXT,
 111       subcommand_help_text={},
 112   )
 113
 114   # Command entry point.
 115   def RunCommand(self):
 116     """Command entry point for the cat command."""
 117     show_header = False
 118     request_range = None
 119     start_byte = 0
 120     end_byte = None
 121     if self.sub_opts:
 122       for o, a in self.sub_opts:
 123         if o == '-h':
 124           show_header = True
 125         elif o == '-r':
 126           request_range = a.strip()
 127           range_matcher = re.compile(
 128               '^(?P<start>[0-9]+)-(?P<end>[0-9]*)$|^(?P<endslice>-[0-9]+)$')
 129           range_match = range_matcher.match(request_range)
 130           if not range_match:
 131             raise CommandException('Invalid range (%s)' % request_range)
 132           if range_match.group('start'):
 133             start_byte = long(range_match.group('start'))
 134           if range_match.group('end'):
 135             end_byte = long(range_match.group('end'))
 136           if range_match.group('endslice'):
 137             start_byte = long(range_match.group('endslice'))
 138         else:
 139           self.RaiseInvalidArgumentException()
 140
 141     return CatHelper(self).CatUrlStrings(self.args,
 142                                          show_header=show_header,
 143                                          start_byte=start_byte,
 144                                          end_byte=end_byte)