diff --git a/docs/conf.py b/docs/conf.py index c61d72fcc..1691c5c04 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -364,6 +364,7 @@ "grpc": ("https://grpc.github.io/grpc/python/", None), "proto-plus": ("https://proto-plus-python.readthedocs.io/en/latest/", None), "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None), + "requests": ("https://docs.python-requests.org/en/master/", None), } diff --git a/docs/index.rst b/docs/index.rst index 7a74f12cd..051bac888 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,6 +21,7 @@ API Reference constants hmac_key notification + retry_timeout Changelog --------- diff --git a/docs/retry_timeout.rst b/docs/retry_timeout.rst new file mode 100644 index 000000000..b7fc4ff41 --- /dev/null +++ b/docs/retry_timeout.rst @@ -0,0 +1,152 @@ +Configuring Timeouts and Retries +================================ + +When using object methods which invoke Google Cloud Storage API methods, +you have several options for how the library handles timeouts and +how it retries transient errors. + + +.. _configuring_timeouts: + +Configuring Timeouts +-------------------- + +For a number of reasons, methods which invoke API methods may take +longer than expected or desired. By default, such methods all time out +after a default interval, 60.0 seconds. Rather than blocking your application +code for that interval, you may choose to configure explicit timeouts +in your code, using one of three forms: + +- You can pass a single integer or float which functions as the timeout for the + entire request. E.g.: + +.. code-block:: python + + bucket = client.get_bucket(BUCKET_NAME, timeout=300.0) # five minutes + +- You can also be passed as a two-tuple, ``(connect_timeout, read_timeout)``, + where the ``connect_timeout`` sets the maximum time required to establish + the connection to the server, and the ``read_timeout`` sets the maximum + time to wait for a completed response. E.g.: + +.. code-block:: python + + bucket = client.get_bucket(BUCKET_NAME, timeout=(3, 10)) + + +- You can also pass ``None`` as the timeout value: in this case, the library + will block indefinitely for a response. E.g.: + +.. code-block:: python + + bucket = client.get_bucket(BUCKET_NAME, timeout=None) + +.. note:: + Depending on the retry strategy, a request may be + repeated several times using the same timeout each time. + +See also: + + :ref:`Timeouts in requests ` + + +.. _configuring_retries: + +Configuring Retries +-------------------- + +.. note:: + + For more background on retries, see also the + `GCS Retry Strategies Document `_ + +Methods which invoke API methods may fail for a number of reasons, some of +which represent "transient" conditions, and thus can be retried +automatically. The library tries to provide a sensible default retry policy +for each method, base on its semantics: + +- For API requests which are always idempotent, the library uses its + :data:`~google.cloud.storage.retry.DEFAULT_RETRY` policy, which + retries any API request which returns a "transient" error. + +- For API requests which are idempotent only if the blob has + the same "generation", the library uses its + :data:`~google.cloud.storage.retry.DEFAULT_RETRY_IF_GENERATION_SPECIFIED` + policy, which retries API requests which returns a "transient" error, + but only if the original request includes an ``ifGenerationMatch`` header. + +- For API requests which are idempotent only if the bucket or blob has + the same "metageneration", the library uses its + :data:`~google.cloud.storage.retry.DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED` + policy, which retries API requests which returns a "transient" error, + but only if the original request includes an ``ifMetagenerationMatch`` header. + +- For API requests which are idempotent only if the bucket or blob has + the same "etag", the library uses its + :data:`~google.cloud.storage.retry.DEFAULT_RETRY_IF_ETAG_IN_JSON` + policy, which retries API requests which returns a "transient" error, + but only if the original request includes an ``ETAG`` in its payload. + +- For those API requests which are never idempotent, the library passes + ``retry=None`` by default, suppressing any retries. + +Rather than using one of the default policies, you may choose to configure an +explicit policy in your code. + +- You can pass ``None`` as a retry policy to disable retries. E.g.: + +.. code-block:: python + + bucket = client.get_bucket(BUCKET_NAME, retry=None) + +- You can pass an instance of :class:`google.api_core.retry.Retry` to enable + retries; the passed object will define retriable response codes and errors, + as well as configuring backoff and retry interval options. E.g.: + +.. code-block:: python + + from google.api_core import exceptions + from google.api_core.retry import Retry + + _MY_RETRIABLE_TYPES = [ + exceptions.TooManyRequests, # 429 + exceptions.InternalServerError, # 500 + exceptions.BadGateway, # 502 + exceptions.ServiceUnavailable, # 503 + ] + + def is_retryable(exc): + return isinstance(exc, _MY_RETRIABLE_TYPES) + + my_retry_policy = Retry(predicate=is_retryable) + bucket = client.get_bucket(BUCKET_NAME, retry=my_retry_policy) + +- You can pass an instance of + :class:`google.cloud.storage.retry.ConditionalRetryPolicy`, which wraps a + :class:`~google.cloud.storage.retry.RetryPolicy`, activating it only if + certain conditions are met. This class exists to provide safe defaults + for RPC calls that are not technically safe to retry normally (due to + potential data duplication or other side-effects) but become safe to retry + if a condition such as if_metageneration_match is set. E.g.: + +.. code-block:: python + + from google.api_core.retry import Retry + from google.cloud.storage.retry import ConditionalRetryPolicy + from google.cloud.storage.retry import is_etag_in_json + + def is_retryable(exc): + ... # as above + + my_retry_policy = Retry(predicate=is_retryable) + my_cond_policy = ConditionalRetryPolicy( + my_retry_policy, conditional_predicate=is_etag_in_json) + bucket = client.get_bucket(BUCKET_NAME, retry=my_cond_policy) + + +Retry Module API +---------------- + +.. automodule:: google.cloud.storage.retry + :members: + :show-inheritance: diff --git a/google/cloud/storage/_helpers.py b/google/cloud/storage/_helpers.py index 83ed10b87..9e09fc9f2 100644 --- a/google/cloud/storage/_helpers.py +++ b/google/cloud/storage/_helpers.py @@ -162,11 +162,9 @@ def reload( properties to return. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: long :param if_generation_match: (Optional) Make the operation conditional on whether @@ -190,18 +188,8 @@ def reload( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ client = self._require_client(client) query_params = self._query_params @@ -275,11 +263,9 @@ def patch( ``client`` stored on the current object. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: long :param if_generation_match: (Optional) Make the operation conditional on whether @@ -303,18 +289,8 @@ def patch( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ client = self._require_client(client) query_params = self._query_params @@ -363,11 +339,9 @@ def update( ``client`` stored on the current object. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: long :param if_generation_match: (Optional) Make the operation conditional on whether @@ -391,18 +365,8 @@ def update( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ client = self._require_client(client) diff --git a/google/cloud/storage/acl.py b/google/cloud/storage/acl.py index bdb17bfc9..a17e4f09e 100644 --- a/google/cloud/storage/acl.py +++ b/google/cloud/storage/acl.py @@ -219,11 +219,9 @@ 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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` """ if not self.loaded: self.reload(timeout=timeout) @@ -442,20 +440,13 @@ def reload(self, client=None, timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY): :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: :class:`~google.api_core.retry.Retry` - :param retry: (Optional) How to retry the RPC. - - A None value will disable retries. - - A google.api_core.retry.Retry value will enable retries, - and the object will define retriable response codes and errors - and configure backoff and timeout options. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ path = self.reload_path client = self._require_client(client) @@ -489,21 +480,15 @@ def _save(self, acl, predefined, client, timeout=_DEFAULT_TIMEOUT): ``NoneType`` :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 - for the server response. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :type timeout: float or tuple + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: :class:`~google.api_core.retry.Retry` - :param retry: (Optional) How to retry the RPC. - - A None value will disable retries. - - A google.api_core.retry.Retry value will enable retries, - and the object will define retriable response codes and errors - and configure backoff and timeout options. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ client = self._require_client(client) query_params = {"projection": "full"} @@ -545,12 +530,11 @@ def save(self, acl=None, client=None, timeout=_DEFAULT_TIMEOUT): ``NoneType`` :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 - for the server response. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :type timeout: float or tuple + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` """ if acl is None: acl = self @@ -577,12 +561,11 @@ def save_predefined(self, predefined, client=None, timeout=_DEFAULT_TIMEOUT): ``NoneType`` :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 - for the server response. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :type timeout: float or tuple + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` """ predefined = self.validate_predefined(predefined) self._save(None, predefined, client, timeout=timeout) @@ -601,12 +584,11 @@ def clear(self, client=None, timeout=_DEFAULT_TIMEOUT): ``NoneType`` :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 - for the server response. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :type timeout: float or tuple + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` """ self.save([], client=client, timeout=timeout) diff --git a/google/cloud/storage/batch.py b/google/cloud/storage/batch.py index d40fdc6f5..732439f14 100644 --- a/google/cloud/storage/batch.py +++ b/google/cloud/storage/batch.py @@ -181,11 +181,9 @@ 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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :rtype: tuple of ``response`` (a dictionary of sorts) and ``content`` (a string). diff --git a/google/cloud/storage/blob.py b/google/cloud/storage/blob.py index fa3f5c7ac..3fb8a59b9 100644 --- a/google/cloud/storage/blob.py +++ b/google/cloud/storage/blob.py @@ -642,11 +642,8 @@ def exists( :type timeout: float or tuple :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). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: long :param if_generation_match: @@ -672,18 +669,8 @@ def exists( current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: bool :returns: True if the blob exists in Cloud Storage. @@ -740,11 +727,8 @@ def delete( :type timeout: float or tuple :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). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: long :param if_generation_match: @@ -770,18 +754,8 @@ def delete( current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises: :class:`google.cloud.exceptions.NotFound` (propagated from @@ -951,11 +925,8 @@ def _do_download( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -1092,11 +1063,8 @@ def download_to_file( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -1188,11 +1156,8 @@ def download_to_filename( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -1293,11 +1258,8 @@ def download_as_bytes( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -1391,11 +1353,8 @@ def download_as_string( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :rtype: bytes :returns: The data stored in this blob. @@ -1483,11 +1442,8 @@ def download_as_text( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :rtype: text :returns: The data stored in this blob, decoded to text. @@ -1678,11 +1634,8 @@ def _do_multipart_upload( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -1857,11 +1810,8 @@ def _initiate_resumable_upload( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -2035,11 +1985,8 @@ def _do_resumable_upload( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -2162,11 +2109,8 @@ def _do_upload( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -2341,11 +2285,8 @@ def upload_from_file( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -2478,11 +2419,8 @@ def upload_from_filename( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -2598,11 +2536,8 @@ def upload_from_string( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -2704,11 +2639,8 @@ def create_resumable_upload_session( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type checksum: str :param checksum: @@ -2794,25 +2726,12 @@ def get_iam_policy( :type timeout: float or tuple :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). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`google.api_core.iam.Policy` :returns: the policy instance, based on the resource returned from @@ -2867,25 +2786,12 @@ def set_iam_policy( :type timeout: float or tuple :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). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`google.api_core.iam.Policy` :returns: the policy instance, based on the resource returned from @@ -2937,25 +2843,12 @@ def test_iam_permissions( :type timeout: float or tuple :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). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: list of string :returns: the permissions returned by the ``testIamPermissions`` API @@ -2987,12 +2880,10 @@ def make_public(self, client=None, timeout=_DEFAULT_TIMEOUT): 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 - for the server response. The timeout applies to each underlying - request. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. """ self.acl.all().grant_read() self.acl.save(client=client, timeout=timeout) @@ -3006,12 +2897,9 @@ def make_private(self, client=None, timeout=_DEFAULT_TIMEOUT): 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 - for the server response. The timeout applies to each underlying - request. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` """ self.acl.all().revoke_read() self.acl.save(client=client, timeout=timeout) @@ -3039,11 +2927,9 @@ def compose( ``client`` stored on the blob's bucket. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: list of long :param if_generation_match: @@ -3059,18 +2945,8 @@ def compose( ``sources`` item-to-item. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` Example: Compose blobs using generation match preconditions. @@ -3179,11 +3055,8 @@ def rewrite( :type timeout: float or tuple :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). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: long :param if_generation_match: @@ -3233,18 +3106,8 @@ def rewrite( object's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: tuple :returns: ``(token, bytes_rewritten, total_bytes)``, where ``token`` @@ -3394,25 +3257,12 @@ def update_storage_class( :type timeout: float or tuple :param timeout: - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ if new_class not in self.STORAGE_CLASSES: raise ValueError("Invalid storage class: %s" % (new_class,)) diff --git a/google/cloud/storage/bucket.py b/google/cloud/storage/bucket.py index b79fc12e5..a4a27d7aa 100644 --- a/google/cloud/storage/bucket.py +++ b/google/cloud/storage/bucket.py @@ -737,11 +737,9 @@ def exists( to the ``client`` stored on the current bucket. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_metageneration_match: long :param if_metageneration_match: (Optional) Make the operation conditional on whether the @@ -752,18 +750,8 @@ def exists( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: bool :returns: True if the bucket exists in Cloud Storage. @@ -848,25 +836,13 @@ def create( 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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ warnings.warn( "Bucket.create() is deprecated and will be removed in future." @@ -907,11 +883,9 @@ def update( ``client`` stored on the current object. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_metageneration_match: long :param if_metageneration_match: (Optional) Make the operation conditional on whether the @@ -922,18 +896,8 @@ def update( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ super(Bucket, self).update( client=client, @@ -967,11 +931,9 @@ def reload( properties to return. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_metageneration_match: long :param if_metageneration_match: (Optional) Make the operation conditional on whether the @@ -982,18 +944,8 @@ def reload( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ super(Bucket, self).reload( client=client, @@ -1024,11 +976,9 @@ def patch( ``client`` stored on the current object. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_metageneration_match: long :param if_metageneration_match: (Optional) Make the operation conditional on whether the @@ -1039,18 +989,8 @@ def patch( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ # Special case: For buckets, it is possible that labels are being # removed; this requires special handling. @@ -1143,11 +1083,9 @@ def get_blob( this object. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: long :param if_generation_match: (Optional) Make the operation conditional on whether @@ -1171,18 +1109,8 @@ def get_blob( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :param kwargs: Keyword arguments to pass to the :class:`~google.cloud.storage.blob.Blob` constructor. @@ -1300,25 +1228,13 @@ 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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`~google.api_core.page_iterator.Iterator` :returns: Iterator of all :class:`~google.cloud.storage.blob.Blob` @@ -1365,25 +1281,13 @@ def list_notifications( :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: list of :class:`.BucketNotification` :returns: notification instances @@ -1418,25 +1322,13 @@ def get_notification( :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`.BucketNotification` :returns: notification instance. @@ -1497,25 +1389,13 @@ def delete( blob's current metageneration does not match the given value. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises: :class:`ValueError` if ``force`` is ``True`` and the bucket contains more than 256 objects / blobs. @@ -1608,11 +1488,9 @@ def delete_blob( revision of this object. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: long :param if_generation_match: (Optional) Make the operation conditional on whether @@ -1636,18 +1514,8 @@ def delete_blob( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises: :class:`google.cloud.exceptions.NotFound` (to suppress the exception, call ``delete_blobs``, passing a no-op @@ -1714,12 +1582,9 @@ def delete_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 - for the server response. The timeout applies to each individual - blob delete request. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: list of long :param if_generation_match: (Optional) Make the operation conditional on whether @@ -1747,18 +1612,8 @@ def delete_blobs( The list must match ``blobs`` item-to-item. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises: :class:`~google.cloud.exceptions.NotFound` (if `on_error` is not passed). @@ -1858,11 +1713,9 @@ def copy_blob( copied. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_generation_match: long :param if_generation_match: (Optional) Makes the operation @@ -1922,18 +1775,8 @@ def copy_blob( does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`google.cloud.storage.blob.Blob` :returns: The new Blob. @@ -2098,26 +1941,13 @@ def rename_blob( Also used in the delete request. :type timeout: float or tuple - :param timeout: (Optional) The amount of time, in seconds, to wait - for the server response. The timeout applies to each individual - request. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`Blob` :returns: The newly-renamed blob. @@ -2819,25 +2649,13 @@ 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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`google.api_core.iam.Policy` :returns: the policy instance, based on the resource returned from @@ -2908,25 +2726,13 @@ def set_iam_policy( to the ``client`` stored on the current bucket. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`google.api_core.iam.Policy` :returns: the policy instance, based on the resource returned from @@ -2972,25 +2778,13 @@ def test_iam_permissions( to the ``client`` stored on the current bucket. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: list of string :returns: the permissions returned by the ``testIamPermissions`` API @@ -3030,12 +2824,9 @@ def make_public( :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 - for the server response. The timeout applies to each underlying - request. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :raises ValueError: If ``recursive`` is True, and the bucket contains more than 256 @@ -3097,12 +2888,9 @@ def make_private( to the ``client`` stored on the current bucket. :type timeout: float or tuple - :param timeout: (Optional) The amount of time, in seconds, to wait - for the server response. The timeout applies to each underlying - request. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :raises ValueError: If ``recursive`` is True, and the bucket contains more than 256 @@ -3219,25 +3007,13 @@ def lock_retention_policy( 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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises ValueError: if the bucket has no metageneration (i.e., new or never reloaded); diff --git a/google/cloud/storage/client.py b/google/cloud/storage/client.py index 8fcc12b69..a9a06746a 100644 --- a/google/cloud/storage/client.py +++ b/google/cloud/storage/client.py @@ -259,25 +259,13 @@ def get_service_account_email( (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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: str :returns: service account email address @@ -799,11 +787,9 @@ def lookup_bucket( :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type if_metageneration_match: long :param if_metageneration_match: (Optional) Make the operation conditional on whether the @@ -814,18 +800,8 @@ def lookup_bucket( blob's current metageneration does not match the given value. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`google.cloud.storage.bucket.Bucket` :returns: The bucket matching the name provided or None if not found. @@ -1306,25 +1282,13 @@ def list_buckets( 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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: :class:`~google.api_core.page_iterator.Iterator` :raises ValueError: if both ``project`` is ``None`` and the client's @@ -1379,11 +1343,9 @@ def create_hmac_key( :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy :param retry: (Optional) How to retry the RPC. A None value will disable retries. @@ -1453,25 +1415,13 @@ def list_hmac_keys( :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: Tuple[:class:`~google.cloud.storage.hmac_key.HMACKeyMetadata`, str] @@ -1514,11 +1464,9 @@ def get_hmac_key_metadata( Defaults to client's project. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type user_project: str :param user_project: (Optional) This parameter is currently ignored. diff --git a/google/cloud/storage/hmac_key.py b/google/cloud/storage/hmac_key.py index e59960a1c..5cec51fa7 100644 --- a/google/cloud/storage/hmac_key.py +++ b/google/cloud/storage/hmac_key.py @@ -193,25 +193,13 @@ def exists(self, timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY): """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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: bool :returns: True if the key exists in Cloud Storage. @@ -234,25 +222,13 @@ def reload(self, timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY): """Reload properties from Cloud Storage. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises :class:`~google.api_core.exceptions.NotFound`: if the key does not exist on the back-end. @@ -270,25 +246,13 @@ def update(self, timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY_IF_ETAG_IN_JSON): """Save writable properties to Cloud Storage. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises :class:`~google.api_core.exceptions.NotFound`: if the key does not exist on the back-end. @@ -306,25 +270,13 @@ def delete(self, timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY): """Delete the key from Cloud Storage. :type timeout: float or tuple - :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). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises :class:`~google.api_core.exceptions.NotFound`: if the key does not exist on the back-end. diff --git a/google/cloud/storage/notification.py b/google/cloud/storage/notification.py index e86859466..d23343100 100644 --- a/google/cloud/storage/notification.py +++ b/google/cloud/storage/notification.py @@ -246,25 +246,13 @@ def create(self, client=None, timeout=_DEFAULT_TIMEOUT, retry=None): :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` """ if self.notification_id is not None: raise ValueError( @@ -298,25 +286,13 @@ def exists(self, client=None, timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY): :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :rtype: bool :returns: True, if the notification exists, else False. @@ -354,25 +330,13 @@ def reload(self, client=None, timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY): :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises ValueError: if the notification has no ID. @@ -405,25 +369,13 @@ def delete(self, client=None, timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY): :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 - for the server response. - - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + :param timeout: + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable retries. - A google.api_core.retry.Retry value will enable retries, and the object will - define retriable response codes and errors and configure backoff and timeout options. - - A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and - activates it only if certain conditions are met. This class exists to provide safe defaults - for RPC calls that are not technically safe to retry normally (due to potential data - duplication or other side-effects) but become safe to retry if a condition such as - if_metageneration_match is set. - - See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for - information on retry types and how to configure them. + :param retry: + (Optional) How to retry the RPC. See: :ref:`configuring_retries` :raises: :class:`google.api_core.exceptions.NotFound`: if the notification does not exist. diff --git a/google/cloud/storage/retry.py b/google/cloud/storage/retry.py index 7b9626ed5..a9cdc9c0d 100644 --- a/google/cloud/storage/retry.py +++ b/google/cloud/storage/retry.py @@ -139,9 +139,29 @@ def is_etag_in_json(data): DEFAULT_RETRY_IF_GENERATION_SPECIFIED = ConditionalRetryPolicy( DEFAULT_RETRY, is_generation_specified, ["query_params"] ) +"""Conditional wrapper for the default retry object. + +This retry setting will retry all _RETRYABLE_TYPES and any status codes from +_ADDITIONAL_RETRYABLE_STATUS_CODES, but only if the request included an +``ifGenerationMatch`` header. +""" + DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED = ConditionalRetryPolicy( DEFAULT_RETRY, is_metageneration_specified, ["query_params"] ) +"""Conditional wrapper for the default retry object. + +This retry setting will retry all _RETRYABLE_TYPES and any status codes from +_ADDITIONAL_RETRYABLE_STATUS_CODES, but only if the request included an +``ifMetagenerationMatch`` header. +""" + DEFAULT_RETRY_IF_ETAG_IN_JSON = ConditionalRetryPolicy( DEFAULT_RETRY, is_etag_in_json, ["data"] ) +"""Conditional wrapper for the default retry object. + +This retry setting will retry all _RETRYABLE_TYPES and any status codes from +_ADDITIONAL_RETRYABLE_STATUS_CODES, but only if the request included an +``ETAG`` entry in its payload. +""" diff --git a/owlbot.py b/owlbot.py index 945dfa91a..0e23239ec 100644 --- a/owlbot.py +++ b/owlbot.py @@ -32,6 +32,9 @@ # See: https://github.com/googleapis/python-storage/issues/226 "google-cloud-kms < 2.0dev", ], + intersphinx_dependencies = { + "requests": "https://docs.python-requests.org/en/master/" + }, ) s.move(