From c502a9212a8fb1c86334e084af6cb6fc879ec58d Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Thu, 10 Jun 2021 12:35:28 -0400 Subject: [PATCH] docs: add narrative docs for conditional params - 'if_genration_match' - 'if_genration_not_match' - 'if_metageneration_match' - 'if_metageneration_not_match' Toward #460. --- docs/generation_metageneration.rst | 114 +++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 115 insertions(+) create mode 100644 docs/generation_metageneration.rst diff --git a/docs/generation_metageneration.rst b/docs/generation_metageneration.rst new file mode 100644 index 000000000..b7fd38a9f --- /dev/null +++ b/docs/generation_metageneration.rst @@ -0,0 +1,114 @@ +Conditional Requests Via Generation / Metageneration +==================================================== + +Concepts +-------- + +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 +``metageneration`` is incremented. + +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 increased, 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 `) or modifies +the blob (e.g., +:meth:`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 `) or modifies +the blob (e.g., +:meth:`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.reaload `, +:meth:`Bucket.reload `) +or modifies the blob or bucket (e.g., +:meth:`Blob.update ` +:meth:`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.reaload `, +:meth:`Bucket.reload `) +or modifies the blob or bucket (e.g., +:meth:`Blob.update ` +:meth:`Bucket.patch `) +makes the operation conditional on whether the resource's current +``metageneration`` does **not** match the given value. diff --git a/docs/index.rst b/docs/index.rst index 051bac888..9ece79741 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,6 +22,7 @@ API Reference hmac_key notification retry_timeout + generation_metageneration Changelog ---------