Skip to content
This repository was archived by the owner on Mar 31, 2026. It is now read-only.

Commit bdd426a

Browse files
cojencocojenco
authored
docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings (#1234)
* docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings * update docstrings
1 parent 992f910 commit bdd426a

2 files changed

Lines changed: 93 additions & 78 deletions

File tree

‎google/cloud/storage/blob.py‎

Lines changed: 65 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -787,7 +787,13 @@ def delete(
787787
788788
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
789789
:param retry:
790-
(Optional) How to retry the RPC. See: :ref:`configuring_retries`
790+
(Optional) How to retry the RPC.
791+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
792+
policy which will only enable retries if ``if_generation_match`` or ``generation``
793+
is set, in order to ensure requests are idempotent before retrying them.
794+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
795+
to enable retries regardless of generation precondition setting.
796+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
791797
792798
:raises: :class:`google.cloud.exceptions.NotFound`
793799
(propagated from
@@ -2769,26 +2775,17 @@ def upload_from_file(
27692775
"md5", "crc32c" and None. The default is None.
27702776
27712777
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
2772-
:param retry: (Optional) How to retry the RPC. A None value will disable
2773-
retries. A google.api_core.retry.Retry value will enable retries,
2774-
and the object will define retriable response codes and errors and
2775-
configure backoff and timeout options.
2776-
2777-
A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
2778-
Retry object and activates it only if certain conditions are met.
2779-
This class exists to provide safe defaults for RPC calls that are
2780-
not technically safe to retry normally (due to potential data
2781-
duplication or other side-effects) but become safe to retry if a
2782-
condition such as if_generation_match is set.
2783-
2784-
See the retry.py source code and docstrings in this package
2785-
(google.cloud.storage.retry) for information on retry types and how
2786-
to configure them.
2778+
:param retry: (Optional) How to retry the RPC.
2779+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
2780+
policy which will only enable retries if ``if_generation_match`` or ``generation``
2781+
is set, in order to ensure requests are idempotent before retrying them.
2782+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
2783+
to enable retries regardless of generation precondition setting.
2784+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
27872785
27882786
Media operations (downloads and uploads) do not support non-default
2789-
predicates in a Retry object. The default will always be used. Other
2790-
configuration changes for Retry objects such as delays and deadlines
2791-
are respected.
2787+
predicates in a Retry object. Other configuration changes for Retry objects
2788+
such as delays and deadlines are respected.
27922789
27932790
:raises: :class:`~google.cloud.exceptions.GoogleCloudError`
27942791
if the upload response returns an error status.
@@ -2934,26 +2931,17 @@ def upload_from_filename(
29342931
"md5", "crc32c" and None. The default is None.
29352932
29362933
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
2937-
:param retry: (Optional) How to retry the RPC. A None value will disable
2938-
retries. A google.api_core.retry.Retry value will enable retries,
2939-
and the object will define retriable response codes and errors and
2940-
configure backoff and timeout options.
2941-
2942-
A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
2943-
Retry object and activates it only if certain conditions are met.
2944-
This class exists to provide safe defaults for RPC calls that are
2945-
not technically safe to retry normally (due to potential data
2946-
duplication or other side-effects) but become safe to retry if a
2947-
condition such as if_generation_match is set.
2948-
2949-
See the retry.py source code and docstrings in this package
2950-
(google.cloud.storage.retry) for information on retry types and how
2951-
to configure them.
2934+
:param retry: (Optional) How to retry the RPC.
2935+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
2936+
policy which will only enable retries if ``if_generation_match`` or ``generation``
2937+
is set, in order to ensure requests are idempotent before retrying them.
2938+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
2939+
to enable retries regardless of generation precondition setting.
2940+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
29522941
29532942
Media operations (downloads and uploads) do not support non-default
2954-
predicates in a Retry object. The default will always be used. Other
2955-
configuration changes for Retry objects such as delays and deadlines
2956-
are respected.
2943+
predicates in a Retry object. Other configuration changes for Retry objects
2944+
such as delays and deadlines are respected.
29572945
"""
29582946

29592947
self._handle_filename_and_upload(
@@ -3063,26 +3051,17 @@ def upload_from_string(
30633051
"md5", "crc32c" and None. The default is None.
30643052
30653053
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
3066-
:param retry: (Optional) How to retry the RPC. A None value will disable
3067-
retries. A google.api_core.retry.Retry value will enable retries,
3068-
and the object will define retriable response codes and errors and
3069-
configure backoff and timeout options.
3070-
3071-
A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
3072-
Retry object and activates it only if certain conditions are met.
3073-
This class exists to provide safe defaults for RPC calls that are
3074-
not technically safe to retry normally (due to potential data
3075-
duplication or other side-effects) but become safe to retry if a
3076-
condition such as if_generation_match is set.
3077-
3078-
See the retry.py source code and docstrings in this package
3079-
(google.cloud.storage.retry) for information on retry types and how
3080-
to configure them.
3054+
:param retry: (Optional) How to retry the RPC.
3055+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
3056+
policy which will only enable retries if ``if_generation_match`` or ``generation``
3057+
is set, in order to ensure requests are idempotent before retrying them.
3058+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
3059+
to enable retries regardless of generation precondition setting.
3060+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
30813061
30823062
Media operations (downloads and uploads) do not support non-default
3083-
predicates in a Retry object. The default will always be used. Other
3084-
configuration changes for Retry objects such as delays and deadlines
3085-
are respected.
3063+
predicates in a Retry object. Other configuration changes for Retry objects
3064+
such as delays and deadlines are respected.
30863065
"""
30873066
data = _to_bytes(data, encoding="utf-8")
30883067
string_buffer = BytesIO(data)
@@ -3209,23 +3188,17 @@ def create_resumable_upload_session(
32093188
(Optional) See :ref:`using-if-metageneration-not-match`
32103189
32113190
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
3212-
:param retry: (Optional) How to retry the RPC. A None value will disable
3213-
retries. A google.api_core.retry.Retry value will enable retries,
3214-
and the object will define retriable response codes and errors and
3215-
configure backoff and timeout options.
3216-
A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
3217-
Retry object and activates it only if certain conditions are met.
3218-
This class exists to provide safe defaults for RPC calls that are
3219-
not technically safe to retry normally (due to potential data
3220-
duplication or other side-effects) but become safe to retry if a
3221-
condition such as if_generation_match is set.
3222-
See the retry.py source code and docstrings in this package
3223-
(google.cloud.storage.retry) for information on retry types and how
3224-
to configure them.
3191+
:param retry: (Optional) How to retry the RPC.
3192+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
3193+
policy which will only enable retries if ``if_generation_match`` or ``generation``
3194+
is set, in order to ensure requests are idempotent before retrying them.
3195+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
3196+
to enable retries regardless of generation precondition setting.
3197+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
3198+
32253199
Media operations (downloads and uploads) do not support non-default
3226-
predicates in a Retry object. The default will always be used. Other
3227-
configuration changes for Retry objects such as delays and deadlines
3228-
are respected.
3200+
predicates in a Retry object. Other configuration changes for Retry objects
3201+
such as delays and deadlines are respected.
32293202
32303203
:rtype: str
32313204
:returns: The resumable upload session URL. The upload can be
@@ -3631,7 +3604,13 @@ def compose(
36313604
36323605
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
36333606
:param retry:
3634-
(Optional) How to retry the RPC. See: :ref:`configuring_retries`
3607+
(Optional) How to retry the RPC.
3608+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
3609+
policy which will only enable retries if ``if_generation_match`` or ``generation``
3610+
is set, in order to ensure requests are idempotent before retrying them.
3611+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
3612+
to enable retries regardless of generation precondition setting.
3613+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
36353614
"""
36363615
sources_len = len(sources)
36373616
client = self._require_client(client)
@@ -3793,7 +3772,13 @@ def rewrite(
37933772
37943773
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
37953774
:param retry:
3796-
(Optional) How to retry the RPC. See: :ref:`configuring_retries`
3775+
(Optional) How to retry the RPC.
3776+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
3777+
policy which will only enable retries if ``if_generation_match`` or ``generation``
3778+
is set, in order to ensure requests are idempotent before retrying them.
3779+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
3780+
to enable retries regardless of generation precondition setting.
3781+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
37973782
37983783
:rtype: tuple
37993784
:returns: ``(token, bytes_rewritten, total_bytes)``, where ``token``
@@ -3953,7 +3938,13 @@ def update_storage_class(
39533938
39543939
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
39553940
:param retry:
3956-
(Optional) How to retry the RPC. See: :ref:`configuring_retries`
3941+
(Optional) How to retry the RPC.
3942+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
3943+
policy which will only enable retries if ``if_generation_match`` or ``generation``
3944+
is set, in order to ensure requests are idempotent before retrying them.
3945+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
3946+
to enable retries regardless of generation precondition setting.
3947+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
39573948
"""
39583949
# Update current blob's storage class prior to rewrite
39593950
self._patch_property("storageClass", new_class)

‎google/cloud/storage/bucket.py‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1656,7 +1656,13 @@ def delete_blob(
16561656
16571657
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
16581658
:param retry:
1659-
(Optional) How to retry the RPC. See: :ref:`configuring_retries`
1659+
(Optional) How to retry the RPC.
1660+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
1661+
policy which will only enable retries if ``if_generation_match`` or ``generation``
1662+
is set, in order to ensure requests are idempotent before retrying them.
1663+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
1664+
to enable retries regardless of generation precondition setting.
1665+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
16601666
16611667
:raises: :class:`google.cloud.exceptions.NotFound` Raises a NotFound
16621668
if the blob isn't found. To suppress
@@ -1757,7 +1763,13 @@ def delete_blobs(
17571763
17581764
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
17591765
:param retry:
1760-
(Optional) How to retry the RPC. See: :ref:`configuring_retries`
1766+
(Optional) How to retry the RPC.
1767+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
1768+
policy which will only enable retries if ``if_generation_match`` or ``generation``
1769+
is set, in order to ensure requests are idempotent before retrying them.
1770+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
1771+
to enable retries regardless of generation precondition setting.
1772+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
17611773
17621774
:raises: :class:`~google.cloud.exceptions.NotFound` (if
17631775
`on_error` is not passed).
@@ -1902,7 +1914,13 @@ def copy_blob(
19021914
19031915
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
19041916
:param retry:
1905-
(Optional) How to retry the RPC. See: :ref:`configuring_retries`
1917+
(Optional) How to retry the RPC.
1918+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
1919+
policy which will only enable retries if ``if_generation_match`` or ``generation``
1920+
is set, in order to ensure requests are idempotent before retrying them.
1921+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
1922+
to enable retries regardless of generation precondition setting.
1923+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
19061924
19071925
:rtype: :class:`google.cloud.storage.blob.Blob`
19081926
:returns: The new Blob.
@@ -2049,7 +2067,13 @@ def rename_blob(
20492067
20502068
:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
20512069
:param retry:
2052-
(Optional) How to retry the RPC. See: :ref:`configuring_retries`
2070+
(Optional) How to retry the RPC.
2071+
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, a conditional retry
2072+
policy which will only enable retries if ``if_generation_match`` or ``generation``
2073+
is set, in order to ensure requests are idempotent before retrying them.
2074+
Change the value to ``DEFAULT_RETRY`` or another `google.api_core.retry.Retry` object
2075+
to enable retries regardless of generation precondition setting.
2076+
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
20532077
20542078
:rtype: :class:`Blob`
20552079
:returns: The newly-renamed blob.

0 commit comments

Comments
 (0)