Storage: Avoid using 'REGIONAL'/'MULTI_REGIONAL' in examples, tests.

storage/docs/constants.rst

@@ -0,0 +1,7 @@
+Constants
+~~~~~~~~~
+
+.. automodule:: google.cloud.storage.constants
+  :members:
+  :member-order: bysource
+

storage/docs/index.rst

@@ -18,6 +18,7 @@ API Reference
   buckets
   acl
   batch
+  constants
 
 Changelog
 ---------

storage/google/cloud/storage/blob.py

@@ -46,19 +46,24 @@
 from google.resumable_media.requests import MultipartUpload
 from google.resumable_media.requests import ResumableUpload
 
+from google.api_core.iam import Policy
 from google.cloud import exceptions
 from google.cloud._helpers import _bytes_to_unicode
 from google.cloud._helpers import _rfc3339_to_datetime
 from google.cloud._helpers import _to_bytes
 from google.cloud.exceptions import NotFound
-from google.api_core.iam import Policy
 from google.cloud.storage._helpers import _get_storage_host
 from google.cloud.storage._helpers import _PropertyMixin
 from google.cloud.storage._helpers import _scalar_property
 from google.cloud.storage._signing import generate_signed_url_v2
 from google.cloud.storage._signing import generate_signed_url_v4
 from google.cloud.storage.acl import ACL
 from google.cloud.storage.acl import ObjectACL
+from google.cloud.storage.constants import STANDARD_STORAGE_CLASS
+from google.cloud.storage.constants import NEARLINE_STORAGE_CLASS
+from google.cloud.storage.constants import COLDLINE_STORAGE_CLASS
+from google.cloud.storage.constants import MULTI_REGIONAL_LEGACY_STORAGE_CLASS
+from google.cloud.storage.constants import REGIONAL_LEGACY_STORAGE_CLASS
 
 _STORAGE_HOST = _get_storage_host()
 
@@ -134,12 +139,12 @@ class Blob(_PropertyMixin):
     _CHUNK_SIZE_MULTIPLE = 256 * 1024
     """Number (256 KB, in bytes) that must divide the chunk size."""
 
-    _STORAGE_CLASSES = (
-        "NEARLINE",
-        "MULTI_REGIONAL",
-        "REGIONAL",
-        "COLDLINE",
-        "STANDARD",  # alias for MULTI_REGIONAL/REGIONAL, based on location
+    STORAGE_CLASSES = (
+        STANDARD_STORAGE_CLASS,
+        NEARLINE_STORAGE_CLASS,
+        COLDLINE_STORAGE_CLASS,
+        MULTI_REGIONAL_LEGACY_STORAGE_CLASS,
+        REGIONAL_LEGACY_STORAGE_CLASS,
     )
     """Allowed values for :attr:`storage_class`.
 
@@ -150,11 +155,6 @@ class Blob(_PropertyMixin):
     .. note::
        This list does not include 'DURABLE_REDUCED_AVAILABILITY', which
        is only documented for buckets (and deprecated).
-
-    .. note::
-       The documentation does *not* mention 'STANDARD', but it is the value
-       assigned by the back-end for objects created in buckets with 'STANDARD'
-       set as their 'storage_class'.
     """
 
     def __init__(
@@ -1640,13 +1640,20 @@ def update_storage_class(self, new_class, client=None):
         to that project.
 
         :type new_class: str
-        :param new_class: new storage class for the object
+        :param new_class:
+            new storage class for the object.   One of:
+            :attr:`~google.cloud.storage.constants.NEARLINE_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.COLDLINE_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.STANDARD_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
+            or
+            :attr:`~google.cloud.storage.constants.REGIONAL_LEGACY_STORAGE_CLASS`.
 
         :type client: :class:`~google.cloud.storage.client.Client`
         :param client: Optional. The client to use.  If not passed, falls back
                        to the ``client`` stored on the blob's bucket.
         """
-        if new_class not in self._STORAGE_CLASSES:
+        if new_class not in self.STORAGE_CLASSES:
             raise ValueError("Invalid storage class: %s" % (new_class,))
 
         # Update current blob's storage class prior to rewrite
@@ -1927,9 +1934,15 @@ def kms_key_name(self):
     See https://cloud.google.com/storage/docs/storage-classes
 
     :rtype: str or ``NoneType``
-    :returns: If set, one of "MULTI_REGIONAL", "REGIONAL",
-              "NEARLINE", "COLDLINE", "STANDARD", or
-              "DURABLE_REDUCED_AVAILABILITY", else ``None``.
+    :returns:
+        If set, one of
+        :attr:`~google.cloud.storage.constants.STANDARD_STORAGE_CLASS`,
+        :attr:`~google.cloud.storage.constants.NEARLINE_STORAGE_CLASS`,
+        :attr:`~google.cloud.storage.constants.COLDLINE_STORAGE_CLASS`,
+        :attr:`~google.cloud.storage.constants.MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
+        :attr:`~google.cloud.storage.constants.REGIONAL_LEGACY_STORAGE_CLASS`,
+        :attr:`~google.cloud.storage.constants.DURABLE_REDUCED_AVAILABILITY_STORAGE_CLASS`,
+        else ``None``.
     """
 
     temporary_hold = _scalar_property("temporaryHold")

storage/google/cloud/storage/bucket.py

@@ -39,6 +39,17 @@
 from google.cloud.storage.acl import BucketACL
 from google.cloud.storage.acl import DefaultObjectACL
 from google.cloud.storage.blob import Blob
+from google.cloud.storage.constants import COLDLINE_STORAGE_CLASS
+from google.cloud.storage.constants import DUAL_REGION_LOCATION_TYPE
+from google.cloud.storage.constants import (
+    DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS,
+)
+from google.cloud.storage.constants import MULTI_REGIONAL_LEGACY_STORAGE_CLASS
+from google.cloud.storage.constants import MULTI_REGION_LOCATION_TYPE
+from google.cloud.storage.constants import NEARLINE_STORAGE_CLASS
+from google.cloud.storage.constants import REGIONAL_LEGACY_STORAGE_CLASS
+from google.cloud.storage.constants import REGION_LOCATION_TYPE
+from google.cloud.storage.constants import STANDARD_STORAGE_CLASS
 from google.cloud.storage.notification import BucketNotification
 from google.cloud.storage.notification import NONE_PAYLOAD_FORMAT
 
@@ -130,7 +141,7 @@ class LifecycleRuleConditions(dict):
                     version.
 
     :type matches_storage_class: list(str), one or more of
-                                 :attr:`Bucket._STORAGE_CLASSES`.
+                                 :attr:`Bucket.STORAGE_CLASSES`.
     :param matches_storage_class: (optional) apply rule action to items which
                                   whose storage class matches this value.
 
@@ -244,7 +255,7 @@ def from_api_repr(cls, resource):
 class LifecycleRuleSetStorageClass(dict):
     """Map a lifecycle rule upating storage class of matching items.
 
-    :type storage_class: str, one of :attr:`Bucket._STORAGE_CLASSES`.
+    :type storage_class: str, one of :attr:`Bucket.STORAGE_CLASSES`.
     :param storage_class: new storage class to assign to matching items.
 
     :type kw: dict
@@ -387,38 +398,7 @@ class Bucket(_PropertyMixin):
     This is used in Bucket.delete() and Bucket.make_public().
     """
 
-    STANDARD_STORAGE_CLASS = "STANDARD"
-    """Storage class for objects accessed more than once per month."""
-
-    NEARLINE_STORAGE_CLASS = "NEARLINE"
-    """Storage class for objects accessed at most once per month."""
-
-    COLDLINE_STORAGE_CLASS = "COLDLINE"
-    """Storage class for objects accessed at most once per year."""
-
-    MULTI_REGIONAL_LEGACY_STORAGE_CLASS = "MULTI_REGIONAL"
-    """Legacy storage class.
-
-    Alias for :attr:`STANDARD_STORAGE_CLASS`.
-
-    Implies :attr:`MULTI_REGION_LOCATION_TYPE` for :attr:`location_type`.
-    """
-
-    REGIONAL_LEGACY_STORAGE_CLASS = "REGIONAL"
-    """Legacy storage class.
-
-    Alias for :attr:`STANDARD_STORAGE_CLASS`.
-
-    Implies :attr:`REGION_LOCATION_TYPE` for :attr:`location_type`.
-    """
-
-    DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS = "DURABLE_REDUCED_AVAILABILITY"
-    """Legacy storage class.
-
-    Similar to :attr:`NEARLINE_STORAGE_CLASS`.
-    """
-
-    _STORAGE_CLASSES = (
+    STORAGE_CLASSES = (
         STANDARD_STORAGE_CLASS,
         NEARLINE_STORAGE_CLASS,
         COLDLINE_STORAGE_CLASS,
@@ -435,24 +415,6 @@ class Bucket(_PropertyMixin):
     https://cloud.google.com/storage/docs/storage-classes
     """
 
-    MULTI_REGION_LOCATION_TYPE = "multi-region"
-    """Location type: data will be replicated across regions in a multi-region.
-
-    Provides highest availability across largest area.
-    """
-
-    REGION_LOCATION_TYPE = "region"
-    """Location type: data will be stored within a single region.
-
-    Provides lowest latency within a single region.
-    """
-
-    DUAL_REGION_LOCATION_TYPE = "dual-region"
-    """Location type: data will be stored within two primary regions.
-
-    Provides high availability and low latency across two regions.
-    """
-
     _LOCATION_TYPES = (
         MULTI_REGION_LOCATION_TYPE,
         REGION_LOCATION_TYPE,
@@ -1422,7 +1384,7 @@ def add_lifecycle_set_storage_class_rule(self, storage_class, **kw):
           :start-after: [START add_lifecycle_set_storage_class_rule]
           :end-before: [END add_lifecycle_set_storage_class_rule]
 
-        :type storage_class: str, one of :attr:`_STORAGE_CLASSES`.
+        :type storage_class: str, one of :attr:`STORAGE_CLASSES`.
         :param storage_class: new storage class to assign to matching items.
 
         :type kw: dict
@@ -1476,8 +1438,10 @@ def location_type(self):
 
         :rtype: str or ``NoneType``
         :returns:
-            If set, one of :attr:`MULTI_REGION_LOCATION_TYPE`,
-            :attr:`REGION_LOCATION_TYPE`, or :attr:`DUAL_REGION_LOCATION_TYPE`,
+            If set, one of
+            :attr:`~google.cloud.storage.constants.MULTI_REGION_LOCATION_TYPE`,
+            :attr:`~google.cloud.storage.constants.REGION_LOCATION_TYPE`, or
+            :attr:`~google.cloud.storage.constants.DUAL_REGION_LOCATION_TYPE`,
             else ``None``.
         """
         return self._properties.get("locationType")
@@ -1639,12 +1603,14 @@ def storage_class(self):
 
         :rtype: str or ``NoneType``
         :returns:
-            If set, one of :attr:`NEARLINE_STORAGE_CLASS`,
-            :attr:`COLDLINE_STORAGE_CLASS`, :attr:`STANDARD_STORAGE_CLASS`,
-            :attr:`MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
-            :attr:`REGIONAL_LEGACY_STORAGE_CLASS`,
+            If set, one of
+            :attr:`~google.cloud.storage.constants.NEARLINE_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.COLDLINE_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.STANDARD_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.REGIONAL_LEGACY_STORAGE_CLASS`,
             or
-            :attr:`DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS`,
             else ``None``.
         """
         return self._properties.get("storageClass")
@@ -1657,14 +1623,16 @@ def storage_class(self, value):
 
         :type value: str
         :param value:
-            One of :attr:`NEARLINE_STORAGE_CLASS`,
-            :attr:`COLDLINE_STORAGE_CLASS`, :attr:`STANDARD_STORAGE_CLASS`,
-            :attr:`MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
-            :attr:`REGIONAL_LEGACY_STORAGE_CLASS`,
+            One of
+            :attr:`~google.cloud.storage.constants.NEARLINE_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.COLDLINE_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.STANDARD_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.MULTI_REGIONAL_LEGACY_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.REGIONAL_LEGACY_STORAGE_CLASS`,
             or
-            :attr:`DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS`,
+            :attr:`~google.cloud.storage.constants.DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS`,
         """
-        if value not in self._STORAGE_CLASSES:
+        if value not in self.STORAGE_CLASSES:
             raise ValueError("Invalid storage class: %s" % (value,))
         self._patch_property("storageClass", value)
 

storage/google/cloud/storage/constants.py

@@ -0,0 +1,72 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Constants used acros google.cloud.storage modules."""
+
+# Storage classes
+
+STANDARD_STORAGE_CLASS = "STANDARD"
+"""Storage class for objects accessed more than once per month."""
+
+NEARLINE_STORAGE_CLASS = "NEARLINE"
+"""Storage class for objects accessed at most once per month."""
+
+COLDLINE_STORAGE_CLASS = "COLDLINE"
+"""Storage class for objects accessed at most once per year."""
+
+MULTI_REGIONAL_LEGACY_STORAGE_CLASS = "MULTI_REGIONAL"
+"""Legacy storage class.
+
+Alias for :attr:`STANDARD_STORAGE_CLASS`.
+
+Can only be used for objects in buckets whose
+:attr:`~google.cloud.storage.bucket.Bucket.location_type` is
+:attr:`~google.cloud.storage.bucket.Bucket.MULTI_REGION_LOCATION_TYPE`.
+"""
+
+REGIONAL_LEGACY_STORAGE_CLASS = "REGIONAL"
+"""Legacy storage class.
+
+Alias for :attr:`STANDARD_STORAGE_CLASS`.
+
+Can only be used for objects in buckets whose
+:attr:`~google.cloud.storage.bucket.Bucket.location_type` is
+:attr:`~google.cloud.storage.bucket.Bucket.REGION_LOCATION_TYPE`.
+"""
+
+DURABLE_REDUCED_AVAILABILITY_LEGACY_STORAGE_CLASS = "DURABLE_REDUCED_AVAILABILITY"
+"""Legacy storage class.
+
+Similar to :attr:`NEARLINE_STORAGE_CLASS`.
+"""
+
+
+# Location types
+
+MULTI_REGION_LOCATION_TYPE = "multi-region"
+"""Location type: data will be replicated across regions in a multi-region.
+
+Provides highest availability across largest area.
+"""
+
+REGION_LOCATION_TYPE = "region"
+"""Location type: data will be stored within a single region.
+
+Provides lowest latency within a single region.
+"""
+
+DUAL_REGION_LOCATION_TYPE = "dual-region"
+"""Location type: data will be stored within two primary regions.
+
+Provides high availability and low latency across two regions.
+"""

storage/tests/unit/test_blob.py

@@ -3087,7 +3087,7 @@ def test_size_string_val(self):
     def test_storage_class_getter(self):
         blob_name = "blob-name"
         bucket = _Bucket()
-        storage_class = "MULTI_REGIONAL"
+        storage_class = "COLDLINE"
         properties = {"storageClass": storage_class}
         blob = self._make_one(blob_name, bucket=bucket, properties=properties)
         self.assertEqual(blob.storage_class, storage_class)