Clarify 'user_project' semantics for API wrapper methods. (#4199)

Closes #4142.

[ci skip]

storage/google/cloud/storage/_helpers.py

@@ -90,6 +90,8 @@ def _require_client(self, client):
     def reload(self, client=None):
         """Reload properties from Cloud Storage.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
@@ -139,6 +141,8 @@ def patch(self, client=None):
 
         Updates the ``_properties`` with the response from the backend.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
@@ -164,6 +168,8 @@ def update(self, client=None):
 
         Updates the ``_properties`` with the response from the backend.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: the client to use.  If not passed, falls back to the

storage/google/cloud/storage/acl.py

@@ -399,6 +399,8 @@ def _require_client(self, client):
     def reload(self, client=None):
         """Reload the ACL data from Cloud Storage.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -463,6 +465,8 @@ def _save(self, acl, predefined, client):
     def save(self, acl=None, client=None):
         """Save this ACL for the current bucket.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type acl: :class:`google.cloud.storage.acl.ACL`, or a compatible list.
         :param acl: The ACL object to save.  If left blank, this will save
                     current entries.
@@ -484,6 +488,8 @@ def save(self, acl=None, client=None):
     def save_predefined(self, predefined, client=None):
         """Save this ACL for the current bucket using a predefined ACL.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type predefined: str
         :param predefined: An identifier for a predefined ACL.  Must be one
                            of the keys in :attr:`PREDEFINED_JSON_ACLS`
@@ -506,6 +512,8 @@ def save_predefined(self, predefined, client=None):
     def clear(self, client=None):
         """Remove all ACL entries.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         Note that this won't actually remove *ALL* the rules, but it
         will remove all the non-default rules.  In short, you'll still
         have access to a bucket that you created even after you clear

storage/google/cloud/storage/blob.py

@@ -226,7 +226,7 @@ def client(self):
 
     @property
     def user_project(self):
-        """Project ID used for API requests made via this blob.
+        """Project ID billed for API requests made via this blob.
 
         Derived from bucket's value.
 
@@ -333,6 +333,9 @@ def generate_signed_url(self, expiration, method='GET',
     def exists(self, client=None):
         """Determines whether or not this blob exists.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -365,6 +368,9 @@ def exists(self, client=None):
     def delete(self, client=None):
         """Deletes a blob from Cloud Storage.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -470,6 +476,9 @@ def download_to_file(self, file_obj, client=None):
         `google-resumable-media`_. For example, this library allows
         downloading **parts** of a blob rather than the whole thing.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type file_obj: file
         :param file_obj: A file handle to which to write the blob's data.
 
@@ -493,6 +502,9 @@ def download_to_file(self, file_obj, client=None):
     def download_to_filename(self, filename, client=None):
         """Download the contents of this blob into a named file.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type filename: str
         :param filename: A filename to be passed to ``open``.
 
@@ -519,6 +531,9 @@ def download_to_filename(self, filename, client=None):
     def download_as_string(self, client=None):
         """Download the contents of this blob as a string.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -889,6 +904,9 @@ def upload_from_file(self, file_obj, rewind=False, size=None,
         For more fine-grained over the upload process, check out
         `google-resumable-media`_.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type file_obj: file
         :param file_obj: A file handle open for reading.
 
@@ -952,6 +970,9 @@ def upload_from_filename(self, filename, content_type=None, client=None):
            `lifecycle <https://cloud.google.com/storage/docs/lifecycle>`_
            API documents for details.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type filename: str
         :param filename: The path to the file.
 
@@ -984,6 +1005,9 @@ def upload_from_string(self, data, content_type='text/plain', client=None):
            `lifecycle <https://cloud.google.com/storage/docs/lifecycle>`_
            API documents for details.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type data: bytes or str
         :param data: The data to store in this blob.  If the value is
                      text, it will be encoded as UTF-8.
@@ -1045,6 +1069,9 @@ def create_resumable_upload_session(
         If :attr:`encryption_key` is set, the blob will be encrypted with
         a `customer-supplied`_ encryption key.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type size: int
         :param size: (Optional). The maximum number of bytes that can be
                      uploaded using this session. If the size is not known
@@ -1096,6 +1123,9 @@ def get_iam_policy(self, client=None):
         See
         https://cloud.google.com/storage/docs/json_api/v1/objects/getIamPolicy
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -1125,6 +1155,9 @@ def set_iam_policy(self, policy, client=None):
         See
         https://cloud.google.com/storage/docs/json_api/v1/objects/setIamPolicy
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type policy: :class:`google.cloud.iam.Policy`
         :param policy: policy instance used to update bucket's IAM policy.
 
@@ -1160,6 +1193,9 @@ def test_iam_permissions(self, permissions, client=None):
         See
         https://cloud.google.com/storage/docs/json_api/v1/objects/testIamPermissions
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type permissions: list of string
         :param permissions: the permissions to check
 
@@ -1200,6 +1236,9 @@ def make_public(self, client=None):
     def compose(self, sources, client=None):
         """Concatenate source blobs into this one.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type sources: list of :class:`Blob`
         :param sources: blobs whose contents will be composed into this blob.
 
@@ -1235,6 +1274,9 @@ def compose(self, sources, client=None):
     def rewrite(self, source, token=None, client=None):
         """Rewrite source blob into this one.
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type source: :class:`Blob`
         :param source: blob whose contents will be rewritten into this blob.
 
@@ -1293,6 +1335,9 @@ def update_storage_class(self, new_class, client=None):
         See
         https://cloud.google.com/storage/docs/per-object-storage-class
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type new_class: str
         :param new_class: new storage class for the object
 

storage/google/cloud/storage/bucket.py

@@ -220,6 +220,8 @@ def notification(self, topic_name,
     def exists(self, client=None):
         """Determines whether or not this bucket exists.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -257,6 +259,8 @@ def create(self, client=None):
 
         This implements "storage.buckets.insert".
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -279,6 +283,8 @@ def patch(self, client=None):
 
         Updates the ``_properties`` with the response from the backend.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: the client to use.  If not passed, falls back to the
@@ -334,6 +340,8 @@ def get_blob(self, blob_name, client=None, encryption_key=None, **kwargs):
           :start-after: [START get_blob]
           :end-before: [END get_blob]
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type blob_name: str
         :param blob_name: The name of the blob to retrieve.
 
@@ -385,6 +393,8 @@ def list_blobs(self, max_results=None, page_token=None, prefix=None,
                    projection='noAcl', fields=None, client=None):
         """Return an iterator used to find blobs in the bucket.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type max_results: int
         :param max_results: (Optional) Maximum number of blobs to return.
 
@@ -462,6 +472,8 @@ def list_notifications(self, client=None):
         See:
         https://cloud.google.com/storage/docs/json_api/v1/notifications/list
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -497,6 +509,8 @@ def delete(self, force=False, client=None):
         is to prevent accidental bucket deletion and to prevent extremely long
         runtime of this method.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type force: bool
         :param force: If True, empties the bucket's objects then deletes it.
 
@@ -552,6 +566,8 @@ def delete_blob(self, blob_name, client=None):
           :start-after: [START delete_blob]
           :end-before: [END delete_blob]
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type blob_name: str
         :param blob_name: A blob name to delete.
 
@@ -590,6 +606,8 @@ def delete_blobs(self, blobs, on_error=None, client=None):
 
         Uses :meth:`delete_blob` to delete each individual blob.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type blobs: list
         :param blobs: A list of :class:`~google.cloud.storage.blob.Blob`-s or
                       blob names to delete.
@@ -623,6 +641,8 @@ def copy_blob(self, blob, destination_bucket, new_name=None,
                   client=None, preserve_acl=True):
         """Copy the given blob to the given bucket, optionally with a new name.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type blob: :class:`google.cloud.storage.blob.Blob`
         :param blob: The blob to be copied.
 
@@ -672,6 +692,8 @@ def copy_blob(self, blob, destination_bucket, new_name=None,
     def rename_blob(self, blob, new_name, client=None):
         """Rename the given blob using copy and delete operations.
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         Effectively, copies blob to the same bucket with a new name, then
         deletes the blob.
 
@@ -1112,6 +1134,8 @@ def get_iam_policy(self, client=None):
         See
         https://cloud.google.com/storage/docs/json_api/v1/buckets/getIamPolicy
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -1140,6 +1164,8 @@ def set_iam_policy(self, policy, client=None):
         See
         https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type policy: :class:`google.cloud.iam.Policy`
         :param policy: policy instance used to update bucket's IAM policy.
 
@@ -1174,6 +1200,8 @@ def test_iam_permissions(self, permissions, client=None):
         See
         https://cloud.google.com/storage/docs/json_api/v1/buckets/testIamPermissions
 
+        If :attr:`user_project` is set, bills the API request to that project.
+
         :type permissions: list of string
         :param permissions: the permissions to check
 

storage/google/cloud/storage/client.py

@@ -133,7 +133,7 @@ def bucket(self, bucket_name, user_project=None):
 
         :type user_project: str
         :param user_project: (Optional) the project ID to be billed for API
-                             requests made via this instance.
+                             requests made via the bucket.
 
         :rtype: :class:`google.cloud.storage.bucket.Bucket`
         :returns: The bucket object created.

storage/google/cloud/storage/notification.py

@@ -223,6 +223,9 @@ def create(self, client=None):
         See:
         https://cloud.google.com/storage/docs/json_api/v1/notifications/insert
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :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 notification's bucket.
@@ -254,6 +257,9 @@ def exists(self, client=None):
         See:
         https://cloud.google.com/storage/docs/json_api/v1/notifications/get
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -289,6 +295,9 @@ def reload(self, client=None):
         See:
         https://cloud.google.com/storage/docs/json_api/v1/notifications/get
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back
@@ -320,6 +329,9 @@ def delete(self, client=None):
         See:
         https://cloud.google.com/storage/docs/json_api/v1/notifications/delete
 
+        If :attr:`user_project` is set on the bucket, bills the API request
+        to that project.
+
         :type client: :class:`~google.cloud.storage.client.Client` or
                       ``NoneType``
         :param client: Optional. The client to use.  If not passed, falls back