[Storage] Decompression for Binary Response in Download APIs (#43587)

Author: weirongw23-msft

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

@@ -11,6 +11,7 @@ APIs, which specifies the full path to start listing paths from.
 - Added support for the keyword `user_delegation_oid` to `generate_blob_sas` and `generate_container_sas`, which
 specifies the Entra ID of the user that is authorized to use the generated SAS URL.
 - Added support for `UseDevelopmentStorage=true;` as a valid connection string for Azurite.
+- Added the ability to skip auto decompression on `BlobClient.download_blob` via the `decompress` keyword.
 
 ## 12.27.1 (2025-10-29)
 

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

@@ -732,6 +732,8 @@ def download_blob(
             function(current: int, total: int) where current is the number of bytes transferred
             so far, and total is the total size of the download.
         :paramtype progress_hook: Callable[[int, int], None]
+        :keyword bool decompress: If True, any compressed content, identified by the Content-Encoding header, will be
+            decompressed automatically before being returned. Default value is True.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.

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

@@ -210,6 +210,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):
         max_concurrency: int = 1,
         encoding: str,
         progress_hook: Optional[Callable[[int, int], None]] = None,
+        decompress: Optional[bool] = None,
         timeout: Optional[int] = None,
         **kwargs: Any
     ) -> StorageStreamDownloader[str]: ...
@@ -231,6 +232,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):
         max_concurrency: int = 1,
         encoding: None = None,
         progress_hook: Optional[Callable[[int, int], None]] = None,
+        decompress: Optional[bool] = None,
         timeout: Optional[int] = None,
         **kwargs: Any
     ) -> StorageStreamDownloader[bytes]: ...
@@ -252,6 +254,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):
         max_concurrency: int = 1,
         encoding: Optional[str] = None,
         progress_hook: Optional[Callable[[int, int], None]] = None,
+        decompress: Optional[bool] = None,
         timeout: Optional[int] = None,
         **kwargs: Any
     ) -> Union[StorageStreamDownloader[str], StorageStreamDownloader[bytes]]: ...

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

@@ -422,6 +422,10 @@ def __len__(self):
     def _get_encryption_data_request(self) -> None:
         # Save current request cls
         download_cls = self._request_options.pop('cls', None)
+
+        # Temporarily removing this for the get properties request
+        decompress = self._request_options.pop('decompress', None)
+
         # Adjust cls for get_properties
         self._request_options['cls'] = deserialize_blob_properties
 
@@ -434,6 +438,10 @@ def _get_encryption_data_request(self) -> None:
         # Restore cls for download
         self._request_options['cls'] = download_cls
 
+        # Decompression does not work with client-side encryption
+        if decompress is not None:
+            self._request_options['decompress'] = decompress
+
     @property
     def _download_complete(self):
         if is_encryption_v2(self._encryption_data):

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

@@ -745,6 +745,8 @@ async def download_blob(
             function(current: int, total: int) where current is the number of bytes transferred
             so far, and total is the total size of the download.
         :paramtype progress_hook: Callable[[int, int], Awaitable[None]]
+        :keyword bool decompress: If True, any compressed content, identified by the Content-Encoding header, will be
+            decompressed automatically before being returned. Default value is True.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.

sdk/storage/azure-storage-blob/azure/storage/blob/aio/_blob_client_async.pyi

@@ -212,6 +212,7 @@ class BlobClient(  # type: ignore[misc]
         max_concurrency: int = 1,
         encoding: str,
         progress_hook: Optional[Callable[[int, int], Awaitable[None]]] = None,
+        decompress: Optional[bool] = None,
         timeout: Optional[int] = None,
         **kwargs: Any
     ) -> StorageStreamDownloader[str]: ...
@@ -233,6 +234,7 @@ class BlobClient(  # type: ignore[misc]
         max_concurrency: int = 1,
         encoding: None = None,
         progress_hook: Optional[Callable[[int, int], Awaitable[None]]] = None,
+        decompress: Optional[bool] = None,
         timeout: Optional[int] = None,
         **kwargs: Any
     ) -> StorageStreamDownloader[bytes]: ...
@@ -254,6 +256,7 @@ class BlobClient(  # type: ignore[misc]
         max_concurrency: int = 1,
         encoding: Optional[str] = None,
         progress_hook: Optional[Callable[[int, int], Awaitable[None]]] = None,
+        decompress: Optional[bool] = None,
         timeout: Optional[int] = None,
         **kwargs: Any
     ) -> Union[StorageStreamDownloader[str], StorageStreamDownloader[bytes]]: ...

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

@@ -292,6 +292,10 @@ def __len__(self):
     async def _get_encryption_data_request(self) -> None:
         # Save current request cls
         download_cls = self._request_options.pop('cls', None)
+
+        # Temporarily removing this for the get properties request
+        decompress = self._request_options.pop('decompress', None)
+
         # Adjust cls for get_properties
         self._request_options['cls'] = deserialize_blob_properties
 
@@ -304,6 +308,10 @@ async def _get_encryption_data_request(self) -> None:
         # Restore cls for download
         self._request_options['cls'] = download_cls
 
+        # Decompression does not work with client-side encryption
+        if decompress is not None:
+            self._request_options['decompress'] = decompress
+
     async def _setup(self) -> None:
         if self._encryption_options.get("key") is not None or self._encryption_options.get("resolver") is not None:
             await self._get_encryption_data_request()

sdk/storage/azure-storage-blob/tests/test_blob_encryption_v2.py

@@ -14,7 +14,7 @@
 import pytest
 from azure.core import MatchConditions
 from azure.core.exceptions import HttpResponseError
-from azure.storage.blob import BlobServiceClient, BlobType
+from azure.storage.blob import BlobServiceClient, BlobType, ContentSettings
 from azure.storage.blob._encryption import (
     _dict_to_encryption_data,
     _validate_and_unwrap_cek,
@@ -196,6 +196,26 @@ def test_encryption_kek(self, **kwargs):
         # Assert
         assert content == data
 
+    @pytest.mark.live_test_only
+    @BlobPreparer()
+    def test_decompression_with_encryption(self, **kwargs):
+        storage_account_name = kwargs.pop("storage_account_name")
+        storage_account_key = kwargs.pop("storage_account_key")
+
+        self._setup(storage_account_name, storage_account_key)
+        kek = KeyWrapper('key1')
+        self.enable_encryption_v2(kek)
+
+        blob = self.bsc.get_blob_client(self.container_name, self._get_blob_reference())
+        compressed_data = b'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xcaH\xcd\xc9\xc9WH+\xca\xcfUH\xaf\xca,\x00\x00\x00\x00\xff\xff\x03\x00d\xaa\x8e\xb5\x0f\x00\x00\x00'
+        content_settings = ContentSettings(content_encoding='gzip')
+
+        # Act / Assert
+        blob.upload_blob(data=compressed_data, overwrite=True, content_settings=content_settings)
+
+        result = blob.download_blob(decompress=False).readall()
+        assert result == compressed_data
+
     @pytest.mark.live_test_only
     @BlobPreparer()
     def test_encryption_kek_rsa(self, **kwargs):

sdk/storage/azure-storage-blob/tests/test_blob_encryption_v2_async.py

@@ -14,7 +14,7 @@
 import pytest
 from azure.core import MatchConditions
 from azure.core.exceptions import HttpResponseError
-from azure.storage.blob import BlobType
+from azure.storage.blob import BlobType, ContentSettings
 from azure.storage.blob.aio import BlobServiceClient
 from azure.storage.blob._encryption import (
     _dict_to_encryption_data,
@@ -199,6 +199,26 @@ async def test_encryption_kek(self, **kwargs):
         # Assert
         assert content == data
 
+    @pytest.mark.live_test_only
+    @BlobPreparer()
+    async def test_decompression_with_encryption(self, **kwargs):
+        storage_account_name = kwargs.pop("storage_account_name")
+        storage_account_key = kwargs.pop("storage_account_key")
+
+        await self._setup(storage_account_name, storage_account_key)
+        kek = KeyWrapper('key1')
+        self.enable_encryption_v2(kek)
+
+        blob = self.bsc.get_blob_client(self.container_name, self._get_blob_reference())
+        compressed_data = b'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xcaH\xcd\xc9\xc9WH+\xca\xcfUH\xaf\xca,\x00\x00\x00\x00\xff\xff\x03\x00d\xaa\x8e\xb5\x0f\x00\x00\x00'
+        content_settings = ContentSettings(content_encoding='gzip')
+
+        # Act / Assert
+        await blob.upload_blob(data=compressed_data, overwrite=True, content_settings=content_settings)
+
+        result = await (await blob.download_blob(decompress=False)).readall()
+        assert result == compressed_data
+
     @pytest.mark.live_test_only
     @BlobPreparer()
     async def test_encryption_kek_rsa(self, **kwargs):

sdk/storage/azure-storage-blob/tests/test_common_blob.py

@@ -3658,4 +3658,53 @@ def test_blob_user_delegation_oid(self, **kwargs):
 
         return variables
 
+    @pytest.mark.live_test_only
+    @BlobPreparer()
+    def test_download_blob_decompress(self, **kwargs):
+        storage_account_name = kwargs.pop("storage_account_name")
+        storage_account_key = kwargs.pop("storage_account_key")
+
+        # Arrange
+        self._setup(storage_account_name, storage_account_key)
+        blob_name = self._get_blob_reference()
+        blob = self.bsc.get_blob_client(self.container_name, blob_name)
+        compressed_data = b'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xcaH\xcd\xc9\xc9WH+\xca\xcfUH\xaf\xca,\x00\x00\x00\x00\xff\xff\x03\x00d\xaa\x8e\xb5\x0f\x00\x00\x00'
+        decompressed_data = b"hello from gzip"
+        content_settings = ContentSettings(content_encoding='gzip')
+
+        # Act / Assert
+        blob.upload_blob(data=compressed_data, overwrite=True, content_settings=content_settings)
+
+        result = blob.download_blob(decompress=True).readall()
+        assert result == decompressed_data
+
+        result = blob.download_blob(decompress=False).readall()
+        assert result == compressed_data
+
+    @pytest.mark.live_test_only
+    @BlobPreparer()
+    def test_download_blob_no_decompress_chunks(self, **kwargs):
+        storage_account_name = kwargs.pop("storage_account_name")
+        storage_account_key = kwargs.pop("storage_account_key")
+
+        # Arrange
+        self._setup(storage_account_name, storage_account_key)
+        blob_name = self._get_blob_reference()
+        blob = BlobClient(
+            account_url=self.account_url(storage_account_name, "blob"),
+            container_name=self.container_name,
+            blob_name = blob_name,
+            credential=storage_account_key,
+            max_chunk_get_size=4,
+            max_single_get_size=4,
+        )
+        compressed_data = b'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xcaH\xcd\xc9\xc9WH+\xca\xcfUH\xaf\xca,\x00\x00\x00\x00\xff\xff\x03\x00d\xaa\x8e\xb5\x0f\x00\x00\x00'
+        content_settings = ContentSettings(content_encoding='gzip')
+
+        # Act / Assert
+        blob.upload_blob(data=compressed_data, overwrite=True, content_settings=content_settings)
+
+        result = blob.download_blob(decompress=False).readall()
+        assert result == compressed_data
+
     # ------------------------------------------------------------------------------