[Storage] Conditional etag parameters

sdk/storage/azure-storage-blob/HISTORY.md

@@ -9,9 +9,9 @@
 - Removed types that were accidentally exposed from two modules. Only `BlobServiceClient`, `ContainerClient`, 
 `BlobClient` and `LeaseClient` should be imported from azure.storage.blob.aio
 - `Logging` has been renamed to `BlobAnalyticsLogging`.
+- All operations that take Etag conditional parameters (`if_match` and `if_none_match`) now take explicit `etag` and `match_condition` parameters, where `etag` is the Etag value, and `match_condition` is an instance of `azure.core.MatchConditions`.
 - The `generate_shared_access_signature` methods on each of `BlobServiceClient`, `ContainerClient` and `BlobClient` have been replaced by module level functions `generate_account_sas`, `generate_container_sas` and `generate_blob_sas`.
 
-
 **New features**
 
 - `ResourceTypes`, and `Services` now have method `from_string` which takes parameters as a string.

sdk/storage/azure-storage-blob/azure/storage/blob/_serialize.py

@@ -0,0 +1,57 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+# pylint: disable=no-self-use
+
+from azure.core import MatchConditions
+
+from ._generated.models import ModifiedAccessConditions, SourceModifiedAccessConditions
+
+
+def _get_match_headers(kwargs, match_param, etag_param):
+    # type: (str) -> Tuple(Dict[str, Any], Optional[str], Optional[str])
+    if_match = None
+    if_none_match = None
+    match_condition = kwargs.pop(match_param, None)
+    if match_condition == MatchConditions.IfNotModified:
+        if_match = kwargs.pop(etag_param, None)
+        if not if_match:
+            raise ValueError("'{}' specified without '{}'.".format(match_param, etag_param))
+    elif match_condition == MatchConditions.IfPresent:
+        if_match = '*'
+    elif match_condition == MatchConditions.IfModified:
+        if_none_match = kwargs.pop(etag_param, None)
+        if not if_none_match:
+            raise ValueError("'{}' specified without '{}'.".format(match_param, etag_param))
+    elif match_condition == MatchConditions.IfMissing:
+        if_none_match = '*'
+    elif match_condition is None:
+        if etag_param in kwargs:
+            raise ValueError("'{}' specified without '{}'.".format(etag_param, match_param))
+    else:
+        raise TypeError("Invalid match condition: {}".format(match_condition))
+    return if_match, if_none_match
+
+
+def get_modify_conditions(kwargs):
+    # type: (Dict[str, Any]) -> ModifiedAccessConditions
+    if_match, if_none_match = _get_match_headers(kwargs, 'match_condition', 'etag')
+    return ModifiedAccessConditions(
+        if_modified_since=kwargs.pop('if_modified_since', None),
+        if_unmodified_since=kwargs.pop('if_unmodified_since', None),
+        if_match=if_match or kwargs.pop('if_match', None),
+        if_none_match=if_none_match or kwargs.pop('if_none_match', None)
+    )
+
+
+def get_source_conditions(kwargs):
+    # type: (Dict[str, Any]) -> SourceModifiedAccessConditions
+    if_match, if_none_match = _get_match_headers(kwargs, 'source_match_condition', 'source_etag')
+    return SourceModifiedAccessConditions(
+        source_if_modified_since=kwargs.pop('source_if_modified_since', None),
+        source_if_unmodified_since=kwargs.pop('source_if_unmodified_since', None),
+        source_if_match=if_match or kwargs.pop('source_if_match', None),
+        source_if_none_match=if_none_match or kwargs.pop('source_if_none_match', None)
+    )

sdk/storage/azure-storage-blob/azure/storage/blob/aio/blob_service_client_async.py

@@ -432,15 +432,11 @@ async def delete_container(
             If a date is passed in without timezone info, it is assumed to be UTC.
             Specify this header to perform the operation only if
             the resource has not been modified since the specified date/time.
-        :keyword str if_match:
-            An ETag value, or the wildcard character (*). Specify this header to perform
-            the operation only if the resource's ETag matches the value specified.
-        :keyword str if_none_match:
-            An ETag value, or the wildcard character (*). Specify this header
-            to perform the operation only if the resource's ETag does not match
-            the value specified. Specify the wildcard character (*) to perform
-            the operation only if the resource does not exist, and fail the
-            operation if it does exist.
+        :keyword str etag:
+            An ETag value, or the wildcard character (*). Used to check if the resource has changed,
+            and act according to the condition specified by the `match_condition` parameter.
+        :keyword :class:`MatchConditions` match_condition:
+            The match condition to use upon the etag.
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :rtype: None

sdk/storage/azure-storage-blob/azure/storage/blob/aio/container_client_async.py

@@ -25,10 +25,10 @@
     return_headers_and_deserialized)
 from .._generated.aio import AzureBlobStorage
 from .._generated.models import (
-    ModifiedAccessConditions,
     StorageErrorException,
     SignedIdentifier)
 from .._deserialize import deserialize_container_properties
+from .._serialize import get_modify_conditions
 from ..container_client import ContainerClient as ContainerClientBase
 from ..lease import get_access_conditions
 from ..models import ContainerProperties, BlobProperties, BlobType  # pylint: disable=unused-import
@@ -180,15 +180,11 @@ async def delete_container(
             If a date is passed in without timezone info, it is assumed to be UTC.
             Specify this header to perform the operation only if
             the resource has not been modified since the specified date/time.
-        :keyword str if_match:
-            An ETag value, or the wildcard character (*). Specify this header to perform
-            the operation only if the resource's ETag matches the value specified.
-        :keyword str if_none_match:
-            An ETag value, or the wildcard character (*). Specify this header
-            to perform the operation only if the resource's ETag does not match
-            the value specified. Specify the wildcard character (*) to perform
-            the operation only if the resource does not exist, and fail the
-            operation if it does exist.
+        :keyword str etag:
+            An ETag value, or the wildcard character (*). Used to check if the resource has changed,
+            and act according to the condition specified by the `match_condition` parameter.
+        :keyword :class:`MatchConditions` match_condition:
+            The match condition to use upon the etag.
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :rtype: None
@@ -204,11 +200,7 @@ async def delete_container(
         """
         lease = kwargs.pop('lease', None)
         access_conditions = get_access_conditions(lease)
-        mod_conditions = ModifiedAccessConditions(
-            if_modified_since=kwargs.pop('if_modified_since', None),
-            if_unmodified_since=kwargs.pop('if_unmodified_since', None),
-            if_match=kwargs.pop('if_match', None),
-            if_none_match=kwargs.pop('if_none_match', None))
+        mod_conditions = get_modify_conditions(kwargs)
         timeout = kwargs.pop('timeout', None)
         try:
             await self._client.container.delete(
@@ -250,15 +242,11 @@ async def acquire_lease(
             If a date is passed in without timezone info, it is assumed to be UTC.
             Specify this header to perform the operation only if
             the resource has not been modified since the specified date/time.
-        :keyword str if_match:
-            An ETag value, or the wildcard character (*). Specify this header to perform
-            the operation only if the resource's ETag matches the value specified.
-        :keyword str if_none_match:
-            An ETag value, or the wildcard character (*). Specify this header
-            to perform the operation only if the resource's ETag does not match
-            the value specified. Specify the wildcard character (*) to perform
-            the operation only if the resource does not exist, and fail the
-            operation if it does exist.
+        :keyword str etag:
+            An ETag value, or the wildcard character (*). Used to check if the resource has changed,
+            and act according to the condition specified by the `match_condition` parameter.
+        :keyword :class:`MatchConditions` match_condition:
+            The match condition to use upon the etag.
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :returns: A LeaseClient object, that can be run in a context manager.
@@ -373,7 +361,7 @@ async def set_container_metadata( # type: ignore
         headers.update(add_metadata_headers(metadata))
         lease = kwargs.pop('lease', None)
         access_conditions = get_access_conditions(lease)
-        mod_conditions = ModifiedAccessConditions(if_modified_since=kwargs.pop('if_modified_since', None))
+        mod_conditions = get_modify_conditions(kwargs)
         timeout = kwargs.pop('timeout', None)
         try:
             return await self._client.container.set_metadata( # type: ignore
@@ -485,9 +473,7 @@ async def set_container_access_policy(
             identifiers.append(SignedIdentifier(id=key, access_policy=value)) # type: ignore
         signed_identifiers = identifiers # type: ignore
 
-        mod_conditions = ModifiedAccessConditions(
-            if_modified_since=kwargs.pop('if_modified_since', None),
-            if_unmodified_since=kwargs.pop('if_unmodified_since', None))
+        mod_conditions = get_modify_conditions(kwargs)
         access_conditions = get_access_conditions(lease)
         try:
             return await self._client.container.set_access_policy(
@@ -647,15 +633,11 @@ async def upload_blob(
             If a date is passed in without timezone info, it is assumed to be UTC.
             Specify this header to perform the operation only if
             the resource has not been modified since the specified date/time.
-        :keyword str if_match:
-            An ETag value, or the wildcard character (*). Specify this header to perform
-            the operation only if the resource's ETag matches the value specified.
-        :keyword str if_none_match:
-            An ETag value, or the wildcard character (*). Specify this header
-            to perform the operation only if the resource's ETag does not match
-            the value specified. Specify the wildcard character (*) to perform
-            the operation only if the resource does not exist, and fail the
-            operation if it does exist.
+        :keyword str etag:
+            An ETag value, or the wildcard character (*). Used to check if the resource has changed,
+            and act according to the condition specified by the `match_condition` parameter.
+        :keyword :class:`MatchConditions` match_condition:
+            The match condition to use upon the etag.
         :keyword int timeout:
             The timeout parameter is expressed in seconds. This method may make
             multiple calls to the Azure service and the timeout will apply to
@@ -753,15 +735,11 @@ async def delete_blob(
             If a date is passed in without timezone info, it is assumed to be UTC.
             Specify this header to perform the operation only if
             the resource has not been modified since the specified date/time.
-        :keyword str if_match:
-            An ETag value, or the wildcard character (*). Specify this header to perform
-            the operation only if the resource's ETag matches the value specified.
-        :keyword str if_none_match:
-            An ETag value, or the wildcard character (*). Specify this header
-            to perform the operation only if the resource's ETag does not match
-            the value specified. Specify the wildcard character (*) to perform
-            the operation only if the resource does not exist, and fail the
-            operation if it does exist.
+        :keyword str etag:
+            An ETag value, or the wildcard character (*). Used to check if the resource has changed,
+            and act according to the condition specified by the `match_condition` parameter.
+        :keyword :class:`MatchConditions` match_condition:
+            The match condition to use upon the etag.
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :rtype: None
@@ -821,15 +799,11 @@ async def delete_blobs(  # pylint: disable=arguments-differ
             If a date is passed in without timezone info, it is assumed to be UTC.
             Specify this header to perform the operation only if
             the resource has not been modified since the specified date/time.
-        :keyword str if_match:
-            An ETag value, or the wildcard character (*). Specify this header to perform
-            the operation only if the resource's ETag matches the value specified.
-        :keyword str if_none_match:
-            An ETag value, or the wildcard character (*). Specify this header
-            to perform the operation only if the resource's ETag does not match
-            the value specified. Specify the wildcard character (*) to perform
-            the operation only if the resource does not exist, and fail the
-            operation if it does exist.
+        :keyword str etag:
+            An ETag value, or the wildcard character (*). Used to check if the resource has changed,
+            and act according to the condition specified by the `match_condition` parameter.
+        :keyword :class:`MatchConditions` match_condition:
+            The match condition to use upon the etag.
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :return: An async iterator of responses, one for each blob in order