[Blob][STG78]Object Imutability Policy (Version Level Worm) (#19098)

* [Blob][STG78]Object Imutability Policy (Version Level Worm)

Author: xiafu-msft

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

@@ -24,7 +24,8 @@
     UserDelegationKey
 )
 from ._generated.models import (
-    RehydratePriority
+    RehydratePriority,
+    BlobImmutabilityPolicyMode
 )
 from ._models import (
     BlobType,
@@ -58,7 +59,8 @@
     ArrowDialect,
     ArrowType,
     ObjectReplicationPolicy,
-    ObjectReplicationRule
+    ObjectReplicationRule,
+    ImmutabilityPolicy
 )
 from ._list_blobs_helper import BlobPrefix
 
@@ -195,6 +197,8 @@ def download_blob_from_url(
     'StandardBlobTier',
     'PremiumPageBlobTier',
     'SequenceNumberAction',
+    'BlobImmutabilityPolicyMode',
+    'ImmutabilityPolicy',
     'PublicAccess',
     'BlobAnalyticsLogging',
     'Metrics',

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

@@ -408,6 +408,7 @@ def _upload_blob_options(  # pylint:disable=too-many-statements
         kwargs['blob_settings'] = self._config
         kwargs['max_concurrency'] = max_concurrency
         kwargs['encryption_options'] = encryption_options
+
         if blob_type == BlobType.BlockBlob:
             kwargs['client'] = self._client.block_blob
             kwargs['data'] = data
@@ -649,6 +650,20 @@ def upload_blob(  # pylint: disable=too-many-locals
         :keyword ~azure.storage.blob.StandardBlobTier standard_blob_tier:
             A standard blob tier value to set the blob to. For this version of the library,
             this is only applicable to block blobs on standard storage accounts.
+        :keyword ~azure.storage.blob.ImmutabilityPolicy immutability_policy:
+            Specifies the immutability policy of a blob, blob snapshot or blob version.
+            Currently this parameter of upload_blob() API is for BlockBlob only.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
+        :keyword bool legal_hold:
+            Specified if a legal hold should be set on the blob.
+            Currently this parameter of upload_blob() API is for BlockBlob only.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
         :keyword int maxsize_condition:
             Optional conditional header. The max length in bytes permitted for
             the append blob. If the Append Block operation would cause the blob
@@ -1389,6 +1404,64 @@ def set_blob_metadata(self, metadata=None, **kwargs):
         except HttpResponseError as error:
             process_storage_error(error)
 
+    @distributed_trace
+    def set_immutability_policy(self, immutability_policy, **kwargs):
+        # type: (**Any) -> Dict[str, str]
+        """The Set Immutability Policy operation sets the immutability policy on the blob.
+
+        .. versionadded:: 12.10.0
+            This operation was introduced in API version '2020-10-02'.
+
+        :param ~azure.storage.blob.ImmutabilityPolicy immutability_policy:
+            Specifies the immutability policy of a blob, blob snapshot or blob version.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
+        :keyword int timeout:
+            The timeout parameter is expressed in seconds.
+        :returns: Key value pairs of blob tags.
+        :rtype: Dict[str, str]
+        """
+
+        kwargs['immutability_policy_expiry'] = immutability_policy.expiry_time
+        kwargs['immutability_policy_mode'] = immutability_policy.policy_mode
+        return self._client.blob.set_immutability_policy(cls=return_response_headers, **kwargs)
+
+    @distributed_trace
+    def delete_immutability_policy(self, **kwargs):
+        # type: (**Any) -> None
+        """The Delete Immutability Policy operation deletes the immutability policy on the blob.
+
+        .. versionadded:: 12.10.0
+            This operation was introduced in API version '2020-10-02'.
+
+        :keyword int timeout:
+            The timeout parameter is expressed in seconds.
+        :returns: Key value pairs of blob tags.
+        :rtype: Dict[str, str]
+        """
+
+        self._client.blob.delete_immutability_policy(**kwargs)
+
+    @distributed_trace
+    def set_legal_hold(self, legal_hold, **kwargs):
+        # type: (**Any) -> Dict[str, Union[str, datetime, bool]]
+        """The Set Legal Hold operation sets a legal hold on the blob.
+
+        .. versionadded:: 12.10.0
+            This operation was introduced in API version '2020-10-02'.
+
+        :param bool legal_hold:
+            Specified if a legal hold should be set on the blob.
+        :keyword int timeout:
+            The timeout parameter is expressed in seconds.
+        :returns: Key value pairs of blob tags.
+        :rtype: Dict[str, str]
+        """
+
+        return self._client.blob.set_legal_hold(legal_hold, cls=return_response_headers, **kwargs)
+
     def _create_page_blob_options(  # type: ignore
             self, size,  # type: int
             content_settings=None,  # type: Optional[ContentSettings]
@@ -1424,6 +1497,11 @@ def _create_page_blob_options(  # type: ignore
             cpk_info = CpkInfo(encryption_key=cpk.key_value, encryption_key_sha256=cpk.key_hash,
                                encryption_algorithm=cpk.algorithm)
 
+        immutability_policy = kwargs.pop('immutability_policy', None)
+        if immutability_policy:
+            kwargs['immutability_policy_expiry'] = immutability_policy.expiry_time
+            kwargs['immutability_policy_mode'] = immutability_policy.policy_mode
+
         if premium_page_blob_tier:
             try:
                 headers['x-ms-access-tier'] = premium_page_blob_tier.value  # type: ignore
@@ -1490,6 +1568,18 @@ def create_page_blob(  # type: ignore
             Required if the blob has an active lease. Value can be a BlobLeaseClient object
             or the lease ID as a string.
         :paramtype lease: ~azure.storage.blob.BlobLeaseClient or str
+        :keyword ~azure.storage.blob.ImmutabilityPolicy immutability_policy:
+            Specifies the immutability policy of a blob, blob snapshot or blob version.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
+        :keyword bool legal_hold:
+            Specified if a legal hold should be set on the blob.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
         :keyword ~datetime.datetime if_modified_since:
             A DateTime value. Azure expects the date value passed in to be UTC.
             If timezone is included, any non-UTC datetimes will be converted to UTC.
@@ -1563,6 +1653,12 @@ def _create_append_blob_options(self, content_settings=None, metadata=None, **kw
                 raise ValueError("Customer provided encryption key must be used over HTTPS.")
             cpk_info = CpkInfo(encryption_key=cpk.key_value, encryption_key_sha256=cpk.key_hash,
                                encryption_algorithm=cpk.algorithm)
+
+        immutability_policy = kwargs.pop('immutability_policy', None)
+        if immutability_policy:
+            kwargs['immutability_policy_expiry'] = immutability_policy.expiry_time
+            kwargs['immutability_policy_mode'] = immutability_policy.policy_mode
+
         blob_tags_string = serialize_blob_tags_header(kwargs.pop('tags', None))
 
         options = {
@@ -1604,6 +1700,18 @@ def create_append_blob(self, content_settings=None, metadata=None, **kwargs):
             Required if the blob has an active lease. Value can be a BlobLeaseClient object
             or the lease ID as a string.
         :paramtype lease: ~azure.storage.blob.BlobLeaseClient or str
+        :keyword ~azure.storage.blob.ImmutabilityPolicy immutability_policy:
+            Specifies the immutability policy of a blob, blob snapshot or blob version.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
+        :keyword bool legal_hold:
+            Specified if a legal hold should be set on the blob.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
         :keyword ~datetime.datetime if_modified_since:
             A DateTime value. Azure expects the date value passed in to be UTC.
             If timezone is included, any non-UTC datetimes will be converted to UTC.
@@ -1776,6 +1884,11 @@ def _start_copy_from_url_options(self, source_url, metadata=None, incremental_co
         dest_mod_conditions = get_modify_conditions(kwargs)
         blob_tags_string = serialize_blob_tags_header(kwargs.pop('tags', None))
 
+        immutability_policy = kwargs.pop('immutability_policy', None)
+        if immutability_policy:
+            kwargs['immutability_policy_expiry'] = immutability_policy.expiry_time
+            kwargs['immutability_policy_mode'] = immutability_policy.policy_mode
+
         options = {
             'copy_source': source_url,
             'seal_blob': kwargs.pop('seal_destination_blob', None),
@@ -1863,6 +1976,18 @@ def start_copy_from_url(self, source_url, metadata=None, incremental_copy=False,
             .. versionadded:: 12.4.0
 
         :paramtype tags: dict(str, str)
+        :keyword ~azure.storage.blob.ImmutabilityPolicy immutability_policy:
+            Specifies the immutability policy of a blob, blob snapshot or blob version.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
+        :keyword bool legal_hold:
+            Specified if a legal hold should be set on the blob.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
         :keyword ~datetime.datetime source_if_modified_since:
             A DateTime value. Azure expects the date value passed in to be UTC.
             If timezone is included, any non-UTC datetimes will be converted to UTC.
@@ -1933,7 +2058,7 @@ def start_copy_from_url(self, source_url, metadata=None, incremental_copy=False,
             the prefix of the source_authorization string. This option is only available when `incremental_copy` is
             set to False and `requires_sync` is set to True.
         :returns: A dictionary of copy properties (etag, last_modified, copy_id, copy_status).
-        :rtype: dict[str, str or ~datetime.datetime]
+        :rtype: dict[str, Union[str, ~datetime.datetime]]
 
         .. admonition:: Example:
 
@@ -2415,6 +2540,11 @@ def _commit_block_list_options( # type: ignore
             cpk_info = CpkInfo(encryption_key=cpk.key_value, encryption_key_sha256=cpk.key_hash,
                                encryption_algorithm=cpk.algorithm)
 
+        immutability_policy = kwargs.pop('immutability_policy', None)
+        if immutability_policy:
+            kwargs['immutability_policy_expiry'] = immutability_policy.expiry_time
+            kwargs['immutability_policy_mode'] = immutability_policy.policy_mode
+
         tier = kwargs.pop('standard_blob_tier', None)
         blob_tags_string = serialize_blob_tags_header(kwargs.pop('tags', None))
 
@@ -2468,6 +2598,18 @@ def commit_block_list( # type: ignore
             Required if the blob has an active lease. Value can be a BlobLeaseClient object
             or the lease ID as a string.
         :paramtype lease: ~azure.storage.blob.BlobLeaseClient or str
+        :keyword ~azure.storage.blob.ImmutabilityPolicy immutability_policy:
+            Specifies the immutability policy of a blob, blob snapshot or blob version.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
+        :keyword bool legal_hold:
+            Specified if a legal hold should be set on the blob.
+
+            .. versionadded:: 12.10.0
+                This was introduced in API version '2020-10-02'.
+
         :keyword bool validate_content:
             If true, calculates an MD5 hash of the page content. The storage
             service checks the hash of the content that has arrived

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

@@ -744,7 +744,7 @@ def list_blobs(self, name_starts_with=None, include=None, **kwargs):
         :param list[str] or str include:
             Specifies one or more additional datasets to include in the response.
             Options include: 'snapshots', 'metadata', 'uncommittedblobs', 'copy', 'deleted', 'deletedwithversions',
-            'tags', 'versions'.
+            'tags', 'versions', 'immutabilitypolicy', 'legalhold'.
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :returns: An iterable (auto-paging) response of BlobProperties.

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

@@ -9,7 +9,7 @@
     TYPE_CHECKING
 )
 
-from ._models import BlobType, CopyProperties, ContentSettings, LeaseProperties, BlobProperties
+from ._models import BlobType, CopyProperties, ContentSettings, LeaseProperties, BlobProperties, ImmutabilityPolicy
 from ._shared.models import get_enum_value
 
 from ._shared.response_handlers import deserialize_metadata
@@ -153,6 +153,8 @@ def get_blob_properties_from_generated_code(generated):
     blob.tags = parse_tags(generated.blob_tags)  # pylint: disable=protected-access
     blob.object_replication_source_properties = deserialize_ors_policies(generated.object_replication_metadata)
     blob.last_accessed_on = generated.properties.last_accessed_on
+    blob.immutability_policy = ImmutabilityPolicy._from_generated(generated)  # pylint: disable=protected-access
+    blob.has_legal_hold = generated.properties.legal_hold
     blob.has_versions_only = generated.has_versions_only
     return blob