Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings #1234

Merged
merged 3 commits into from
Apr 11, 2024
Merged

docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings #1234

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
60403da
docs: update DEFAULT_RETRY_IF_GENERATION_SPECIFIED docstrings
cojenco Feb 29, 2024
6e9c5ab
update docstrings
cojenco Apr 8, 2024
5a11688
Merge branch 'main' into generation-match
cojenco Apr 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 60 additions & 69 deletions google/cloud/storage/blob.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2759,26 +2759,19 @@ 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.
:param retry: (Optional) How to retry the RPC.
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, which
cojenco marked this conversation as resolved.
Show resolved Hide resolved
only uploads with ``if_generation_match`` or ``generation`` set will
be retried.

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.
Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if uploads are not guaranteed to be idempotent.
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 @@ -2924,26 +2917,19 @@ 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.
:param retry: (Optional) How to retry the RPC.
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, which
only uploads with ``if_generation_match`` or ``generation`` set will
be retried.

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.
Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if uploads are not guaranteed to be idempotent.
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 @@ -3053,26 +3039,19 @@ 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.
:param retry: (Optional) How to retry the RPC.
The default value is ``DEFAULT_RETRY_IF_GENERATION_SPECIFIED``, which
only uploads with ``if_generation_match`` or ``generation`` set will
be retried.

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.
Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if uploads are not guaranteed to be idempotent.
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 @@ -3199,23 +3178,19 @@ 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``, which
only uploads with ``if_generation_match`` or ``generation`` set will
be retried.

Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if uploads are not guaranteed to be idempotent.
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 @@ -3621,7 +3596,15 @@ 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``, which
only compose operations with ``if_generation_match`` or ``generation``
set will be retried.

Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if compose operations are not guaranteed to be idempotent.
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 @@ -3783,7 +3766,15 @@ 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``, which
only rewrites with ``if_generation_match`` or ``generation`` set will
be retried.

Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if rewrites are not guaranteed to be idempotent.
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
40 changes: 36 additions & 4 deletions google/cloud/storage/bucket.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1631,7 +1631,15 @@ 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``, which
only deletes with ``if_generation_match`` or ``generation`` set will
be retried.

Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if deletes are not guaranteed to be idempotent.
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 @@ -1732,7 +1740,15 @@ 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``, which
only delete operations with ``if_generation_match`` or ``generation`` set will
be retried.

Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if delete operations are not guaranteed to be idempotent.
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 @@ -1877,7 +1893,15 @@ 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``, which
only copy operations with ``if_generation_match`` or ``generation``
set will be retried.

Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if copy operations are not guaranteed to be idempotent.
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 @@ -2024,7 +2048,15 @@ 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``, which
only rename operations with ``if_generation_match`` or ``generation``
set will be retried.

Users can configure non-default retry behavior. A ``None`` value will
disable retries. A ``DEFAULT_RETRY`` value will enable retries
even if rename operations are not guaranteed to be idempotent.
See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).

:rtype: :class:`Blob`
:returns: The newly-renamed blob.
Expand Down