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.

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: