From 475d1fbbdb39c3c955012288fe62dce9114c8645 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Mon, 7 Jun 2021 17:46:36 -0400 Subject: [PATCH 01/12] docs: add 'requests' intersphinx refs --- docs/conf.py | 1 + owlbot.py | 13 +++++++++++++ 2 files changed, 14 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index c61d72fcc..0e236c548 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -359,6 +359,7 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { "python": ("https://python.readthedocs.org/en/latest/", None), + "requests": ("https://docs.python-requests.org/en/master/", None), "google-auth": ("https://googleapis.dev/python/google-auth/latest/", None), "google.api_core": ("https://googleapis.dev/python/google-api-core/latest/", None,), "grpc": ("https://grpc.github.io/grpc/python/", None), diff --git a/owlbot.py b/owlbot.py index 945dfa91a..5b452c702 100644 --- a/owlbot.py +++ b/owlbot.py @@ -38,4 +38,17 @@ templated_files, excludes=["docs/multiprocessing.rst", "noxfile.py", "CONTRIBUTING.rst"], ) +s.replace( + "docs/conf.py", + """\ +intersphinx_mapping = { + "python": ("https://python.readthedocs.org/en/latest/", None), +""", + """\ +intersphinx_mapping = { + "python": ("https://python.readthedocs.org/en/latest/", None), + "requests": ("https://docs.python-requests.org/en/master/", None), +""", +) + s.shell.run(["nox", "-s", "blacken"], hide_output=False) From 6de23df1d3158b248e4f9e94415375c0480ba9a6 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Mon, 7 Jun 2021 17:57:13 -0400 Subject: [PATCH 02/12] docs: add narrative docs for timeouts and retries Include API docs for the 'retry' module, as well, to unbreak links. --- docs/index.rst | 1 + docs/retry_timeout.rst | 114 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 docs/retry_timeout.rst 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..5059a3e56 --- /dev/null +++ b/docs/retry_timeout.rst @@ -0,0 +1,114 @@ +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 +-------------------- + +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. + +Rather than using the default policy, 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.retry import Retry + + def is_retryable(exc): + ... # your retriable exception types here + + 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): + ... # your retriable exception types here + + 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: From 7c6d4ca135a275c8d8f8a5e68f04ffde3f5754b8 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Mon, 7 Jun 2021 17:59:17 -0400 Subject: [PATCH 03/12] docs: streamline 'timeout' / 'retry docstrngs Replace boilerplate with links to new narrative docs. Closes #455. --- google/cloud/storage/_helpers.py | 66 +---- google/cloud/storage/acl.py | 70 ++--- google/cloud/storage/batch.py | 8 +- google/cloud/storage/blob.py | 284 +++++------------- google/cloud/storage/bucket.py | 416 +++++++-------------------- google/cloud/storage/client.py | 104 ++----- google/cloud/storage/hmac_key.py | 88 ++---- google/cloud/storage/notification.py | 88 ++---- 8 files changed, 273 insertions(+), 851 deletions(-) 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. From 581a43c19fe12cd8827040e78223fc713eeca444 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Tue, 8 Jun 2021 18:48:13 -0400 Subject: [PATCH 04/12] fix: appease regex matching idols --- owlbot.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/owlbot.py b/owlbot.py index 5b452c702..8d9f19ab8 100644 --- a/owlbot.py +++ b/owlbot.py @@ -42,7 +42,7 @@ "docs/conf.py", """\ intersphinx_mapping = { - "python": ("https://python.readthedocs.org/en/latest/", None), + "python": \("https://python.readthedocs.org/en/latest/", None\), """, """\ intersphinx_mapping = { From a9014aaa71599f86c3cf5ce256cbf263ab3d32c3 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Tue, 8 Jun 2021 18:50:56 -0400 Subject: [PATCH 05/12] fix: fail owlbot if replacement misses --- owlbot.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/owlbot.py b/owlbot.py index 8d9f19ab8..b12ec7c29 100644 --- a/owlbot.py +++ b/owlbot.py @@ -38,7 +38,7 @@ templated_files, excludes=["docs/multiprocessing.rst", "noxfile.py", "CONTRIBUTING.rst"], ) -s.replace( +replaced = s.replace( "docs/conf.py", """\ intersphinx_mapping = { @@ -50,5 +50,6 @@ "requests": ("https://docs.python-requests.org/en/master/", None), """, ) +assert replaced == 1 s.shell.run(["nox", "-s", "blacken"], hide_output=False) From bcecbaf82ad834e5ae3956d918a6a279c1463ca9 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Tue, 8 Jun 2021 20:48:18 -0400 Subject: [PATCH 06/12] fix: add 'requests' intersphinx dep via library API Rather than hacking it in via replacement. --- owlbot.py | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/owlbot.py b/owlbot.py index b12ec7c29..0e23239ec 100644 --- a/owlbot.py +++ b/owlbot.py @@ -32,24 +32,13 @@ # 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( templated_files, excludes=["docs/multiprocessing.rst", "noxfile.py", "CONTRIBUTING.rst"], ) -replaced = s.replace( - "docs/conf.py", - """\ -intersphinx_mapping = { - "python": \("https://python.readthedocs.org/en/latest/", None\), -""", - """\ -intersphinx_mapping = { - "python": ("https://python.readthedocs.org/en/latest/", None), - "requests": ("https://docs.python-requests.org/en/master/", None), -""", -) -assert replaced == 1 - s.shell.run(["nox", "-s", "blacken"], hide_output=False) From 501bb176e9f006ec25d4e081113641ce1d70898f Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 9 Jun 2021 11:55:02 -0400 Subject: [PATCH 07/12] docs: add docstrings for default conditional policies. --- google/cloud/storage/retry.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) 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. +""" From 99f38cdddea14e29bd92b7c209a185b85e6f8b6f Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 9 Jun 2021 11:56:30 -0400 Subject: [PATCH 08/12] docs: flesh out retry docs - Explain semantics of default policies, and where used. - Provide an example of a predicate function for a conditional policy. Per review comments. --- docs/retry_timeout.rst | 40 +++++++++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/docs/retry_timeout.rst b/docs/retry_timeout.rst index 5059a3e56..0d27614dc 100644 --- a/docs/retry_timeout.rst +++ b/docs/retry_timeout.rst @@ -58,9 +58,31 @@ Configuring Retries 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. - -Rather than using the default policy, you may choose to configure an +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 bucket or blob has + the same "metageneration", 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. + +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.: @@ -75,10 +97,18 @@ explicit policy in your code. .. 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): - ... # your retriable exception types here + return isinstance(exc, _MY_RETRIABLE_TYPES) my_retry_policy = Retry(predicate=is_retryable) bucket = client.get_bucket(BUCKET_NAME, retry=my_retry_policy) @@ -98,7 +128,7 @@ explicit policy in your code. from google.cloud.storage.retry import is_etag_in_json def is_retryable(exc): - ... # your retriable exception types here + ... # as above my_retry_policy = Retry(predicate=is_retryable) my_cond_policy = ConditionalRetryPolicy( From 2162c289fc91bd42b59862b8f192e0d86601079e Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Wed, 9 Jun 2021 00:49:58 +0000 Subject: [PATCH 09/12] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 0e236c548..1691c5c04 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -359,12 +359,12 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { "python": ("https://python.readthedocs.org/en/latest/", None), - "requests": ("https://docs.python-requests.org/en/master/", None), "google-auth": ("https://googleapis.dev/python/google-auth/latest/", None), "google.api_core": ("https://googleapis.dev/python/google-api-core/latest/", None,), "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), } From 4b1f419c53ffd5d53bd625272b8545a2e314dab4 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 9 Jun 2021 12:20:20 -0400 Subject: [PATCH 10/12] docs: tweak Per review comments. --- docs/retry_timeout.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/retry_timeout.rst b/docs/retry_timeout.rst index 0d27614dc..965a5c4a0 100644 --- a/docs/retry_timeout.rst +++ b/docs/retry_timeout.rst @@ -65,7 +65,7 @@ for each method, base on its semantics: retries any API request which returns a "transient" error. - For API requests which are idempotent only if the bucket or blob has - the same "metageneration", the library uses its + 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. @@ -82,6 +82,9 @@ for each method, base on its semantics: 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. From 799012d067c7000a78b03737b5d36e42db20b094 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 9 Jun 2021 14:25:33 -0400 Subject: [PATCH 11/12] docs: tweak Further review comments. --- docs/retry_timeout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/retry_timeout.rst b/docs/retry_timeout.rst index 965a5c4a0..3567334e1 100644 --- a/docs/retry_timeout.rst +++ b/docs/retry_timeout.rst @@ -64,7 +64,7 @@ for each method, base on its semantics: :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 bucket or blob has +- 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, From 1a56e89397c5a7d9696fac0939ca7db383856767 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Thu, 10 Jun 2021 11:30:23 -0400 Subject: [PATCH 12/12] docs: add ref to back-end retry strategy docs Per review. --- docs/retry_timeout.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/retry_timeout.rst b/docs/retry_timeout.rst index 3567334e1..b7fc4ff41 100644 --- a/docs/retry_timeout.rst +++ b/docs/retry_timeout.rst @@ -55,6 +55,11 @@ See also: 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