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.

Author: tseaver

docs/generation_metageneration.rst

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

docs/index.rst

@@ -22,6 +22,7 @@ API Reference
  hmac_key
  notification
  retry_timeout
+ generation_metageneration
 
 Changelog
 ---------

google/cloud/storage/_helpers.py

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