docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings (#1234)

* docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings * update docstrings

Author: cojenco

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)

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.