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
17from __future__ import absolute_import
18
19
20class 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
65class 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
82class 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
99class 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