diff --git a/docs/generation_metageneration.rst b/docs/generation_metageneration.rst new file mode 100644 index 000000000..287e6573a --- /dev/null +++ b/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 ` or +:ref:`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 `) 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.reload `, +: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.reload `, +: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 --------- diff --git a/google/cloud/storage/_helpers.py b/google/cloud/storage/_helpers.py index 04671035b..ff5767de7 100644 --- a/google/cloud/storage/_helpers.py +++ b/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: diff --git a/google/cloud/storage/blob.py b/google/cloud/storage/blob.py index c22e6699c..60178aa2e 100644 --- a/google/cloud/storage/blob.py +++ b/google/cloud/storage/blob.py @@ -116,6 +116,25 @@ "A checksum of type `{}` was requested, but checksumming is not available " "for downloads when chunk_size is set." ) +_COMPOSE_IF_GENERATION_LIST_DEPRECATED = ( + "'if_generation_match: type list' is deprecated and supported for " + "backwards-compatability reasons only. Use 'if_source_generation_match' " + "instead' to match source objects' generations.", +) +_COMPOSE_IF_GENERATION_LIST_AND_IF_SOURCE_GENERATION_ERROR = ( + "Use 'if_generation_match' to match the generation of the destination " + "object by passing in a generation number, instead of a list. " + "Use 'if_source_generation_match' to match source objects generations." +) +_COMPOSE_IF_METAGENERATION_LIST_DEPRECATED = ( + "'if_metageneration_match: type list' is deprecated and supported for " + "backwards-compatability reasons only. Note that the metageneration to " + "be matched is that of the destination blob. Please pass in a single " + "value (type long).", +) +_COMPOSE_IF_SOURCE_GENERATION_MISMATCH_ERROR = ( + "'if_source_generation_match' length must be the same as 'sources' length" +) _DEFAULT_CHUNKSIZE = 104857600 # 1024 * 1024 B * 100 = 100 MB @@ -616,11 +635,11 @@ def generate_signed_url( def exists( 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, ): """Determines whether or not this blob exists. @@ -633,33 +652,26 @@ def exists( (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. - :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. + (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. + (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. + (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. + (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: @@ -701,11 +713,11 @@ def exists( def delete( 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_GENERATION_SPECIFIED, ): """Deletes a blob from Cloud Storage. @@ -718,33 +730,26 @@ def delete( (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. - :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. + (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. + (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. + (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. + (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: @@ -801,25 +806,19 @@ def _get_download_url( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :rtype: str :returns: The download URL for the current blob. @@ -1056,25 +1055,19 @@ def download_to_file( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -1173,25 +1166,19 @@ def download_to_filename( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -1299,25 +1286,19 @@ def download_as_bytes( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -1418,25 +1399,19 @@ def download_as_string( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -1530,26 +1505,19 @@ def download_as_text( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -1746,26 +1714,19 @@ def _do_multipart_upload( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -1937,26 +1898,19 @@ def _initiate_resumable_upload( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -2127,26 +2081,19 @@ def _do_resumable_upload( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -2268,26 +2215,19 @@ def _do_upload( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -2473,26 +2413,19 @@ def upload_from_file( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -2636,26 +2569,19 @@ def upload_from_filename( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -2777,26 +2703,19 @@ def upload_from_string( :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. + (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. + (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. + (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. + (Optional) See :ref:`using-if-metageneration-not-match` :type timeout: float or tuple :param timeout: @@ -3226,10 +3145,13 @@ def compose( Setting to 0 makes the operation succeed only if there are no live versions of the object. - Note: In a previous version, this argument worked identically to the - ``if_source_generation_match`` argument. For backwards-compatibility reasons, - if a list is passed in, this argument will behave like ``if_source_generation_match`` - and also issue a DeprecationWarning. + .. note:: + + In a previous version, this argument worked identically to the + ``if_source_generation_match`` argument. For + backwards-compatibility reasons, if a list is passed in, + this argument will behave like ``if_source_generation_match`` + and also issue a DeprecationWarning. :type if_metageneration_match: long :param if_metageneration_match: @@ -3237,13 +3159,14 @@ def compose( destination object's current metageneration matches the given value. - If a list of long is passed in, no match operation will be performed. - (Deprecated: type(list of long) is supported for backwards-compatability reasons only.) + If a list of long is passed in, no match operation will be + performed. (Deprecated: type(list of long) is supported for + backwards-compatability reasons only.) :type if_source_generation_match: list of long :param if_source_generation_match: - (Optional) Makes the operation conditional on whether the current generation - of each source blob matches the corresponding generation. + (Optional) Makes the operation conditional on whether the current + generation of each source blob matches the corresponding generation. The list must match ``sources`` item-to-item. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy @@ -3270,27 +3193,22 @@ def compose( if isinstance(if_generation_match, list): warnings.warn( - "if_generation_match: type list is deprecated and supported for backwards-compatability reasons only." - "Use if_source_generation_match instead to match source objects generations.", + _COMPOSE_IF_GENERATION_LIST_DEPRECATED, DeprecationWarning, stacklevel=2, ) if if_source_generation_match is not None: raise ValueError( - "Use if_generation_match to match the generation of the destination object by passing in a generation number, instead of a list." - "Use if_source_generation_match to match source objects generations." + _COMPOSE_IF_GENERATION_LIST_AND_IF_SOURCE_GENERATION_ERROR ) - # if_generation_match: type list is deprecated. Instead use if_source_generation_match. if_source_generation_match = if_generation_match if_generation_match = None if isinstance(if_metageneration_match, list): warnings.warn( - "if_metageneration_match: type list is deprecated and supported for backwards-compatability reasons only." - "Note that the metageneration to be matched is that of the destination blob." - "Please pass in a single value (type long).", + _COMPOSE_IF_METAGENERATION_LIST_DEPRECATED, DeprecationWarning, stacklevel=2, ) @@ -3300,9 +3218,7 @@ def compose( if if_source_generation_match is None: if_source_generation_match = [None] * sources_len if len(if_source_generation_match) != sources_len: - raise ValueError( - "'if_source_generation_match' length must be the same as 'sources' length" - ) + raise ValueError(_COMPOSE_IF_SOURCE_GENERATION_MISMATCH_ERROR) source_objects = [] for source, source_generation in zip(sources, if_source_generation_match): @@ -3346,7 +3262,6 @@ def rewrite( source, token=None, client=None, - timeout=_DEFAULT_TIMEOUT, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, @@ -3355,6 +3270,7 @@ def rewrite( if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, + timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY_IF_GENERATION_SPECIFIED, ): """Rewrite source blob into this one. @@ -3376,37 +3292,29 @@ def rewrite( (Optional) The client to use. If not passed, falls back to the ``client`` stored on the blob's bucket. - :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) Makes the operation conditional on whether the - destination object's current generation matches the given value. - Setting to 0 makes the operation succeed only if there are no live - versions of the object. + (Optional) See :ref:`using-if-generation-match` + Note that the generation to be matched is that of the + ``destination`` blob. :type if_generation_not_match: long :param if_generation_not_match: - (Optional) Makes the operation conditional on whether the - destination object's current generation does not match the given - value. If no live object exists, the precondition fails. Setting to - 0 makes the operation succeed only if there is a live version of - the object. + (Optional) See :ref:`using-if-generation-not-match` + Note that the generation to be matched is that of the + ``destination`` blob. :type if_metageneration_match: long :param if_metageneration_match: - (Optional) Makes the operation conditional on whether the - destination object's current metageneration matches the given - value. + (Optional) See :ref:`using-if-metageneration-match` + Note that the metageneration to be matched is that of the + ``destination`` blob. :type if_metageneration_not_match: long :param if_metageneration_not_match: - (Optional) Makes the operation conditional on whether the - destination object's current metageneration does not match the - given value. + (Optional) See :ref:`using-if-metageneration-not-match` + Note that the metageneration to be matched is that of the + ``destination`` blob. :type if_source_generation_match: long :param if_source_generation_match: @@ -3428,6 +3336,11 @@ def rewrite( (Optional) Makes the operation conditional on whether the source object's current metageneration does not match the given value. + :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: (Optional) How to retry the RPC. See: :ref:`configuring_retries` @@ -3533,30 +3446,27 @@ def update_storage_class( :type if_generation_match: long :param if_generation_match: - (Optional) Makes the operation conditional on whether the - destination object's current generation matches the given value. - Setting to 0 makes the operation succeed only if there are no live - versions of the object. + (Optional) See :ref:`using-if-generation-match` + Note that the generation to be matched is that of the + ``destination`` blob. :type if_generation_not_match: long :param if_generation_not_match: - (Optional) Makes the operation conditional on whether the - destination object's current generation does not match the given - value. If no live object exists, the precondition fails. Setting to - 0 makes the operation succeed only if there is a live version of - the object. + (Optional) See :ref:`using-if-generation-not-match` + Note that the generation to be matched is that of the + ``destination`` blob. :type if_metageneration_match: long :param if_metageneration_match: - (Optional) Makes the operation conditional on whether the - destination object's current metageneration matches the given - value. + (Optional) See :ref:`using-if-metageneration-match` + Note that the metageneration to be matched is that of the + ``destination`` blob. :type if_metageneration_not_match: long :param if_metageneration_not_match: - (Optional) Makes the operation conditional on whether the - destination object's current metageneration does not match the - given value. + (Optional) See :ref:`using-if-metageneration-not-match` + Note that the metageneration to be matched is that of the + ``destination`` blob. :type if_source_generation_match: long :param if_source_generation_match: @@ -3691,15 +3601,30 @@ def open( newline mode" and writes use the system default. See the Python 'io' module documentation for 'io.TextIOWrapper' for details. - :param kwargs: Keyword arguments to pass to the underlying API calls. + :param kwargs: + Keyword arguments to pass to the underlying API calls. For both uploads and downloads, the following arguments are - supported: "if_generation_match", "if_generation_not_match", - "if_metageneration_match", "if_metageneration_not_match", "timeout", - "retry". For uploads only, the following additional arguments are - supported: "content_type", "num_retries", "predefined_acl", - "checksum". "num_retries" is supported for backwards-compatibility - reasons only; please use "retry" with a Retry object or - ConditionalRetryPolicy instead. + supported: + + - ``if_generation_match`` + - ``if_generation_not_match`` + - ``if_metageneration_match`` + - ``if_metageneration_not_match`` + - ``timeout`` + - ``retry`` + + For uploads only, the following additional arguments are supported: + + - ``content_type`` + - ``num_retries`` + - ``predefined_acl`` + - ``checksum`` + + .. note:: + + ``num_retries`` is supported for backwards-compatibility + reasons only; please use ``retry`` with a Retry object or + ConditionalRetryPolicy instead. :returns: A 'BlobReader' or 'BlobWriter' from 'google.cloud.storage.fileio', or an 'io.TextIOWrapper' around one diff --git a/google/cloud/storage/bucket.py b/google/cloud/storage/bucket.py index a4a27d7aa..0dc4ef76d 100644 --- a/google/cloud/storage/bucket.py +++ b/google/cloud/storage/bucket.py @@ -1045,11 +1045,11 @@ def get_blob( client=None, encryption_key=None, generation=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, **kwargs ): @@ -1079,34 +1079,29 @@ def get_blob( https://cloud.google.com/storage/docs/encryption#customer-supplied. :type generation: long - :param generation: (Optional) If present, selects a specific revision of - this 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` + :param generation: + (Optional) If present, selects a specific revision of this object. :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: @@ -1454,11 +1449,11 @@ def delete_blob( blob_name, client=None, generation=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_GENERATION_SPECIFIED, ): """Deletes a blob from the current bucket. @@ -1487,31 +1482,26 @@ def delete_blob( :param generation: (Optional) If present, permanently deletes a specific revision of this 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: @@ -1581,35 +1571,31 @@ def delete_blobs( :param client: (Optional) The client to use. If not passed, falls back to the ``client`` stored on the current bucket. - :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: list of 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. The list must match - ``blobs`` item-to-item. + :param if_generation_match: + (Optional) See :ref:`using-if-generation-match` + Note that the length of the list must match the length of + The list must match ``blobs`` item-to-item. :type if_generation_not_match: list of 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. The list must match - ``blobs`` item-to-item. + :param if_generation_not_match: + (Optional) See :ref:`using-if-generation-not-match` + The list must match ``blobs`` item-to-item. :type if_metageneration_match: list of long - :param if_metageneration_match: (Optional) Make the operation conditional on whether the - blob's current metageneration matches the given value. - The list must match ``blobs`` item-to-item. + :param if_metageneration_match: + (Optional) See :ref:`using-if-metageneration-match` + The list must match ``blobs`` item-to-item. :type if_metageneration_not_match: list of long - :param if_metageneration_not_match: (Optional) Make the operation conditional on whether the - blob's current metageneration does not match the given value. - The list must match ``blobs`` item-to-item. + :param if_metageneration_not_match: + (Optional) See :ref:`using-if-metageneration-not-match` + The list must match ``blobs`` item-to-item. + + :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: @@ -1673,7 +1659,6 @@ def copy_blob( client=None, preserve_acl=True, source_generation=None, - timeout=_DEFAULT_TIMEOUT, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, @@ -1682,6 +1667,7 @@ def copy_blob( if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, + timeout=_DEFAULT_TIMEOUT, retry=DEFAULT_RETRY_IF_GENERATION_SPECIFIED, ): """Copy the given blob to the given bucket, optionally with a new name. @@ -1712,67 +1698,54 @@ def copy_blob( :param source_generation: (Optional) The generation of the blob to be copied. - :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) Makes the operation - conditional on whether the destination - object's current generation matches the - given value. Setting to 0 makes the - operation succeed only if there are no - live versions of the object. + :param if_generation_match: + (Optional) See :ref:`using-if-generation-match` + Note that the generation to be matched is that of the + ``destination`` blob. :type if_generation_not_match: long - :param if_generation_not_match: (Optional) Makes the operation - conditional on whether the - destination object's current - generation does not match the given - value. If no live object exists, - the precondition fails. Setting to - 0 makes the operation succeed only - if there is a live version - of the object. + :param if_generation_not_match: + (Optional) See :ref:`using-if-generation-not-match` + Note that the generation to be matched is that of the + ``destination`` blob. :type if_metageneration_match: long - :param if_metageneration_match: (Optional) Makes the operation - conditional on whether the - destination object's current - metageneration matches the given - value. + :param if_metageneration_match: + (Optional) See :ref:`using-if-metageneration-match` + Note that the metageneration to be matched is that of the + ``destination`` blob. :type if_metageneration_not_match: long - :param if_metageneration_not_match: (Optional) Makes the operation - conditional on whether the - destination object's current - metageneration does not match - the given value. + :param if_metageneration_not_match: + (Optional) See :ref:`using-if-metageneration-not-match` + Note that the metageneration to be matched is that of the + ``destination`` blob. :type if_source_generation_match: long - :param if_source_generation_match: (Optional) Makes the operation - conditional on whether the source - object's generation matches the - given value. + :param if_source_generation_match: + (Optional) Makes the operation conditional on whether the source + object's generation matches the given value. :type if_source_generation_not_match: long - :param if_source_generation_not_match: (Optional) Makes the operation - conditional on whether the source - object's generation does not match - the given value. + :param if_source_generation_not_match: + (Optional) Makes the operation conditional on whether the source + object's generation does not match the given value. :type if_source_metageneration_match: long - :param if_source_metageneration_match: (Optional) Makes the operation - conditional on whether the source - object's current metageneration - matches the given value. + :param if_source_metageneration_match: + (Optional) Makes the operation conditional on whether the source + object's current metageneration matches the given value. :type if_source_metageneration_not_match: long - :param if_source_metageneration_not_match: (Optional) Makes the operation - conditional on whether the source - object's current metageneration - does not match the given value. + :param if_source_metageneration_not_match: + (Optional) Makes the operation conditional on whether the source + object's current metageneration does not match the given value. + + :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: @@ -1880,65 +1853,52 @@ def rename_blob( to the ``client`` stored on the current bucket. :type if_generation_match: long - :param if_generation_match: (Optional) Makes the operation - conditional on whether the destination - object's current generation matches the - given value. Setting to 0 makes the - operation succeed only if there are no - live versions of the object. + :param if_generation_match: + (Optional) See :ref:`using-if-generation-match` + Note that the generation to be matched is that of the + ``destination`` blob. :type if_generation_not_match: long - :param if_generation_not_match: (Optional) Makes the operation - conditional on whether the - destination object's current - generation does not match the given - value. If no live object exists, - the precondition fails. Setting to - 0 makes the operation succeed only - if there is a live version - of the object. + :param if_generation_not_match: + (Optional) See :ref:`using-if-generation-not-match` + Note that the generation to be matched is that of the + ``destination`` blob. :type if_metageneration_match: long - :param if_metageneration_match: (Optional) Makes the operation - conditional on whether the - destination object's current - metageneration matches the given - value. + :param if_metageneration_match: + (Optional) See :ref:`using-if-metageneration-match` + Note that the metageneration to be matched is that of the + ``destination`` blob. :type if_metageneration_not_match: long - :param if_metageneration_not_match: (Optional) Makes the operation - conditional on whether the - destination object's current - metageneration does not match - the given value. + :param if_metageneration_not_match: + (Optional) See :ref:`using-if-metageneration-not-match` + Note that the metageneration to be matched is that of the + ``destination`` blob. :type if_source_generation_match: long - :param if_source_generation_match: (Optional) Makes the operation - conditional on whether the source - object's generation matches the - given value. Also used in the - delete request. + :param if_source_generation_match: + (Optional) Makes the operation conditional on whether the source + object's generation matches the given value. Also used in the + (implied) delete request. :type if_source_generation_not_match: long - :param if_source_generation_not_match: (Optional) Makes the operation - conditional on whether the source - object's generation does not match - the given value. Also used in the - delete request. + :param if_source_generation_not_match: + (Optional) Makes the operation conditional on whether the source + object's generation does not match the given value. Also used in + the (implied) delete request. :type if_source_metageneration_match: long - :param if_source_metageneration_match: (Optional) Makes the operation - conditional on whether the source - object's current metageneration - matches the given value.Also used in the - delete request. + :param if_source_metageneration_match: + (Optional) Makes the operation conditional on whether the source + object's current metageneration matches the given value. Also used + in the (implied) delete request. :type if_source_metageneration_not_match: long - :param if_source_metageneration_not_match: (Optional) Makes the operation - conditional on whether the source - object's current metageneration - does not match the given value. - Also used in the delete request. + :param if_source_metageneration_not_match: + (Optional) Makes the operation conditional on whether the source + object's current metageneration does not match the given value. + Also used in the (implied) delete request. :type timeout: float or tuple :param timeout: diff --git a/google/cloud/storage/client.py b/google/cloud/storage/client.py index df42f0c11..d6f688d92 100644 --- a/google/cloud/storage/client.py +++ b/google/cloud/storage/client.py @@ -983,37 +983,35 @@ def download_blob_to_file( str, \ ]): The blob resource to pass or URI to download. + file_obj (file): A file handle to which to write the blob's data. + start (int): (Optional) The first byte in a range to be downloaded. + end (int): (Optional) The last byte in a range to be downloaded. + raw_download (bool): (Optional) If true, download the object without any expansion. - if_generation_match (long): - (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. - if_generation_not_match (long): - (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. - if_metageneration_match (long): - (Optional) Make the operation conditional on whether the - blob's current metageneration matches the given value. - if_metageneration_not_match (long): - (Optional) Make the operation conditional on whether the - blob's current metageneration does not match the given value. + + if_generation_match: long + (Optional) See :ref:`using-if-generation-match` + + if_generation_not_match: long + (Optional) See :ref:`using-if-generation-not-match` + + if_metageneration_match: long + (Optional) See :ref:`using-if-metageneration-match` + + if_metageneration_not_match: long + (Optional) See :ref:`using-if-metageneration-not-match` + timeout ([Union[float, Tuple[float, float]]]): - (Optional) The number of seconds the transport should wait for the - server response. Depending on the retry strategy, a request may be - repeated several times using the same timeout each time. - Can also be passed as a tuple (connect_timeout, read_timeout). - See :meth:`requests.Session.request` documentation for details. + (Optional) The amount of time, in seconds, to wait + for the server response. See: :ref:`configuring_timeouts` + checksum (str): (Optional) The type of checksum to compute to verify the integrity of the object. The response headers must contain a checksum of the diff --git a/google/cloud/storage/fileio.py b/google/cloud/storage/fileio.py index e74b9ed4a..6ac8e057f 100644 --- a/google/cloud/storage/fileio.py +++ b/google/cloud/storage/fileio.py @@ -67,7 +67,8 @@ class BlobReader(io.BufferedIOBase): The default is the chunk_size of the blob, or 40MiB. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable + :param retry: + (Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. @@ -88,10 +89,15 @@ class BlobReader(io.BufferedIOBase): configuration changes for Retry objects such as delays and deadlines are respected. - :param download_kwargs: Keyword arguments to pass to the underlying API - calls. The following arguments are supported: "if_generation_match", - "if_generation_not_match", "if_metageneration_match", - "if_metageneration_not_match", "timeout". + :param download_kwargs: + Keyword arguments to pass to the underlying API calls. + The following arguments are supported: + + - ``if_generation_match`` + - ``if_generation_not_match`` + - ``if_metageneration_match`` + - ``if_metageneration_not_match`` + - ``timeout`` """ def __init__(self, blob, chunk_size=None, retry=DEFAULT_RETRY, **download_kwargs): @@ -230,7 +236,8 @@ class BlobWriter(io.BufferedIOBase): expectations. :type retry: google.api_core.retry.Retry or google.cloud.storage.retry.ConditionalRetryPolicy - :param retry: (Optional) How to retry the RPC. A None value will disable + :param retry: + (Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. @@ -251,11 +258,19 @@ class BlobWriter(io.BufferedIOBase): configuration changes for Retry objects such as delays and deadlines are respected. - :param upload_kwargs: Keyword arguments to pass to the underlying API - calls. The following arguments are supported: "if_generation_match", - "if_generation_not_match", "if_metageneration_match", - "if_metageneration_not_match", "timeout", "content_type", - "num_retries", "predefined_acl", "checksum". + :param upload_kwargs: + Keyword arguments to pass to the underlying API + calls. The following arguments are supported: + + - ``if_generation_match`` + - ``if_generation_not_match`` + - ``if_metageneration_match`` + - ``if_metageneration_not_match`` + - ``timeout`` + - ``content_type`` + - ``num_retries`` + - ``predefined_acl`` + - ``checksum`` """ def __init__( diff --git a/noxfile.py b/noxfile.py index 0b85dc8b0..c34e8b981 100644 --- a/noxfile.py +++ b/noxfile.py @@ -179,6 +179,7 @@ def docfx(session): """Build the docfx yaml files for this library.""" session.install("-e", ".") + session.install("grpcio") session.install("sphinx", "alabaster", "recommonmark", "gcp-sphinx-docfx-yaml") shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True) diff --git a/tests/unit/test_blob.py b/tests/unit/test_blob.py index 158109705..a21385821 100644 --- a/tests/unit/test_blob.py +++ b/tests/unit/test_blob.py @@ -3996,7 +3996,9 @@ def test_compose_w_generation_match(self): ) @mock.patch("warnings.warn") - def test_compose_w_generation_match_w_warning(self, mock_warn): + def test_compose_w_if_generation_match_list_w_warning(self, mock_warn): + from google.cloud.storage.blob import _COMPOSE_IF_GENERATION_LIST_DEPRECATED + source_1_name = "source-1" source_2_name = "source-2" destination_name = "destination" @@ -4045,13 +4047,10 @@ def test_compose_w_generation_match_w_warning(self, mock_warn): ) mock_warn.assert_called_with( - "if_generation_match: type list is deprecated and supported for backwards-compatability reasons only." - "Use if_source_generation_match instead to match source objects generations.", - DeprecationWarning, - stacklevel=2, + _COMPOSE_IF_GENERATION_LIST_DEPRECATED, DeprecationWarning, stacklevel=2, ) - def test_compose_invalid_generation_match(self): + def test_compose_w_if_generation_match_and_if_s_generation_match(self): source_1_name = "source-1" source_2_name = "source-2" destination_name = "destination" @@ -4073,7 +4072,9 @@ def test_compose_invalid_generation_match(self): client._post_resource.assert_not_called() @mock.patch("warnings.warn") - def test_compose_w_metageneration_match_w_warning(self, mock_warn): + def test_compose_w_if_metageneration_match_list_w_warning(self, mock_warn): + from google.cloud.storage.blob import _COMPOSE_IF_METAGENERATION_LIST_DEPRECATED + source_1_name = "source-1" source_2_name = "source-2" destination_name = "destination" @@ -4108,9 +4109,7 @@ def test_compose_w_metageneration_match_w_warning(self, mock_warn): ) mock_warn.assert_called_with( - "if_metageneration_match: type list is deprecated and supported for backwards-compatability reasons only." - "Note that the metageneration to be matched is that of the destination blob." - "Please pass in a single value (type long).", + _COMPOSE_IF_METAGENERATION_LIST_DEPRECATED, DeprecationWarning, stacklevel=2, )