docs: pass explicit 'client' in '{Blob.Bucket}.from_string' examples (#545)

tseaver · web-flow · commit 6eff22db0e8c · 2021-08-20T06:36:23.000Z
See #540.
diff --git a/google/cloud/storage/blob.py b/google/cloud/storage/blob.py
@@ -393,8 +393,8 @@ def from_string(cls, uri, client=None):
 
         :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.
+            (Optional) The client to use.  Application code should
+            *always* pass ``client``.
 
         :rtype: :class:`google.cloud.storage.blob.Blob`
         :returns: The blob object created.
@@ -405,7 +405,7 @@ def from_string(cls, uri, client=None):
             >>> from google.cloud import storage
             >>> from google.cloud.storage.blob import Blob
             >>> client = storage.Client()
-            >>> blob = Blob.from_string("gs://bucket/object")
+            >>> blob = Blob.from_string("gs://bucket/object", client=client)
         """
         from google.cloud.storage.bucket import Bucket
 
diff --git a/google/cloud/storage/bucket.py b/google/cloud/storage/bucket.py
@@ -656,7 +656,8 @@ def from_string(cls, uri, client=None):
 
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
-        :param client: (Optional) The client to use.
+        :param client: (Optional) The client to use.  Application code should
+            *always* pass ``client``.
 
         :rtype: :class:`google.cloud.storage.bucket.Bucket`
         :returns: The bucket object created.
@@ -667,7 +668,7 @@ def from_string(cls, uri, client=None):
             >>> from google.cloud import storage
             >>> from google.cloud.storage.bucket import Bucket
             >>> client = storage.Client()
-            >>> bucket = Bucket.from_string("gs://bucket", client)
+            >>> bucket = Bucket.from_string("gs://bucket", client=client)
         """
         scheme, netloc, path, query, frag = urlsplit(uri)
 
diff --git a/google/cloud/storage/client.py b/google/cloud/storage/client.py
@@ -221,26 +221,6 @@ def _pop_batch(self):
         """
         return self._batch_stack.pop()
 
-    def _bucket_arg_to_bucket(self, bucket_or_name):
-        """Helper to return given bucket or create new by name.
-
-        Args:
-            bucket_or_name (Union[ \
-                :class:`~google.cloud.storage.bucket.Bucket`, \
-                 str, \
-            ]):
-                The bucket resource to pass or name to create.
-
-        Returns:
-            google.cloud.storage.bucket.Bucket
-                The newly created bucket or the given one.
-        """
-        if isinstance(bucket_or_name, Bucket):
-            bucket = bucket_or_name
-        else:
-            bucket = Bucket(self, name=bucket_or_name)
-        return bucket
-
     @property
     def current_batch(self):
         """Currently-active batch.
@@ -682,6 +662,28 @@ def _delete_resource(
             _target_object=_target_object,
         )
 
+    def _bucket_arg_to_bucket(self, bucket_or_name):
+        """Helper to return given bucket or create new by name.
+
+        Args:
+            bucket_or_name (Union[ \
+                :class:`~google.cloud.storage.bucket.Bucket`, \
+                 str, \
+            ]):
+                The bucket resource to pass or name to create.
+
+        Returns:
+            google.cloud.storage.bucket.Bucket
+                The newly created bucket or the given one.
+        """
+        if isinstance(bucket_or_name, Bucket):
+            bucket = bucket_or_name
+            if bucket.client is None:
+                bucket._client = self
+        else:
+            bucket = Bucket(self, name=bucket_or_name)
+        return bucket
+
     def get_bucket(
         self,
         bucket_or_name,
diff --git a/tests/unit/test_client.py b/tests/unit/test_client.py
@@ -785,6 +785,51 @@ def test__delete_resource_hit_w_explicit(self):
             _target_object=target,
         )
 
+    def test__bucket_arg_to_bucket_w_bucket_w_client(self):
+        from google.cloud.storage.bucket import Bucket
+
+        project = "PROJECT"
+        credentials = _make_credentials()
+        client = self._make_one(project=project, credentials=credentials)
+        other_client = mock.Mock(spec=[])
+        bucket_name = "w_client"
+
+        bucket = Bucket(other_client, name=bucket_name)
+
+        found = client._bucket_arg_to_bucket(bucket)
+
+        self.assertIs(found, bucket)
+        self.assertIs(found.client, other_client)
+
+    def test__bucket_arg_to_bucket_w_bucket_wo_client(self):
+        from google.cloud.storage.bucket import Bucket
+
+        project = "PROJECT"
+        credentials = _make_credentials()
+        client = self._make_one(project=project, credentials=credentials)
+        bucket_name = "wo_client"
+
+        bucket = Bucket(client=None, name=bucket_name)
+
+        found = client._bucket_arg_to_bucket(bucket)
+
+        self.assertIs(found, bucket)
+        self.assertIs(found.client, client)
+
+    def test__bucket_arg_to_bucket_w_bucket_name(self):
+        from google.cloud.storage.bucket import Bucket
+
+        project = "PROJECT"
+        credentials = _make_credentials()
+        client = self._make_one(project=project, credentials=credentials)
+        bucket_name = "string-name"
+
+        found = client._bucket_arg_to_bucket(bucket_name)
+
+        self.assertIsInstance(found, Bucket)
+        self.assertEqual(found.name, bucket_name)
+        self.assertIs(found.client, client)
+
     def test_get_bucket_miss_w_string_w_defaults(self):
         from google.cloud.exceptions import NotFound
         from google.cloud.storage.bucket import Bucket
