docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings (#1234)

cojenco · web-flow · commit bdd426adf590 · 2024-04-10T19:06:31.000-07:00
* docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings

* update docstrings
diff --git a/google/cloud/storage/blob.py b/google/cloud/storage/blob.py
@@ -787,7 +787,13 @@ def delete(
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
-            (Optional) How to retry the RPC. See: :ref:`configuring_retries`
+            (Optional) How to retry the RPC.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
         :raises: :class:`google.cloud.exceptions.NotFound`
                  (propagated from
@@ -2769,26 +2775,17 @@ def upload_from_file(
             "md5", "crc32c" and None. The default is None.
 
         :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_generation_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.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
             Media operations (downloads and uploads) do not support non-default
-            predicates in a Retry object. The default will always be used. Other
-            configuration changes for Retry objects such as delays and deadlines
-            are respected.
+            predicates in a Retry object. Other configuration changes for Retry objects
+            such as delays and deadlines are respected.
 
         :raises: :class:`~google.cloud.exceptions.GoogleCloudError`
                  if the upload response returns an error status.
@@ -2934,26 +2931,17 @@ def upload_from_filename(
             "md5", "crc32c" and None. The default is None.
 
         :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_generation_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.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
             Media operations (downloads and uploads) do not support non-default
-            predicates in a Retry object. The default will always be used. Other
-            configuration changes for Retry objects such as delays and deadlines
-            are respected.
+            predicates in a Retry object. Other configuration changes for Retry objects
+            such as delays and deadlines are respected.
         """
 
         self._handle_filename_and_upload(
@@ -3063,26 +3051,17 @@ def upload_from_string(
             "md5", "crc32c" and None. The default is None.
 
         :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_generation_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.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
             Media operations (downloads and uploads) do not support non-default
-            predicates in a Retry object. The default will always be used. Other
-            configuration changes for Retry objects such as delays and deadlines
-            are respected.
+            predicates in a Retry object. Other configuration changes for Retry objects
+            such as delays and deadlines are respected.
         """
         data = _to_bytes(data, encoding="utf-8")
         string_buffer = BytesIO(data)
@@ -3209,23 +3188,17 @@ def create_resumable_upload_session(
             (Optional) See :ref:`using-if-metageneration-not-match`
 
         :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_generation_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.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
+
             Media operations (downloads and uploads) do not support non-default
-            predicates in a Retry object. The default will always be used. Other
-            configuration changes for Retry objects such as delays and deadlines
-            are respected.
+            predicates in a Retry object. Other configuration changes for Retry objects
+            such as delays and deadlines are respected.
 
         :rtype: str
         :returns: The resumable upload session URL. The upload can be
@@ -3631,7 +3604,13 @@ def compose(
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
-            (Optional) How to retry the RPC. See: :ref:`configuring_retries`
+            (Optional) How to retry the RPC.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
         """
         sources_len = len(sources)
         client = self._require_client(client)
@@ -3793,7 +3772,13 @@ def rewrite(
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
-            (Optional) How to retry the RPC. See: :ref:`configuring_retries`
+            (Optional) How to retry the RPC.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
         :rtype: tuple
         :returns: ``(token, bytes_rewritten, total_bytes)``, where ``token``
@@ -3953,7 +3938,13 @@ def update_storage_class(
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
-            (Optional) How to retry the RPC. See: :ref:`configuring_retries`
+            (Optional) How to retry the RPC.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
         """
         # Update current blob's storage class prior to rewrite
         self._patch_property("storageClass", new_class)
diff --git a/google/cloud/storage/bucket.py b/google/cloud/storage/bucket.py
@@ -1656,7 +1656,13 @@ def delete_blob(
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
-            (Optional) How to retry the RPC. See: :ref:`configuring_retries`
+            (Optional) How to retry the RPC.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
         :raises: :class:`google.cloud.exceptions.NotFound` Raises a NotFound
                  if the blob isn't found. To suppress
@@ -1757,7 +1763,13 @@ def delete_blobs(
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
-            (Optional) How to retry the RPC. See: :ref:`configuring_retries`
+            (Optional) How to retry the RPC.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
         :raises: :class:`~google.cloud.exceptions.NotFound` (if
                  `on_error` is not passed).
@@ -1902,7 +1914,13 @@ def copy_blob(
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
-            (Optional) How to retry the RPC. See: :ref:`configuring_retries`
+            (Optional) How to retry the RPC.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
         :rtype: :class:`google.cloud.storage.blob.Blob`
         :returns: The new Blob.
@@ -2049,7 +2067,13 @@ def rename_blob(
 
         :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
         :param retry:
-            (Optional) How to retry the RPC. See: :ref:`configuring_retries`
+            (Optional) How to retry the RPC.
+            The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
+            policy which will only enable retries if ``if_generation_match`` or ``generation``
+            is set, in order to ensure requests are idempotent before retrying them.
+            Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
+            to enable retries regardless of generation precondition setting.
+            See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
         :rtype: :class:`Blob`
         :returns: The newly-renamed blob.
