tools/telemetry/third_party/gsutilz/gslib/bucket_listing_ref.py

   1 # -*- coding: utf-8 -*-
   2 # Copyright 2012 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 """Classes for cloud/file references yielded by gsutil iterators."""
  16
  17 from __future__ import absolute_import
  18
  19
  20 class BucketListingRef(object):
  21   """Base class for a reference to one fully expanded iterator result.
  22
  23   This allows polymorphic iteration over wildcard-iterated URLs.  The
  24   reference contains a fully expanded URL string containing no wildcards and
  25   referring to exactly one entity (if a wildcard is contained, it is assumed
  26   this is part of the raw string and should never be treated as a wildcard).
  27
  28   Each reference represents a Bucket, Object, or Prefix.  For filesystem URLs,
  29   Objects represent files and Prefixes represent directories.
  30
  31   The root_object member contains the underlying object as it was retrieved.
  32   It is populated by the calling iterator, which may only request certain
  33   fields to reduce the number of server requests.
  34
  35   For filesystem URLs, root_object is not populated.
  36   """
  37
  38   class _BucketListingRefType(object):
  39     """Enum class for describing BucketListingRefs."""
  40     BUCKET = 'bucket'  # Cloud bucket
  41     OBJECT = 'object'  # Cloud object or filesystem file
  42     PREFIX = 'prefix'  # Cloud bucket subdir or filesystem directory
  43
  44   @property
  45   def url_string(self):
  46     return self._url_string
  47
  48   @property
  49   def type_name(self):
  50     return self._ref_type
  51
  52   def IsBucket(self):
  53     return self._ref_type == self._BucketListingRefType.BUCKET
  54
  55   def IsObject(self):
  56     return self._ref_type == self._BucketListingRefType.OBJECT
  57
  58   def IsPrefix(self):
  59     return self._ref_type == self._BucketListingRefType.PREFIX
  60
  61   def __str__(self):
  62     return self._url_string
  63
  64
  65 class BucketListingBucket(BucketListingRef):
  66   """BucketListingRef subclass for buckets."""
  67
  68   def __init__(self, storage_url, root_object=None):
  69     """Creates a BucketListingRef of type bucket.
  70
  71     Args:
  72       storage_url: StorageUrl containing a bucket.
  73       root_object: Underlying object metadata, if available.
  74     """
  75     super(BucketListingBucket, self).__init__()
  76     self._ref_type = self._BucketListingRefType.BUCKET
  77     self._url_string = storage_url.url_string
  78     self.storage_url = storage_url
  79     self.root_object = root_object
  80
  81
  82 class BucketListingPrefix(BucketListingRef):
  83   """BucketListingRef subclass for prefixes."""
  84
  85   def __init__(self, storage_url, root_object=None):
  86     """Creates a BucketListingRef of type prefix.
  87
  88     Args:
  89       storage_url: StorageUrl containing a prefix.
  90       root_object: Underlying object metadata, if available.
  91     """
  92     super(BucketListingPrefix, self).__init__()
  93     self._ref_type = self._BucketListingRefType.PREFIX
  94     self._url_string = storage_url.url_string
  95     self.storage_url = storage_url
  96     self.root_object = root_object
  97
  98
  99 class BucketListingObject(BucketListingRef):
 100   """BucketListingRef subclass for objects."""
 101
 102   def __init__(self, storage_url, root_object=None):
 103     """Creates a BucketListingRef of type object.
 104
 105     Args:
 106       storage_url: StorageUrl containing an object.
 107       root_object: Underlying object metadata, if available.
 108     """
 109     super(BucketListingObject, self).__init__()
 110     self._ref_type = self._BucketListingRefType.OBJECT
 111     self._url_string = storage_url.url_string
 112     self.storage_url = storage_url
 113     self.root_object = root_object
 114