Skip to content

Commit

Permalink
docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings (#1234)
Browse files Browse the repository at this point in the history 
* docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings

* update docstrings
  • Loading branch information
@cojenco
cojenco committed Apr 11, 2024
1 parent 992f910 commit bdd426a
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 78 deletions.
139 changes: 65 additions & 74 deletions google/cloud/storage/blob.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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``
Expand Down Expand Up @@ -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)
Expand Down
32 changes: 28 additions & 4 deletions google/cloud/storage/bucket.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit bdd426a

Please sign in to comment.