azure-storage-blob 12.23.1__tar.gz → 12.24.0__tar.gz

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+## 12.24.0 (2024-11-13)
+
+### Features Added
+- Stable release of features from 12.24.0b1
+
+## 12.24.0b1 (2024-10-10)
+
+### Features Added
+- Added support for service version 2025-01-05.
+- Added support for passing metadata to `upload_blob_from_url` via the new `metadata` keyword.
+- Added support for `set_immutability_policy`, `delete_immutability_policy` and `set_legal_hold` for Blob snapshots and versions.
+
 ## 12.23.1 (2024-09-25)
 
 ### Features Added

{azure_storage_blob-12.23.1/azure_storage_blob.egg-info → azure_storage_blob-12.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: azure-storage-blob
-Version: 12.23.1
+Version: 12.24.0
 Summary: Microsoft Azure Blob Storage Client Library for Python
 Home-page: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
 Author: Microsoft Corporation
@@ -116,14 +116,14 @@ The `credential` parameter may be provided in a number of different forms, depen
 
    Use the returned token credential to authenticate the client:
     ```python
-        from azure.identity import DefaultAzureCredential
-        from azure.storage.blob import BlobServiceClient
-        token_credential = DefaultAzureCredential()
-
-        blob_service_client = BlobServiceClient(
-            account_url="https://<my_account_name>.blob.core.windows.net",
-            credential=token_credential
-        )
+    from azure.identity import DefaultAzureCredential
+    from azure.storage.blob import BlobServiceClient
+    token_credential = DefaultAzureCredential()
+
+    blob_service_client = BlobServiceClient(
+        account_url="https://<my_account_name>.blob.core.windows.net",
+        credential=token_credential
+    )
     ```
 
 2. To use a [shared access signature (SAS) token](https://docs.microsoft.com/azure/storage/common/storage-sas-overview),

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/README.md

@@ -87,14 +87,14 @@ The `credential` parameter may be provided in a number of different forms, depen
 
    Use the returned token credential to authenticate the client:
     ```python
-        from azure.identity import DefaultAzureCredential
-        from azure.storage.blob import BlobServiceClient
-        token_credential = DefaultAzureCredential()
-
-        blob_service_client = BlobServiceClient(
-            account_url="https://<my_account_name>.blob.core.windows.net",
-            credential=token_credential
-        )
+    from azure.identity import DefaultAzureCredential
+    from azure.storage.blob import BlobServiceClient
+    token_credential = DefaultAzureCredential()
+
+    blob_service_client = BlobServiceClient(
+        account_url="https://<my_account_name>.blob.core.windows.net",
+        credential=token_credential
+    )
     ```
 
 2. To use a [shared access signature (SAS) token](https://docs.microsoft.com/azure/storage/common/storage-sas-overview),

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/azure/storage/blob/_blob_client.py

@@ -187,7 +187,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         self._query_str, credential = self._format_query_string(sas_token, credential, snapshot=self.snapshot)
         super(BlobClient, self).__init__(parsed_url, service='blob', credential=credential, **kwargs)
         self._client = AzureBlobStorage(self.url, base_url=self.url, pipeline=self._pipeline)
-        self._client._config.version = get_api_version(kwargs)  # type: ignore [assignment] # pylint: disable=protected-access
+        self._client._config.version = get_api_version(kwargs)  # type: ignore [assignment]
         self._configure_encryption(kwargs)
 
     def _format_url(self, hostname: str) -> str:
@@ -320,7 +320,12 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             process_storage_error(error)
 
     @distributed_trace
-    def upload_blob_from_url(self, source_url: str, **kwargs: Any) -> Dict[str, Any]:
+    def upload_blob_from_url(
+        self, source_url: str,
+        *,
+        metadata: Optional[Dict[str, str]] = None,
+        **kwargs: Any
+    ) -> Dict[str, Any]:
         """
         Creates a new Block Blob where the content of the blob is read from a given URL.
         The content of an existing blob is overwritten with the new blob.
@@ -337,6 +342,8 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
 
             https://otheraccount.blob.core.windows.net/mycontainer/myblob?sastoken
+        :keyword dict(str, str) metadata:
+            Name-value pairs associated with the blob as metadata.
         :keyword bool overwrite: Whether the blob to be uploaded should overwrite the current data.
             If True, upload_blob will overwrite the existing data. If set to False, the
             operation will fail with ResourceExistsError.
@@ -422,6 +429,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             raise ValueError("Customer provided encryption key must be used over HTTPS.")
         options = _upload_blob_from_url_options(
             source_url=source_url,
+            metadata=metadata,
             **kwargs)
         try:
             return cast(Dict[str, Any], self._client.block_blob.put_blob_from_url(**options))
@@ -532,8 +540,9 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             value specified in this header, the request will fail with
             MaxBlobSizeConditionNotMet error (HTTP status code 412 - Precondition Failed).
         :keyword int max_concurrency:
-            Maximum number of parallel connections to use when the blob size exceeds
-            64MB.
+            Maximum number of parallel connections to use when transferring the blob in chunks.
+            This option does not affect the underlying connection pool, and may
+            require a separate configuration of the connection pool.
         :keyword ~azure.storage.blob.CustomerProvidedEncryptionKey cpk:
             Encrypts the data on the service-side with the given key.
             Use of customer-provided keys must be done over HTTPS.
@@ -687,7 +696,9 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             As the encryption key itself is provided in the request,
             a secure connection must be established to transfer the key.
         :keyword int max_concurrency:
-            The number of parallel connections with which to download.
+            Maximum number of parallel connections to use when transferring the blob in chunks.
+            This option does not affect the underlying connection pool, and may
+            require a separate configuration of the connection pool.
         :keyword Optional[str] encoding:
             Encoding to decode the downloaded bytes. Default is None, i.e. no decoding.
         :keyword progress_hook:
@@ -1220,6 +1231,9 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             .. versionadded:: 12.10.0
                 This was introduced in API version '2020-10-02'.
 
+        :keyword str version_id:
+            The version id parameter is an opaque DateTime
+            value that, when present, specifies the version of the blob to check if it exists.
         :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.
@@ -1230,9 +1244,11 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         :rtype: Dict[str, str]
         """
 
+        version_id = get_version_id(self.version_id, kwargs)
         kwargs['immutability_policy_expiry'] = immutability_policy.expiry_time
         kwargs['immutability_policy_mode'] = immutability_policy.policy_mode
-        return cast(Dict[str, str], self._client.blob.set_immutability_policy(cls=return_response_headers, **kwargs))
+        return cast(Dict[str, str], self._client.blob.set_immutability_policy(
+            cls=return_response_headers, version_id=version_id, **kwargs))
 
     @distributed_trace
     def delete_immutability_policy(self, **kwargs: Any) -> None:
@@ -1241,6 +1257,9 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         .. versionadded:: 12.10.0
             This operation was introduced in API version '2020-10-02'.
 
+        :keyword str version_id:
+            The version id parameter is an opaque DateTime
+            value that, when present, specifies the version of the blob to check if it exists.
         :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.
@@ -1251,7 +1270,8 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         :rtype: Dict[str, str]
         """
 
-        self._client.blob.delete_immutability_policy(**kwargs)
+        version_id = get_version_id(self.version_id, kwargs)
+        self._client.blob.delete_immutability_policy(version_id=version_id, **kwargs)
 
     @distributed_trace
     def set_legal_hold(self, legal_hold: bool, **kwargs: Any) -> Dict[str, Union[str, datetime, bool]]:
@@ -1262,6 +1282,9 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
 
         :param bool legal_hold:
             Specified if a legal hold should be set on the blob.
+        :keyword str version_id:
+            The version id parameter is an opaque DateTime
+            value that, when present, specifies the version of the blob to check if it exists.
         :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.
@@ -1272,8 +1295,9 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         :rtype: Dict[str, Union[str, datetime, bool]]
         """
 
-        return cast(Dict[str, Union[str, datetime, bool]],
-                    self._client.blob.set_legal_hold(legal_hold, cls=return_response_headers, **kwargs))
+        version_id = get_version_id(self.version_id, kwargs)
+        return cast(Dict[str, Union[str, datetime, bool]], self._client.blob.set_legal_hold(
+            legal_hold, version_id=version_id, cls=return_response_headers, **kwargs))
 
     @distributed_trace
     def create_page_blob(
@@ -3281,7 +3305,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
                 policies=self._pipeline._impl_policies # pylint: disable = protected-access
             )
         else:
-            _pipeline = self._pipeline  # pylint: disable = protected-access
+            _pipeline = self._pipeline
         return ContainerClient(
             f"{self.scheme}://{self.primary_hostname}", container_name=self.container_name,
             credential=self._raw_credential, api_version=self.api_version, _configuration=self._config,

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/azure/storage/blob/_blob_client_helpers.py

@@ -188,7 +188,10 @@ def _upload_blob_options(  # pylint:disable=too-many-statements
         raise ValueError(f"Unsupported BlobType: {blob_type}")
     return kwargs
 
-def _upload_blob_from_url_options(source_url: str, **kwargs: Any ) -> Dict[str, Any]:
+def _upload_blob_from_url_options(source_url: str, **kwargs: Any) -> Dict[str, Any]:
+    metadata = kwargs.pop('metadata', None)
+    headers = kwargs.pop('headers', {})
+    headers.update(add_metadata_headers(metadata))
     source_url = _encode_source_url(source_url=source_url)
     tier = kwargs.pop('standard_blob_tier', None)
     overwrite = kwargs.pop('overwrite', False)
@@ -222,10 +225,11 @@ def _upload_blob_from_url_options(source_url: str, **kwargs: Any ) -> Dict[str,
         'tier': tier.value if tier else None,
         'source_modified_access_conditions': get_source_conditions(kwargs),
         'cpk_info': cpk_info,
-        'cpk_scope_info': get_cpk_scope_info(kwargs)
+        'cpk_scope_info': get_cpk_scope_info(kwargs),
+        'headers': headers,
     }
     options.update(kwargs)
-    if not overwrite and not _any_conditions(**options): # pylint: disable=protected-access
+    if not overwrite and not _any_conditions(**options):
         options['modified_access_conditions'].if_none_match = '*'
     return options
 

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/azure/storage/blob/_blob_service_client.py

@@ -128,7 +128,7 @@ class BlobServiceClient(StorageAccountHostsMixin, StorageEncryptionMixin):
         self._query_str, credential = self._format_query_string(sas_token, credential)
         super(BlobServiceClient, self).__init__(parsed_url, service='blob', credential=credential, **kwargs)
         self._client = AzureBlobStorage(self.url, base_url=self.url, pipeline=self._pipeline)
-        self._client._config.version = get_api_version(kwargs)  # type: ignore [assignment] # pylint: disable=protected-access
+        self._client._config.version = get_api_version(kwargs)  # type: ignore [assignment]
         self._configure_encryption(kwargs)
 
     def _format_url(self, hostname):

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/azure/storage/blob/_container_client.py

@@ -624,7 +624,7 @@ class ContainerClient(StorageAccountHostsMixin, StorageEncryptionMixin):    # py
             process_storage_error(error)
 
     @distributed_trace
-    def _get_blob_service_client(self) -> "BlobServiceClient":  # pylint: disable=client-method-missing-kwargs
+    def _get_blob_service_client(self) -> "BlobServiceClient":
         """Get a client to interact with the container's parent service account.
 
         Defaults to current container's credentials.
@@ -648,7 +648,7 @@ class ContainerClient(StorageAccountHostsMixin, StorageEncryptionMixin):    # py
                 policies=self._pipeline._impl_policies # pylint: disable = protected-access
             )
         else:
-            _pipeline = self._pipeline   # pylint: disable = protected-access
+            _pipeline = self._pipeline
         return BlobServiceClient(
             f"{self.scheme}://{self.primary_hostname}",
             credential=self._raw_credential, api_version=self.api_version, _configuration=self._config,

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/azure/storage/blob/_container_client_helpers.py

@@ -132,7 +132,7 @@ def _generate_delete_blobs_options(
     for blob in blobs:
         if not isinstance(blob, str):
             blob_name = blob.get('name')
-            options = _generic_delete_blob_options(  # pylint: disable=protected-access
+            options = _generic_delete_blob_options(
                 snapshot=blob.get('snapshot'),
                 version_id=blob.get('version_id'),
                 delete_snapshots=delete_snapshots or blob.get('delete_snapshots'),
@@ -147,7 +147,7 @@ def _generate_delete_blobs_options(
             )
         else:
             blob_name = blob
-            options = _generic_delete_blob_options(  # pylint: disable=protected-access
+            options = _generic_delete_blob_options(
                 delete_snapshots=delete_snapshots,
                 if_modified_since=if_modified_since,
                 if_unmodified_since=if_unmodified_since,
@@ -199,11 +199,11 @@ def _generate_set_tiers_subrequest_options(
         query_parameters['versionid'] = client._serialize.query("version_id", version_id, 'str')  # pylint: disable=protected-access
     if timeout is not None:
         query_parameters['timeout'] = client._serialize.query("timeout", timeout, 'int', minimum=0)  # pylint: disable=protected-access
-    query_parameters['comp'] = client._serialize.query("comp", comp, 'str')  # pylint: disable=protected-access, specify-parameter-names-in-call
+    query_parameters['comp'] = client._serialize.query("comp", comp, 'str')  # pylint: disable=protected-access
 
     # Construct headers
     header_parameters = {}
-    header_parameters['x-ms-access-tier'] = client._serialize.header("tier", tier, 'str')  # pylint: disable=protected-access, specify-parameter-names-in-call
+    header_parameters['x-ms-access-tier'] = client._serialize.header("tier", tier, 'str')  # pylint: disable=protected-access
     if rehydrate_priority is not None:
         header_parameters['x-ms-rehydrate-priority'] = client._serialize.header(  # pylint: disable=protected-access
             "rehydrate_priority", rehydrate_priority, 'str')

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/azure/storage/blob/_deserialize.py

@@ -142,7 +142,7 @@ def service_properties_deserialize(generated: "StorageServiceProperties") -> Dic
         'hour_metrics': Metrics._from_generated(generated.hour_metrics),  # pylint: disable=protected-access
         'minute_metrics': Metrics._from_generated(generated.minute_metrics),  # pylint: disable=protected-access
         'cors': cors_list,
-        'target_version': generated.default_service_version,  # pylint: disable=protected-access
+        'target_version': generated.default_service_version,
         'delete_retention_policy': RetentionPolicy._from_generated(generated.delete_retention_policy),  # pylint: disable=protected-access
         'static_website': StaticWebsite._from_generated(generated.static_website),  # pylint: disable=protected-access
     }
@@ -181,7 +181,7 @@ def get_blob_properties_from_generated_code(generated: "BlobItemInternal") -> Bl
     blob.version_id = generated.version_id
     blob.is_current_version = generated.is_current_version
     blob.tag_count = generated.properties.tag_count
-    blob.tags = parse_tags(generated.blob_tags)  # pylint: disable=protected-access
+    blob.tags = parse_tags(generated.blob_tags)
     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

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/azure/storage/blob/_encryption.py

@@ -508,6 +508,8 @@ def _generate_encryption_data_dict(
         # We must pad the version to 8 bytes for AES Keywrap algorithms
         to_wrap = _ENCRYPTION_PROTOCOL_V2.encode().ljust(8, b'\0') + cek
         wrapped_cek = kek.wrap_key(to_wrap)
+    else:
+        raise ValueError("Invalid encryption version specified.")
 
     # Build the encryption_data dict.
     # Use OrderedDict to comply with Java's ordering requirement.

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/azure/storage/blob/_generated/_azure_blob_storage.py

@@ -48,7 +48,7 @@ class AzureBlobStorage:  # pylint: disable=client-accepts-api-version-keyword
     :param base_url: Service URL. Required. Default value is "".
     :type base_url: str
     :keyword version: Specifies the version of the operation to use for this request. Default value
-     is "2024-08-04". Note that overriding this default value may result in unsupported behavior.
+     is "2025-01-05". Note that overriding this default value may result in unsupported behavior.
     :paramtype version: str
     """
 

{azure_storage_blob-12.23.1 → azure_storage_blob-12.24.0}/azure/storage/blob/_generated/_configuration.py

@@ -23,12 +23,12 @@ class AzureBlobStorageConfiguration:  # pylint: disable=too-many-instance-attrib
      desired operation. Required.
     :type url: str
     :keyword version: Specifies the version of the operation to use for this request. Default value
-     is "2024-08-04". Note that overriding this default value may result in unsupported behavior.
+     is "2025-01-05". Note that overriding this default value may result in unsupported behavior.
     :paramtype version: str
     """
 
     def __init__(self, url: str, **kwargs: Any) -> None:
-        version: Literal["2024-08-04"] = kwargs.pop("version", "2024-08-04")
+        version: Literal["2025-01-05"] = kwargs.pop("version", "2025-01-05")
 
         if url is None:
             raise ValueError("Parameter 'url' must not be None.")