Skip to content
Permalink
Browse files
docs: streamline docstrings for conditional parmas (#464)
Add narrative docs for conditional params:

- 'if_generation_match'
- 'if_generation_not_match'
- 'if_metageneration_match'
- 'if_metageneration_not_match'

Streamline docstrings for conditional params, linking to new narrative docs.

Also, move 'timeout' argument to end (just before 'retry', if present) for consistency.

Closes #460.
  • Loading branch information
tseaver committed Jun 21, 2021
1 parent cf22a11 commit 69993702390322df07cc2e818003186a47524c2b
@@ -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.

Each time you patch or update the bucket's / blob's metadata, its
``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.
@@ -22,6 +22,7 @@ API Reference
hmac_key
notification
retry_timeout
generation_metageneration

Changelog
---------
@@ -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.
@@ -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:
@@ -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.
@@ -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:
@@ -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.
@@ -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:

0 comments on commit 6999370

Please sign in to comment.