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 115
