From a50cdd145d39cb67e0d7021c376acbe376436178 Mon Sep 17 00:00:00 2001 From: HemangChothani <50404902+HemangChothani@users.noreply.github.com> Date: Sat, 14 Mar 2020 06:02:11 +0530 Subject: [PATCH] refactor(storage): consistent use of optional keyword (#81) Fixes #80 --- google/cloud/storage/_helpers.py | 6 +- google/cloud/storage/_signing.py | 4 +- google/cloud/storage/acl.py | 29 ++++--- google/cloud/storage/batch.py | 2 +- google/cloud/storage/blob.py | 115 +++++++++++++------------- google/cloud/storage/bucket.py | 116 +++++++++++++-------------- google/cloud/storage/client.py | 52 ++++++------ google/cloud/storage/hmac_key.py | 12 +-- google/cloud/storage/notification.py | 28 +++---- 9 files changed, 183 insertions(+), 181 deletions(-) diff --git a/google/cloud/storage/_helpers.py b/google/cloud/storage/_helpers.py index ae53a7b65..1a1aca8ce 100644 --- a/google/cloud/storage/_helpers.py +++ b/google/cloud/storage/_helpers.py @@ -130,7 +130,7 @@ def reload(self, client=None, timeout=_DEFAULT_TIMEOUT): :param client: the client to use. If not passed, falls back to the ``client`` stored on the current object. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -191,7 +191,7 @@ def patch(self, client=None, timeout=_DEFAULT_TIMEOUT): :param client: the client to use. If not passed, falls back to the ``client`` stored on the current object. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -227,7 +227,7 @@ def update(self, client=None, timeout=_DEFAULT_TIMEOUT): :param client: the client to use. If not passed, falls back to the ``client`` stored on the current object. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). diff --git a/google/cloud/storage/_signing.py b/google/cloud/storage/_signing.py index c479c9792..f5e74e260 100644 --- a/google/cloud/storage/_signing.py +++ b/google/cloud/storage/_signing.py @@ -304,7 +304,7 @@ def generate_signed_url_v2( :param expiration: Point in time when the signed URL should expire. :type api_access_endpoint: str - :param api_access_endpoint: Optional URI base. Defaults to empty string. + :param api_access_endpoint: (Optional) URI base. Defaults to empty string. :type method: str :param method: The HTTP verb that will be used when requesting the URL. @@ -466,7 +466,7 @@ def generate_signed_url_v4( :param expiration: Point in time when the signed URL should expire. :type api_access_endpoint: str - :param api_access_endpoint: Optional URI base. Defaults to + :param api_access_endpoint: (Optional) URI base. Defaults to "https://storage.googleapis.com/" :type method: str diff --git a/google/cloud/storage/acl.py b/google/cloud/storage/acl.py index 7260c50b0..fb07faba9 100644 --- a/google/cloud/storage/acl.py +++ b/google/cloud/storage/acl.py @@ -92,8 +92,8 @@ class _ACLEntity(object): :param entity_type: The type of entity (ie, 'group' or 'user'). :type identifier: str - :param identifier: The ID or e-mail of the entity. For the special - entity types (like 'allUsers') this is optional. + :param identifier: (Optional) The ID or e-mail of the entity. For the special + entity types (like 'allUsers'). """ READER_ROLE = "READER" @@ -212,7 +212,7 @@ def _ensure_loaded(self, timeout=_DEFAULT_TIMEOUT): """Load if not already loaded. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -432,10 +432,10 @@ def reload(self, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the ACL's parent. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -465,16 +465,15 @@ def _save(self, acl, predefined, client, timeout=_DEFAULT_TIMEOUT): current entries. :type predefined: str - :param predefined: - (Optional) An identifier for a predefined ACL. Must be one of the + :param predefined: An identifier for a predefined ACL. Must be one of the keys in :attr:`PREDEFINED_JSON_ACLS` If passed, `acl` must be None. :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the ACL's parent. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -514,10 +513,10 @@ def save(self, acl=None, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the ACL's parent. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -546,10 +545,10 @@ def save_predefined(self, predefined, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the ACL's parent. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -570,10 +569,10 @@ def clear(self, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the ACL's parent. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). diff --git a/google/cloud/storage/batch.py b/google/cloud/storage/batch.py index 89425f9b8..abfc88412 100644 --- a/google/cloud/storage/batch.py +++ b/google/cloud/storage/batch.py @@ -177,7 +177,7 @@ def _do_request( initialization of the object at a later time. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). diff --git a/google/cloud/storage/blob.py b/google/cloud/storage/blob.py index 59b4b94a0..fb329d08d 100644 --- a/google/cloud/storage/blob.py +++ b/google/cloud/storage/blob.py @@ -123,20 +123,23 @@ class Blob(_PropertyMixin): :param bucket: The bucket to which this blob belongs. :type chunk_size: int - - :param chunk_size: The size of a chunk of data whenever iterating (in - bytes). This must be a multiple of 256 KB per the API - specification. + :param chunk_size: + (Optional) The size of a chunk of data whenever iterating (in bytes). + This must be a multiple of 256 KB per the API specification. :type encryption_key: bytes :param encryption_key: - Optional 32 byte encryption key for customer-supplied encryption. + (Optional) 32 byte encryption key for customer-supplied encryption. See https://cloud.google.com/storage/docs/encryption#customer-supplied. :type kms_key_name: str :param kms_key_name: - Optional resource name of Cloud KMS key used to encrypt the blob's + (Optional) Resource name of Cloud KMS key used to encrypt the blob's contents. + + :type generation: long + :param generation: (Optional) If present, selects a specific revision of + this object. """ _chunk_size = None # Default value for each instance. @@ -322,7 +325,7 @@ 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. :rtype: :class:`google.cloud.storage.blob.Blob` :returns: The blob object created. @@ -405,7 +408,7 @@ def generate_signed_url( :param expiration: Point in time when the signed URL should expire. :type api_access_endpoint: str - :param api_access_endpoint: Optional URI base. + :param api_access_endpoint: (Optional) URI base. :type method: str :param method: The HTTP verb that will be used when requesting the URL. @@ -568,10 +571,10 @@ def exists(self, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -611,10 +614,10 @@ def delete(self, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -693,17 +696,17 @@ def _do_download( :param download_url: The URL where the media can be accessed. :type headers: dict - :param headers: Optional headers to be sent with the request(s). + :param headers: Headers to be sent with the request(s). :type start: int - :param start: Optional, the first byte in a range to be downloaded. + :param start: (Optional) The first byte in a range to be downloaded. :type end: int - :param end: Optional, The last byte in a range to be downloaded. + :param end: (Optional) The last byte in a range to be downloaded. :type raw_download: bool :param raw_download: - Optional, If true, download the object without any expansion. + (Optional) If true, download the object without any expansion. """ if self.chunk_size is None: if raw_download: @@ -768,18 +771,18 @@ def download_to_file( :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. :type start: int - :param start: Optional, the first byte in a range to be downloaded. + :param start: (Optional) The first byte in a range to be downloaded. :type end: int - :param end: Optional, The last byte in a range to be downloaded. + :param end: (Optional) The last byte in a range to be downloaded. :type raw_download: bool :param raw_download: - Optional, If true, download the object without any expansion. + (Optional) If true, download the object without any expansion. :raises: :class:`google.cloud.exceptions.NotFound` """ @@ -808,18 +811,18 @@ def download_to_filename( :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. :type start: int - :param start: Optional, the first byte in a range to be downloaded. + :param start: (Optional) The first byte in a range to be downloaded. :type end: int - :param end: Optional, The last byte in a range to be downloaded. + :param end: (Optional) The last byte in a range to be downloaded. :type raw_download: bool :param raw_download: - Optional, If true, download the object without any expansion. + (Optional) If true, download the object without any expansion. :raises: :class:`google.cloud.exceptions.NotFound` """ @@ -850,18 +853,18 @@ def download_as_string(self, client=None, start=None, end=None, raw_download=Fal :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. :type start: int - :param start: Optional, the first byte in a range to be downloaded. + :param start: (Optional) The first byte in a range to be downloaded. :type end: int - :param end: Optional, The last byte in a range to be downloaded. + :param end: (Optional) The last byte in a range to be downloaded. :type raw_download: bool :param raw_download: - Optional, If true, download the object without any expansion. + (Optional) If true, download the object without any expansion. :rtype: bytes :returns: The data stored in this blob. @@ -887,7 +890,7 @@ def _get_content_type(self, content_type, filename=None): - The default value ('application/octet-stream') :type content_type: str - :param content_type: (Optional) type of content. + :param content_type: (Optional) Type of content. :type filename: str :param filename: (Optional) The name of the file where the content @@ -994,7 +997,7 @@ def _do_multipart_upload( argument will be removed in a future release.) :type predefined_acl: str - :param predefined_acl: (Optional) predefined access control list + :param predefined_acl: (Optional) Predefined access control list :rtype: :class:`~requests.Response` :returns: The "200 OK" response object returned after the multipart @@ -1074,7 +1077,7 @@ def _initiate_resumable_upload( concluded once ``stream`` is exhausted (or :data:`None`). :type predefined_acl: str - :param predefined_acl: (Optional) predefined access control list + :param predefined_acl: (Optional) Predefined access control list :type num_retries: int :param num_retries: Number of upload retries. (Deprecated: This @@ -1175,7 +1178,7 @@ def _do_resumable_upload( argument will be removed in a future release.) :type predefined_acl: str - :param predefined_acl: (Optional) predefined access control list + :param predefined_acl: (Optional) Predefined access control list :rtype: :class:`~requests.Response` :returns: The "200 OK" response object returned after the final chunk @@ -1231,7 +1234,7 @@ def _do_upload( argument will be removed in a future release.) :type predefined_acl: str - :param predefined_acl: (Optional) predefined access control list + :param predefined_acl: (Optional) Predefined access control list :rtype: dict :returns: The parsed JSON from the "200 OK" response. This will be the @@ -1306,7 +1309,7 @@ def upload_from_file( concluded once ``file_obj`` is exhausted. :type content_type: str - :param content_type: Optional type of content being uploaded. + :param content_type: (Optional) Type of content being uploaded. :type num_retries: int :param num_retries: Number of upload retries. (Deprecated: This @@ -1317,7 +1320,7 @@ def upload_from_file( to the ``client`` stored on the blob's bucket. :type predefined_acl: str - :param predefined_acl: (Optional) predefined access control list + :param predefined_acl: (Optional) Predefined access control list :raises: :class:`~google.cloud.exceptions.GoogleCloudError` if the upload response returns an error status. @@ -1371,14 +1374,14 @@ def upload_from_filename( :param filename: The path to the file. :type content_type: str - :param content_type: Optional type of content being uploaded. + :param content_type: (Optional) Type of content being uploaded. :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. :type predefined_acl: str - :param predefined_acl: (Optional) predefined access control list + :param predefined_acl: (Optional) Predefined access control list """ content_type = self._get_content_type(content_type, filename=filename) @@ -1416,16 +1419,16 @@ def upload_from_string( text, it will be encoded as UTF-8. :type content_type: str - :param content_type: Optional type of content being uploaded. Defaults + :param content_type: (Optional) Type of content being uploaded. Defaults to ``'text/plain'``. :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. :type predefined_acl: str - :param predefined_acl: (Optional) predefined access control list + :param predefined_acl: (Optional) Predefined access control list """ data = _to_bytes(data, encoding="utf-8") string_buffer = BytesIO(data) @@ -1480,7 +1483,7 @@ def create_resumable_upload_session( to that project. :type size: int - :param size: (Optional). The maximum number of bytes that can be + :param size: (Optional) The maximum number of bytes that can be uploaded using this session. If the size is not known when creating the session, this should be left blank. @@ -1548,11 +1551,11 @@ def get_iam_policy( :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current object's bucket. :type requested_policy_version: int or ``NoneType`` - :param requested_policy_version: Optional. The version of IAM policies to request. + :param requested_policy_version: (Optional) The version of IAM policies to request. If a policy with a condition is requested without setting this, the server will return an error. This must be set to a value of 3 to retrieve IAM @@ -1563,7 +1566,7 @@ def get_iam_policy( than the one that was requested, based on the feature syntax in the policy fetched. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1611,10 +1614,10 @@ def set_iam_policy(self, policy, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1662,10 +1665,10 @@ def test_iam_permissions(self, permissions, client=None, timeout=_DEFAULT_TIMEOU :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1693,7 +1696,7 @@ def make_public(self, client=None): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. """ self.acl.all().grant_read() @@ -1704,7 +1707,7 @@ def make_private(self, client=None): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. """ self.acl.all().revoke_read() @@ -1721,10 +1724,10 @@ def compose(self, sources, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1760,17 +1763,17 @@ def rewrite(self, source, token=None, client=None, timeout=_DEFAULT_TIMEOUT): :param source: blob whose contents will be rewritten into this blob. :type token: str - :param token: Optional. Token returned from an earlier, not-completed + :param token: (Optional) Token returned from an earlier, not-completed call to rewrite the same source blob. If passed, result will include updated status, total bytes written. :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1844,7 +1847,7 @@ def update_storage_class(self, new_class, client=None): :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 + :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: diff --git a/google/cloud/storage/bucket.py b/google/cloud/storage/bucket.py index 3079c12e9..c2a909357 100644 --- a/google/cloud/storage/bucket.py +++ b/google/cloud/storage/bucket.py @@ -146,26 +146,26 @@ class LifecycleRuleConditions(dict): See: https://cloud.google.com/storage/docs/lifecycle :type age: int - :param age: (optional) apply rule action to items whos age, in days, + :param age: (Optional) Apply rule action to items whos age, in days, exceeds this value. :type created_before: datetime.date - :param created_before: (optional) apply rule action to items created + :param created_before: (Optional) Apply rule action to items created before this date. :type is_live: bool - :param is_live: (optional) if true, apply rule action to non-versioned + :param is_live: (Optional) If true, apply rule action to non-versioned items, or to items with no newer versions. If false, apply rule action to versioned items with at least one newer version. :type matches_storage_class: list(str), one or more of :attr:`Bucket.STORAGE_CLASSES`. - :param matches_storage_class: (optional) apply rule action to items which + :param matches_storage_class: (Optional) Apply rule action to items which whose storage class matches this value. :type number_of_newer_versions: int - :param number_of_newer_versions: (optional) apply rule action to versioned + :param number_of_newer_versions: (Optional) Apply rule action to versioned items having N newer versions. :raises ValueError: if no arguments are passed. @@ -316,11 +316,11 @@ class IAMConfiguration(dict): :type uniform_bucket_level_access_enabled: bool :params bucket_policy_only_enabled: - (optional) whether the IAM-only policy is enabled for the bucket. + (Optional) Whether the IAM-only policy is enabled for the bucket. :type uniform_bucket_level_locked_time: :class:`datetime.datetime` :params uniform_bucket_level_locked_time: - (optional) When the bucket's IAM-only policy was enabled. + (Optional) When the bucket's IAM-only policy was enabled. This value should normally only be set by the back-end API. :type bucket_policy_only_enabled: bool @@ -549,7 +549,7 @@ 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. :rtype: :class:`google.cloud.storage.bucket.Bucket` :returns: The bucket object created. @@ -593,14 +593,14 @@ def blob( :type encryption_key: bytes :param encryption_key: - Optional 32 byte encryption key for customer-supplied encryption. + (Optional) 32 byte encryption key for customer-supplied encryption. :type kms_key_name: str :param kms_key_name: - Optional resource name of KMS key used to encrypt blob's content. + (Optional) Resource name of KMS key used to encrypt blob's content. :type generation: long - :param generation: Optional. If present, selects a specific revision of + :param generation: (Optional) If present, selects a specific revision of this object. :rtype: :class:`google.cloud.storage.blob.Blob` @@ -649,10 +649,10 @@ def exists(self, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -706,11 +706,11 @@ def create( :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type project: str - :param project: Optional. The project under which the bucket is to + :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. @@ -718,22 +718,22 @@ def create( :attr:`project` is also None. :type location: str - :param location: Optional. The location of the bucket. If not passed, + :param location: (Optional) The location of the bucket. If not passed, the default location, US, will be used. See https://cloud.google.com/storage/docs/bucket-locations :type predefined_acl: str :param predefined_acl: - Optional. Name of predefined ACL to apply to bucket. See: + (Optional) Name of predefined ACL to apply to bucket. See: https://cloud.google.com/storage/docs/access-control/lists#predefined-acl :type predefined_default_object_acl: str :param predefined_default_object_acl: - Optional. Name of predefined ACL to apply to bucket's objects. See: + (Optional) Name of predefined ACL to apply to bucket's objects. See: https://cloud.google.com/storage/docs/access-control/lists#predefined-acl :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -770,7 +770,7 @@ def patch(self, client=None, timeout=_DEFAULT_TIMEOUT): :param client: the client to use. If not passed, falls back to the ``client`` stored on the current object. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -841,21 +841,21 @@ def get_blob( :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type encryption_key: bytes :param encryption_key: - Optional 32 byte encryption key for customer-supplied encryption. + (Optional) 32 byte encryption key for customer-supplied encryption. See https://cloud.google.com/storage/docs/encryption#customer-supplied. :type generation: long - :param generation: Optional. If present, selects a specific revision of + :param generation: (Optional) If present, selects a specific revision of this object. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -916,7 +916,7 @@ def list_blobs( token. :type prefix: str - :param prefix: (Optional) prefix used to filter blobs. + :param prefix: (Optional) Prefix used to filter blobs. :type delimiter: str :param delimiter: (Optional) Delimiter, used with ``prefix`` to @@ -945,7 +945,7 @@ def list_blobs( to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -999,10 +999,10 @@ def list_notifications(self, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1036,10 +1036,10 @@ def get_notification(self, notification_id, client=None, timeout=_DEFAULT_TIMEOU :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: (optional) The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1085,10 +1085,10 @@ def delete(self, force=False, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response on each request. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1157,15 +1157,15 @@ def delete_blob( :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type generation: long - :param generation: Optional. If present, permanently deletes a specific + :param generation: (Optional) If present, permanently deletes a specific revision of this object. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1216,7 +1216,7 @@ def delete_blobs(self, blobs, on_error=None, client=None, timeout=_DEFAULT_TIMEO to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. The timeout applies to each individual blob delete request. @@ -1260,23 +1260,23 @@ def copy_blob( copied. :type new_name: str - :param new_name: (optional) the new name for the copied file. + :param new_name: (Optional) The new name for the copied file. :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type preserve_acl: bool - :param preserve_acl: Optional. Copies ACL from old blob to new blob. + :param preserve_acl: (Optional) Copies ACL from old blob to new blob. Default: True. :type source_generation: long - :param source_generation: Optional. The generation of the blob to be + :param source_generation: (Optional) The generation of the blob to be copied. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -1335,11 +1335,11 @@ def rename_blob(self, blob, new_name, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. The timeout applies to each individual request. @@ -1994,11 +1994,11 @@ def get_iam_policy( :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type requested_policy_version: int or ``NoneType`` - :param requested_policy_version: Optional. The version of IAM policies to request. + :param requested_policy_version: (Optional) The version of IAM policies to request. If a policy with a condition is requested without setting this, the server will return an error. This must be set to a value of 3 to retrieve IAM @@ -2010,7 +2010,7 @@ def get_iam_policy( feature syntax in the policy fetched. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -2075,11 +2075,11 @@ def set_iam_policy(self, policy, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -2120,11 +2120,11 @@ def test_iam_permissions(self, permissions, client=None, timeout=_DEFAULT_TIMEOU :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -2161,10 +2161,10 @@ def make_public( :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. The timeout applies to each underlying request. @@ -2227,11 +2227,11 @@ def make_private( :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. The timeout applies to each underlying request. @@ -2297,7 +2297,7 @@ def generate_upload_policy(self, conditions, expiration=None, client=None): /post-object#policydocument :type expiration: datetime - :param expiration: Optional expiration in UTC. If not specified, the + :param expiration: (Optional) Expiration in UTC. If not specified, the policy will expire in 1 hour. :type conditions: list @@ -2305,7 +2305,7 @@ def generate_upload_policy(self, conditions, expiration=None, client=None): `policy documents`_ documentation. :type client: :class:`~google.cloud.storage.client.Client` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :rtype: dict @@ -2345,7 +2345,7 @@ def lock_retention_policy(self, client=None, timeout=_DEFAULT_TIMEOUT): """Lock the bucket's retention policy. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -2437,7 +2437,7 @@ def generate_signed_url( :param expiration: Point in time when the signed URL should expire. :type api_access_endpoint: str - :param api_access_endpoint: Optional URI base. + :param api_access_endpoint: (Optional) URI base. :type method: str :param method: The HTTP verb that will be used when requesting the URL. diff --git a/google/cloud/storage/client.py b/google/cloud/storage/client.py index ed34ec16f..ad5b39f21 100644 --- a/google/cloud/storage/client.py +++ b/google/cloud/storage/client.py @@ -222,7 +222,7 @@ def get_service_account_email(self, project=None, timeout=_DEFAULT_TIMEOUT): (Optional) Project ID to use for retreiving GCS service account email address. Defaults to the client's project. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -250,7 +250,7 @@ def bucket(self, bucket_name, user_project=None): :param bucket_name: The name of the bucket to be instantiated. :type user_project: str - :param user_project: (Optional) the project ID to be billed for API + :param user_project: (Optional) The project ID to be billed for API requests made via the bucket. :rtype: :class:`google.cloud.storage.bucket.Bucket` @@ -336,7 +336,7 @@ def lookup_bucket(self, bucket_name, timeout=_DEFAULT_TIMEOUT): :param bucket_name: The name of the bucket to get. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -374,23 +374,23 @@ def create_bucket( The bucket resource to pass or name to create. requester_pays (bool): DEPRECATED. Use Bucket().requester_pays instead. - Optional. Whether requester pays for API requests for + (Optional) Whether requester pays for API requests for this bucket and its blobs. project (str): - Optional. The project under which the bucket is to be created. + (Optional) The project under which the bucket is to be created. If not passed, uses the project set on the client. user_project (str): - Optional. The project ID to be billed for API requests + (Optional) The project ID to be billed for API requests made via created bucket. location (str): - Optional. The location of the bucket. If not passed, + (Optional) The location of the bucket. If not passed, the default location, US, will be used. See https://cloud.google.com/storage/docs/bucket-locations predefined_acl (str): - Optional. Name of predefined ACL to apply to bucket. See: + (Optional) Name of predefined ACL to apply to bucket. See: https://cloud.google.com/storage/docs/access-control/lists#predefined-acl predefined_default_object_acl (str): - Optional. Name of predefined ACL to apply to bucket's objects. See: + (Optional) Name of predefined ACL to apply to bucket's objects. See: https://cloud.google.com/storage/docs/access-control/lists#predefined-acl timeout (Optional[Union[float, Tuple[float, float]]]): The amount of time, in seconds, to wait for the server response. @@ -488,9 +488,9 @@ def download_blob_to_file(self, blob_or_uri, file_obj, start=None, end=None): file_obj (file): A file handle to which to write the blob's data. start (int): - Optional. The first byte in a range to be downloaded. + (Optional) The first byte in a range to be downloaded. end (int): - Optional. The last byte in a range to be downloaded. + (Optional) The last byte in a range to be downloaded. Examples: Download a blob using using a blob resource. @@ -556,7 +556,7 @@ def list_blobs( token. prefix (str): - (Optional) prefix used to filter blobs. + (Optional) Prefix used to filter blobs. delimiter (str): (Optional) Delimiter, used with ``prefix`` to @@ -624,18 +624,18 @@ def list_buckets( This implements "storage.buckets.list". :type max_results: int - :param max_results: Optional. The maximum number of buckets to return. + :param max_results: (Optional) The maximum number of buckets to return. :type page_token: str :param page_token: - Optional. If present, return the next batch of buckets, using the + (Optional) If present, return the next batch of buckets, using the value, which must correspond to the ``nextPageToken`` value returned in the previous response. Deprecated: use the ``pages`` property of the returned iterator instead of manually passing the token. :type prefix: str - :param prefix: Optional. Filter results to buckets whose names begin + :param prefix: (Optional) Filter results to buckets whose names begin with this prefix. :type projection: str @@ -651,11 +651,11 @@ def list_buckets( bucket returned: 'items/id,nextPageToken' :type project: str - :param project: (Optional) the project whose buckets are to be listed. + :param project: (Optional) The project whose buckets are to be listed. If not passed, uses the project set on the client. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -708,14 +708,14 @@ def create_hmac_key( :param service_account_email: e-mail address of the service account :type project_id: str - :param project_id: (Optional) explicit project ID for the key. + :param project_id: (Optional) Explicit project ID for the key. Defaults to the client's project. :type user_project: str :param user_project: (Optional) This parameter is currently ignored. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -755,26 +755,26 @@ def list_hmac_keys( :type max_results: int :param max_results: - (Optional) max number of keys to return in a given page. + (Optional) Max number of keys to return in a given page. :type service_account_email: str :param service_account_email: - (Optional) limit keys to those created by the given service account. + (Optional) Limit keys to those created by the given service account. :type show_deleted_keys: bool :param show_deleted_keys: - (Optional) included deleted keys in the list. Default is to + (Optional) Included deleted keys in the list. Default is to exclude them. :type project_id: str - :param project_id: (Optional) explicit project ID for the key. + :param project_id: (Optional) Explicit project ID for the key. Defaults to the client's project. :type user_project: str :param user_project: (Optional) This parameter is currently ignored. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -819,11 +819,11 @@ def get_hmac_key_metadata( :param access_id: Unique ID of an existing key. :type project_id: str - :param project_id: (Optional) project ID of an existing key. + :param project_id: (Optional) Project ID of an existing key. Defaults to client's project. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). diff --git a/google/cloud/storage/hmac_key.py b/google/cloud/storage/hmac_key.py index 296b38e92..d9c451c68 100644 --- a/google/cloud/storage/hmac_key.py +++ b/google/cloud/storage/hmac_key.py @@ -25,10 +25,10 @@ class HMACKeyMetadata(object): :param client: client associated with the key metadata. :type access_id: str - :param access_id: (Optional) unique ID of an existing key. + :param access_id: (Optional) Unique ID of an existing key. :type project_id: str - :param project_id: (Optional) project ID of an existing key. + :param project_id: (Optional) Project ID of an existing key. Defaults to client's project. :type user_project: str @@ -191,7 +191,7 @@ def exists(self, timeout=_DEFAULT_TIMEOUT): """Determine whether or not the key for this metadata exists. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -218,7 +218,7 @@ def reload(self, timeout=_DEFAULT_TIMEOUT): """Reload properties from Cloud Storage. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -240,7 +240,7 @@ def update(self, timeout=_DEFAULT_TIMEOUT): """Save writable properties to Cloud Storage. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -266,7 +266,7 @@ def delete(self, timeout=_DEFAULT_TIMEOUT): """Delete the key from Cloud Storage. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). diff --git a/google/cloud/storage/notification.py b/google/cloud/storage/notification.py index e2af328c5..434a44dd1 100644 --- a/google/cloud/storage/notification.py +++ b/google/cloud/storage/notification.py @@ -55,25 +55,25 @@ class BucketNotification(object): :type topic_project: str :param topic_project: - (Optional) project ID of topic to which notifications are published. + (Optional) Project ID of topic to which notifications are published. If not passed, uses the project ID of the bucket's client. :type custom_attributes: dict :param custom_attributes: - (Optional) additional attributes passed with notification events. + (Optional) Additional attributes passed with notification events. :type event_types: list(str) :param event_types: - (Optional) event types for which notification events are published. + (Optional) Event types for which notification events are published. :type blob_name_prefix: str :param blob_name_prefix: - (Optional) prefix of blob names for which notification events are - published.. + (Optional) Prefix of blob names for which notification events are + published. :type payload_format: str :param payload_format: - (Optional) format of payload for notification events. + (Optional) Format of payload for notification events. :type notification_id: str :param notification_id: @@ -242,10 +242,10 @@ def create(self, client=None, timeout=_DEFAULT_TIMEOUT): to that project. :type client: :class:`~google.cloud.storage.client.Client` - :param client: (Optional) the client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the notification's bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -284,10 +284,10 @@ def exists(self, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -326,10 +326,10 @@ def reload(self, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout). @@ -362,10 +362,10 @@ def delete(self, client=None, timeout=_DEFAULT_TIMEOUT): :type client: :class:`~google.cloud.storage.client.Client` or ``NoneType`` - :param client: Optional. The client to use. If not passed, falls back + :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (optional) The amount of time, in seconds, to wait + :param timeout: (Optional) The amount of time, in seconds, to wait for the server response. Can also be passed as a tuple (connect_timeout, read_timeout).