fix: update user_project usage and documentation in bucket/client cla…

…ss methods (#396)

* fix: update documentation and usage of user_project in bucket class methods

* revise Bucket.create() docstring

* revise Bucket @Property user_project docstring

* add example to client.get_bucket() with user_project

* revise deprecated Bucket.create() and unit test

* fix lint

* address review changes

google/cloud/storage/bucket.py

@@ -611,6 +611,10 @@ def user_project(self):
 
         If unset, API requests are billed to the bucket owner.
 
+        A user project is required for all operations on Requester Pays buckets.
+
+        See https://cloud.google.com/storage/docs/requester-pays#requirements for details.
+
         :rtype: str
         """
         return self._user_project
@@ -809,6 +813,9 @@ def create(
     ):
         """DEPRECATED. Creates current bucket.
 
+        .. note::
+          Direct use of this method is deprecated. Use ``Client.create_bucket()`` instead.
+
         If the bucket already exists, will raise
         :class:`google.cloud.exceptions.Conflict`.
 
@@ -825,7 +832,6 @@ def create(
         :param project: (Optional) The project under which the bucket is to
                         be created. If not passed, uses the project set on
                         the client.
-        :raises ValueError: if :attr:`user_project` is set.
         :raises ValueError: if ``project`` is None and client's
                             :attr:`project` is also None.
 
@@ -871,13 +877,12 @@ def create(
             PendingDeprecationWarning,
             stacklevel=1,
         )
-        if self.user_project is not None:
-            raise ValueError("Cannot create bucket with 'user_project' set.")
 
         client = self._require_client(client)
         client.create_bucket(
             bucket_or_name=self,
             project=project,
+            user_project=self.user_project,
             location=location,
             predefined_acl=predefined_acl,
             predefined_default_object_acl=predefined_default_object_acl,
@@ -1328,7 +1333,7 @@ def list_blobs(
             >>> from google.cloud import storage
             >>> client = storage.Client()
 
-            >>> bucket = storage.Bucket("my-bucket-name", user_project='my-project')
+            >>> bucket = storage.Bucket(client, "my-bucket-name", user_project="my-project")
             >>> all_blobs = list(client.list_blobs(bucket))
         """
         client = self._require_client(client)

google/cloud/storage/client.py

@@ -839,7 +839,7 @@ def list_blobs(
             >>> from google.cloud import storage
             >>> client = storage.Client()
 
-            >>> bucket = storage.Bucket("my-bucket-name", user_project='my-project')
+            >>> bucket = storage.Bucket(client, "my-bucket-name", user_project="my-project")
             >>> all_blobs = list(client.list_blobs(bucket))
         """
         bucket = self._bucket_arg_to_bucket(bucket_or_name)

tests/unit/test_bucket.py

@@ -2330,7 +2330,8 @@ def test_create_deprecated(self, mock_warn):
             stacklevel=1,
         )
 
-    def test_create_w_user_project(self):
+    @mock.patch("warnings.warn")
+    def test_create_w_user_project(self, mock_warn):
         PROJECT = "PROJECT"
         BUCKET_NAME = "bucket-name"
         DATA = {"name": BUCKET_NAME}
@@ -2340,8 +2341,24 @@ def test_create_w_user_project(self):
 
         bucket = self._make_one(client=client, name=BUCKET_NAME)
         bucket._user_project = "USER_PROJECT"
-        with self.assertRaises(ValueError):
-            bucket.create()
+        bucket.create()
+
+        connection.api_request.assert_called_once_with(
+            method="POST",
+            path="/b",
+            query_params={"project": PROJECT, "userProject": "USER_PROJECT"},
+            data=DATA,
+            _target_object=bucket,
+            timeout=self._get_default_timeout(),
+            retry=DEFAULT_RETRY,
+        )
+
+        mock_warn.assert_called_with(
+            "Bucket.create() is deprecated and will be removed in future."
+            "Use Client.create_bucket() instead.",
+            PendingDeprecationWarning,
+            stacklevel=1,
+        )
 
     def test_versioning_enabled_setter(self):
         NAME = "name"