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: streamline docstrings for conditional parmas #464

Merged
merged 6 commits into from Jun 21, 2021
Merged

docs: streamline docstrings for conditional parmas #464

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c502a92
docs: add narrative docs for conditional params
tseaver Jun 10, 2021
7c04114
docs: streamline docstrings for conditional parmas
tseaver Jun 10, 2021
b9367f4
docs: add prologue, linking concepts
tseaver Jun 21, 2021
e8f2479
docs: wording changes / typo fixes
tseaver Jun 21, 2021
99f6d12
chore: install grpcio in docfx session
tseaver Jun 21, 2021
efc4fea
chore: typo fix
tseaver Jun 21, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
127 changes: 127 additions & 0 deletions docs/generation_metageneration.rst
View file
Open in desktop
@@ -0,0 +1,127 @@
Conditional Requests Via Generation / Metageneration Preconditions
==================================================================

Preconditions tell Cloud Storage to only perform a request if the
:ref:`generation <concept-generation>` or
:ref:`metageneration <concept-metageneration>` number of the affected object
meets your precondition criteria. These checks of the generation and
metageneration numbers ensure that the object is in the expected state,
allowing you to perform safe read-modify-write updates and conditional
operations on objects

Concepts
--------

.. _concept-metageneration:

Metageneration
::::::::::::::

When you create a :class:`~google.cloud.storage.bucket.Bucket`,
its :attr:`~google.cloud.storage.bucket.Bucket.metageneration` is initialized
to ``1``, representing the initial version of the bucket's metadata.

When you first upload a
:class:`~google.cloud.storage.blob.Blob` ("Object" in the GCS back-end docs),
its :attr:`~google.cloud.storage.blob.Blob.metageneration` is likewise
initialized to ``1``. representing the initial version of the blob's metadata.

The ``metageneration`` attribute is set by the GCS back-end, and is read-only
in the client library.

WHenever you patch or update the bucket / blob's metadata, its
tseaver marked this conversation as resolved.
Show resolved Hide resolved
``metageneration`` is incremented.


.. _concept-generation:

Generation
::::::::::

Each time you upload a new version of a file to a
:class:`~google.cloud.storage.blob.Blob` ("Object" in the GCS back-end docs),
the Blob's :attr:`~google.cloud.storage.blob.generation` is changed, and its
:attr:`~google.cloud.storage.blob.metageneration` is reset to ``1`` (the first
metadata version for that generation of the blob).

The ``generation`` attribute is set by the GCS back-end, and is read-only
in the client library.

See also
::::::::

- `Storage API Generation Precondition docs`_

.. _Storage API Generation Precondition docs:
https://cloud.google.com/storage/docs/generations-preconditions


Conditional Parameters
----------------------

.. _using-if-generation-match:

Using ``if_generation_match``
:::::::::::::::::::::::::::::

Passing the ``if_generation_match`` parameter to a method which retrieves a
blob resource (e.g.,
:meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`) or modifies
the blob (e.g.,
:meth:`Blob.update <google.cloud.storage.blob.Blob.update>`)
makes the operation conditional on whether the blob's current ``generation``
matches the given value.

As a special case, passing ``0`` as the value for``if_generation_match``
makes the operation succeed only if there are no live versions of the blob.


.. _using-if-generation-not-match:

Using ``if_generation_not_match``
:::::::::::::::::::::::::::::::::

Passing the ``if_generation_not_match`` parameter to a method which retrieves
a blob resource (e.g.,
:meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`) or modifies
the blob (e.g.,
:meth:`Blob.update <google.cloud.storage.blob.Blob.update>`)
makes the operation conditional on whether the blob's current ``generation``
does **not** match the given value.

If no live version of the blob exists, the precondition fails.

As a special case, passing ``0`` as the value for ``if_generation_not_match``
makes the operation succeed only if there **is** a live version of the blob.


.. _using-if-metageneration-match:

Using ``if_metageneration_match``
:::::::::::::::::::::::::::::::::

Passing the ``if_metageneration_match`` parameter to a method which retrieves
a blob or bucket resource
(e.g., :meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`,
:meth:`Bucket.reload <google.cloud.storage.bucket.Bucket.reload>`)
or modifies the blob or bucket (e.g.,
:meth:`Blob.update <google.cloud.storage.blob.Blob.update>`
:meth:`Bucket.patch <google.cloud.storage.bucket.Bucket.patch>`)
makes the operation conditional on whether the resource's current
``metageneration`` matches the given value.


.. _using-if-metageneration-not-match:

Using ``if_metageneration_not_match``
:::::::::::::::::::::::::::::::::::::

Passing the ``if_metageneration_not_match`` parameter to a method which
retrieves a blob or bucket resource
(e.g., :meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`,
:meth:`Bucket.reload <google.cloud.storage.bucket.Bucket.reload>`)
or modifies the blob or bucket (e.g.,
:meth:`Blob.update <google.cloud.storage.blob.Blob.update>`
:meth:`Bucket.patch <google.cloud.storage.bucket.Bucket.patch>`)
makes the operation conditional on whether the resource's current
``metageneration`` does **not** match the given value.
1 change: 1 addition & 0 deletions docs/index.rst
View file
Open in desktop
Expand Up @@ -22,6 +22,7 @@ API Reference
hmac_key
notification
retry_timeout
generation_metageneration

Changelog
---------
Expand Down
99 changes: 42 additions & 57 deletions google/cloud/storage/_helpers.py
View file
Open in desktop
Expand Up @@ -147,11 +147,11 @@ def reload(
self,
client=None,
projection="noAcl",
timeout=_DEFAULT_TIMEOUT,
if_generation_match=None,
if_generation_not_match=None,
if_metageneration_match=None,
if_metageneration_not_match=None,
timeout=_DEFAULT_TIMEOUT,
retry=DEFAULT_RETRY,
):
"""Reload properties from Cloud Storage.
Expand All @@ -168,31 +168,26 @@ def reload(
Defaults to ``'noAcl'``. Specifies the set of
properties to return.

:type timeout: float or tuple
:param timeout:
(Optional) The amount of time, in seconds, to wait
for the server response. See: :ref:`configuring_timeouts`

:type if_generation_match: long
:param if_generation_match: (Optional) Make the operation conditional on whether
the blob's current generation matches the given value.
Setting to 0 makes the operation succeed only if there
are no live versions of the blob.
:param if_generation_match:
(Optional) See :ref:`using-if-generation-match`

:type if_generation_not_match: long
:param if_generation_not_match: (Optional) Make the operation conditional on whether
the blob's current generation does not match the given
value. If no live blob exists, the precondition fails.
Setting to 0 makes the operation succeed only if there
is a live version of the blob.
:param if_generation_not_match:
(Optional) See :ref:`using-if-generation-not-match`

:type if_metageneration_match: long
:param if_metageneration_match: (Optional) Make the operation conditional on whether the
blob's current metageneration matches the given value.
:param if_metageneration_match:
(Optional) See :ref:`using-if-metageneration-match`

:type if_metageneration_not_match: long
:param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
blob's current metageneration does not match the given value.
:param if_metageneration_not_match:
(Optional) See :ref:`using-if-metageneration-not-match`

:type timeout: float or tuple
:param timeout:
(Optional) The amount of time, in seconds, to wait
for the server response. See: :ref:`configuring_timeouts`

:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
:param retry:
Expand Down Expand Up @@ -251,11 +246,11 @@ def _set_properties(self, value):
def patch(
self,
client=None,
timeout=_DEFAULT_TIMEOUT,
if_generation_match=None,
if_generation_not_match=None,
if_metageneration_match=None,
if_metageneration_not_match=None,
timeout=_DEFAULT_TIMEOUT,
retry=DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED,
):
"""Sends all changed properties in a PATCH request.
Expand All @@ -269,31 +264,26 @@ def patch(
:param client: the client to use. If not passed, falls back to the
``client`` stored on the current object.

:type timeout: float or tuple
:param timeout:
(Optional) The amount of time, in seconds, to wait
for the server response. See: :ref:`configuring_timeouts`

:type if_generation_match: long
:param if_generation_match: (Optional) Make the operation conditional on whether
the blob's current generation matches the given value.
Setting to 0 makes the operation succeed only if there
are no live versions of the blob.
:param if_generation_match:
(Optional) See :ref:`using-if-generation-match`

:type if_generation_not_match: long
:param if_generation_not_match: (Optional) Make the operation conditional on whether
the blob's current generation does not match the given
value. If no live blob exists, the precondition fails.
Setting to 0 makes the operation succeed only if there
is a live version of the blob.
:param if_generation_not_match:
(Optional) See :ref:`using-if-generation-not-match`

:type if_metageneration_match: long
:param if_metageneration_match: (Optional) Make the operation conditional on whether the
blob's current metageneration matches the given value.
:param if_metageneration_match:
(Optional) See :ref:`using-if-metageneration-match`

:type if_metageneration_not_match: long
:param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
blob's current metageneration does not match the given value.
:param if_metageneration_not_match:
(Optional) See :ref:`using-if-metageneration-not-match`

:type timeout: float or tuple
:param timeout:
(Optional) The amount of time, in seconds, to wait
for the server response. See: :ref:`configuring_timeouts`

:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
:param retry:
Expand Down Expand Up @@ -327,11 +317,11 @@ def patch(
def update(
self,
client=None,
timeout=_DEFAULT_TIMEOUT,
if_generation_match=None,
if_generation_not_match=None,
if_metageneration_match=None,
if_metageneration_not_match=None,
timeout=_DEFAULT_TIMEOUT,
retry=DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED,
):
"""Sends all properties in a PUT request.
Expand All @@ -345,31 +335,26 @@ def update(
:param client: the client to use. If not passed, falls back to the
``client`` stored on the current object.

:type timeout: float or tuple
:param timeout:
(Optional) The amount of time, in seconds, to wait
for the server response. See: :ref:`configuring_timeouts`

:type if_generation_match: long
:param if_generation_match: (Optional) Make the operation conditional on whether
the blob's current generation matches the given value.
Setting to 0 makes the operation succeed only if there
are no live versions of the blob.
:param if_generation_match:
(Optional) See :ref:`using-if-generation-match`

:type if_generation_not_match: long
:param if_generation_not_match: (Optional) Make the operation conditional on whether
the blob's current generation does not match the given
value. If no live blob exists, the precondition fails.
Setting to 0 makes the operation succeed only if there
is a live version of the blob.
:param if_generation_not_match:
(Optional) See :ref:`using-if-generation-not-match`

:type if_metageneration_match: long
:param if_metageneration_match: (Optional) Make the operation conditional on whether the
blob's current metageneration matches the given value.
:param if_metageneration_match:
(Optional) See :ref:`using-if-metageneration-match`

:type if_metageneration_not_match: long
:param if_metageneration_not_match: (Optional) Make the operation conditional on whether the
blob's current metageneration does not match the given value.
:param if_metageneration_not_match:
(Optional) See :ref:`using-if-metageneration-not-match`

:type timeout: float or tuple
:param timeout:
(Optional) The amount of time, in seconds, to wait
for the server response. See: :ref:`configuring_timeouts`

:type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy
:param retry:
Expand Down