azure-storage-blob 12.25.1__py3-none-any.whl → 12.26.0__py3-none-any.whl

azure/storage/blob/__init__.py

@@ -122,7 +122,7 @@ def upload_blob_to_url(
         entire blocks, and doing so defeats the purpose of the memory-efficient algorithm.
     :keyword str encoding:
         Encoding to use if text is supplied as input. Defaults to UTF-8.
-    :returns: Blob-updated property dict (Etag and last modified)
+    :return: Blob-updated property dict (Etag and last modified)
     :rtype: dict(str, Any)
     """
     with BlobClient.from_blob_url(blob_url, credential=credential) as client:
@@ -153,7 +153,7 @@ def download_blob_from_url(
     :param output:
         Where the data should be downloaded to. This could be either a file path to write to,
         or an open IO handle to write to.
-    :type output: str or writable stream.
+    :type output: str or IO.
     :param credential:
         The credentials with which to authenticate. This is optional if the
         blob URL already has a SAS token or the blob is public. The value can be a SAS token string,
@@ -190,6 +190,7 @@ def download_blob_from_url(
         blob. Also note that if enabled, the memory-efficient upload algorithm
         will not be used, because computing the MD5 hash requires buffering
         entire blocks, and doing so defeats the purpose of the memory-efficient algorithm.
+    :return: None
     :rtype: None
     """
     overwrite = kwargs.pop('overwrite', False)

azure/storage/blob/_blob_client.py

@@ -236,7 +236,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         :keyword str audience: The audience to use when requesting tokens for Azure Active Directory
             authentication. Only has an effect when credential is of type TokenCredential. The value could be
             https://storage.azure.com/ (default) or https://<account>.blob.core.windows.net.
-        :returns: A Blob client.
+        :return: A Blob client.
         :rtype: ~azure.storage.blob.BlobClient
         """
         account_url, container_name, blob_name, path_snapshot = _from_blob_url(blob_url=blob_url, snapshot=snapshot)
@@ -284,7 +284,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         :keyword str audience: The audience to use when requesting tokens for Azure Active Directory
             authentication. Only has an effect when credential is of type TokenCredential. The value could be
             https://storage.azure.com/ (default) or https://<account>.blob.core.windows.net.
-        :returns: A Blob client.
+        :return: A Blob client.
         :rtype: ~azure.storage.blob.BlobClient
 
         .. admonition:: Example:
@@ -311,7 +311,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         The information can also be retrieved if the user has a SAS to a container or blob.
         The keys in the returned dictionary include 'sku_name' and 'account_kind'.
 
-        :returns: A dict of account information (SKU and account type).
+        :return: A dict of account information (SKU and account type).
         :rtype: dict(str, str)
         """
         try:
@@ -422,7 +422,16 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         :keyword str source_authorization:
             Authenticate as a service principal using a client secret to access a source blob. Ensure "bearer " is
             the prefix of the source_authorization string.
-        :returns: Blob-updated property Dict (Etag and last modified)
+        :keyword source_token_intent:
+            Required when source is Azure Storage Files and using `TokenCredential` for authentication.
+            This is ignored for other forms of authentication.
+            Specifies the intent for all requests when using `TokenCredential` authentication. Possible values are:
+
+            backup - Specifies requests are intended for backup/admin type operations, meaning that all file/directory
+                 ACLs are bypassed and full permissions are granted. User must also have required RBAC permission.
+
+        :paramtype source_token_intent: Literal['backup']
+        :return: Blob-updated property Dict (Etag and last modified)
         :rtype: Dict[str, Any]
         """
         if kwargs.get('cpk') and self.scheme.lower() != 'https':
@@ -430,7 +439,8 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         options = _upload_blob_from_url_options(
             source_url=source_url,
             metadata=metadata,
-            **kwargs)
+            **kwargs
+        )
         try:
             return cast(Dict[str, Any], self._client.block_blob.put_blob_from_url(**options))
         except HttpResponseError as error:
@@ -570,7 +580,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__. This method may make multiple calls to the service and
             the timeout will apply to each call individually.
-        :returns: Blob-updated property Dict (Etag and last modified)
+        :return: Blob-updated property Dict (Etag and last modified)
         :rtype: Dict[str, Any]
 
         .. admonition:: Example:
@@ -715,7 +725,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             the timeout will apply to each call individually.
             multiple calls to the Azure service and the timeout will apply to
             each call individually.
-        :returns: A streaming object (StorageStreamDownloader)
+        :return: A streaming object (StorageStreamDownloader)
         :rtype: ~azure.storage.blob.StorageStreamDownloader
 
         .. admonition:: Example:
@@ -819,7 +829,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: A streaming object (BlobQueryReader)
+        :return: A streaming object (BlobQueryReader)
         :rtype: ~azure.storage.blob.BlobQueryReader
 
         .. admonition:: Example:
@@ -864,7 +874,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         and retains the blob for a specified number of days.
         After the specified number of days, the blob's data is removed from the service during garbage collection.
         Soft deleted blob is accessible through :func:`~ContainerClient.list_blobs()` specifying `include=['deleted']`
-        option. Soft-deleted blob can be restored using :func:`undelete` operation.
+        option. Soft-deleted blob can be restored using :func:`~BlobClient.undelete_blob()` operation.
 
         :param Optional[str] delete_snapshots:
             Required if the blob has associated snapshots. Values include:
@@ -912,6 +922,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
+        :return: None
         :rtype: None
 
         .. admonition:: Example:
@@ -950,6 +961,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
+        :return: None
         :rtype: None
 
         .. admonition:: Example:
@@ -981,7 +993,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: boolean
+        :return: boolean
         :rtype: bool
         """
         version_id = get_version_id(self.version_id, kwargs)
@@ -1051,7 +1063,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: BlobProperties
+        :return: BlobProperties
         :rtype: ~azure.storage.blob.BlobProperties
 
         .. admonition:: Example:
@@ -1137,7 +1149,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified)
+        :return: Blob-updated property dict (Etag and last modified)
         :rtype: Dict[str, Any]
         """
         options = _set_http_headers_options(content_settings=content_settings, **kwargs)
@@ -1204,7 +1216,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified)
+        :return: Blob-updated property dict (Etag and last modified)
         :rtype: Dict[str, Union[str, datetime]]
         """
         if kwargs.get('cpk') and self.scheme.lower() != 'https':
@@ -1240,7 +1252,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Key value pairs of blob tags.
+        :return: Key value pairs of blob tags.
         :rtype: Dict[str, str]
         """
 
@@ -1266,7 +1278,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Key value pairs of blob tags.
+        :return: Key value pairs of blob tags.
         :rtype: Dict[str, str]
         """
 
@@ -1291,7 +1303,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Key value pairs of blob tags.
+        :return: Key value pairs of blob tags.
         :rtype: Dict[str, Union[str, datetime, bool]]
         """
 
@@ -1388,7 +1400,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified).
+        :return: Blob-updated property dict (Etag and last modified).
         :rtype: dict[str, Any]
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -1484,7 +1496,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified).
+        :return: Blob-updated property dict (Etag and last modified).
         :rtype: dict[str, Any]
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -1563,7 +1575,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Snapshot ID, Etag, and last modified).
+        :return: Blob-updated property dict (Snapshot ID, Etag, and last modified).
         :rtype: dict[str, Any]
 
         .. admonition:: Example:
@@ -1746,6 +1758,15 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
 
             .. versionadded:: 12.9.0
 
+        :keyword source_token_intent:
+            Required when source is Azure Storage Files and using `TokenCredential` for authentication.
+            This is ignored for other forms of authentication.
+            Specifies the intent for all requests when using `TokenCredential` authentication. Possible values are:
+
+            backup - Specifies requests are intended for backup/admin type operations, meaning that all file/directory
+                 ACLs are bypassed and full permissions are granted. User must also have required RBAC permission.
+
+        :paramtype source_token_intent: Literal['backup']
         :keyword str encryption_scope:
             A predefined encryption scope used to encrypt the data on the sync copied blob. An encryption
             scope can be created using the Management API and referenced here by name. If a default
@@ -1754,7 +1775,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
 
             .. versionadded:: 12.10.0
 
-        :returns: A dictionary of copy properties (etag, last_modified, copy_id, copy_status).
+        :return: A dictionary of copy properties (etag, last_modified, copy_id, copy_status).
         :rtype: dict[str, Union[str, ~datetime.datetime]]
 
         .. admonition:: Example:
@@ -1770,7 +1791,8 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             source_url=source_url,
             metadata=metadata,
             incremental_copy=incremental_copy,
-            **kwargs)
+            **kwargs
+        )
         try:
             if incremental_copy:
                 return cast(Dict[str, Union[str, datetime]], self._client.page_blob.copy_incremental(**options))
@@ -1792,6 +1814,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             The copy operation to abort. This can be either an ID string, or an
             instance of BlobProperties.
         :type copy_id: str or ~azure.storage.blob.BlobProperties
+        :return: None
         :rtype: None
 
         .. admonition:: Example:
@@ -1854,7 +1877,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: A BlobLeaseClient object.
+        :return: A BlobLeaseClient object.
         :rtype: ~azure.storage.blob.BlobLeaseClient
 
         .. admonition:: Example:
@@ -1910,6 +1933,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             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
+        :return: None
         :rtype: None
         """
         access_conditions = get_access_conditions(kwargs.pop('lease', None))
@@ -1980,7 +2004,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob property dict.
+        :return: Blob property dict.
         :rtype: dict[str, Any]
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -2046,7 +2070,16 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         :keyword str source_authorization:
             Authenticate as a service principal using a client secret to access a source blob. Ensure "bearer " is
             the prefix of the source_authorization string.
-        :returns: Blob property dict.
+        :keyword source_token_intent:
+            Required when source is Azure Storage Files and using `TokenCredential` for authentication.
+            This is ignored for other forms of authentication.
+            Specifies the intent for all requests when using `TokenCredential` authentication. Possible values are:
+
+            backup - Specifies requests are intended for backup/admin type operations, meaning that all file/directory
+                 ACLs are bypassed and full permissions are granted. User must also have required RBAC permission.
+
+        :paramtype source_token_intent: Literal['backup']
+        :return: Blob property dict.
         :rtype: dict[str, Any]
         """
         if kwargs.get('cpk') and self.scheme.lower() != 'https':
@@ -2057,7 +2090,8 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             source_offset=source_offset,
             source_length=source_length,
             source_content_md5=source_content_md5,
-            **kwargs)
+            **kwargs
+        )
         try:
             return cast(Dict[str, Any], self._client.block_blob.stage_block_from_url(**options))
         except HttpResponseError as error:
@@ -2090,7 +2124,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: A tuple of two lists - committed and uncommitted blocks
+        :return: A tuple of two lists - committed and uncommitted blocks
         :rtype: Tuple[List[BlobBlock], List[BlobBlock]]
         """
         access_conditions = get_access_conditions(kwargs.pop('lease', None))
@@ -2202,7 +2236,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified).
+        :return: Blob-updated property dict (Etag and last modified).
         :rtype: dict(str, Any)
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -2244,6 +2278,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             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
+        :return: None
         :rtype: None
         """
         access_conditions = get_access_conditions(kwargs.pop('lease', None))
@@ -2299,7 +2334,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified)
+        :return: Blob-updated property dict (Etag and last modified)
         :rtype: Dict[str, Any]
         """
         version_id = get_version_id(self.version_id, kwargs)
@@ -2332,7 +2367,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Key value pairs of blob tags.
+        :return: Key value pairs of blob tags.
         :rtype: Dict[str, str]
         """
         version_id = get_version_id(self.version_id, kwargs)
@@ -2404,7 +2439,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns:
+        :return:
             A tuple of two lists of page ranges as dictionaries with 'start' and 'end' keys.
             The first element are filled page ranges, the 2nd element is cleared page ranges.
         :rtype: tuple(list(dict(str, str), list(dict(str, str))
@@ -2497,7 +2532,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: An iterable (auto-paging) of PageRange.
+        :return: An iterable (auto-paging) of PageRange.
         :rtype: ~azure.core.paging.ItemPaged[~azure.storage.blob.PageRange]
         """
         results_per_page = kwargs.pop('results_per_page', None)
@@ -2580,7 +2615,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns:
+        :return:
             A tuple of two lists of page ranges as dictionaries with 'start' and 'end' keys.
             The first element are filled page ranges, the 2nd element is cleared page ranges.
         :rtype: tuple(list(dict(str, str), list(dict(str, str))
@@ -2645,7 +2680,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified).
+        :return: Blob-updated property dict (Etag and last modified).
         :rtype: dict(str, Any)
         """
         options = _set_sequence_number_options(sequence_number_action, sequence_number=sequence_number, **kwargs)
@@ -2701,7 +2736,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified).
+        :return: Blob-updated property dict (Etag and last modified).
         :rtype: dict(str, Any)
         """
         if kwargs.get('cpk') and self.scheme.lower() != 'https':
@@ -2797,7 +2832,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified).
+        :return: Blob-updated property dict (Etag and last modified).
         :rtype: dict(str, Any)
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -2919,7 +2954,16 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         :keyword str source_authorization:
             Authenticate as a service principal using a client secret to access a source blob. Ensure "bearer " is
             the prefix of the source_authorization string.
-        :returns: Response after uploading pages from specified URL.
+        :keyword source_token_intent:
+            Required when source is Azure Storage Files and using `TokenCredential` for authentication.
+            This is ignored for other forms of authentication.
+            Specifies the intent for all requests when using `TokenCredential` authentication. Possible values are:
+
+            backup - Specifies requests are intended for backup/admin type operations, meaning that all file/directory
+                 ACLs are bypassed and full permissions are granted. User must also have required RBAC permission.
+
+        :paramtype source_token_intent: Literal['backup']
+        :return: Response after uploading pages from specified URL.
         :rtype: Dict[str, Any]
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -2999,7 +3043,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag and last modified).
+        :return: Blob-updated property dict (Etag and last modified).
         :rtype: dict(str, Any)
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -3096,7 +3140,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag, last modified, append offset, committed block count).
+        :return: Blob-updated property dict (Etag, last modified, append offset, committed block count).
         :rtype: dict(str, Any)
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -3211,7 +3255,16 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
         :keyword str source_authorization:
             Authenticate as a service principal using a client secret to access a source blob. Ensure "bearer " is
             the prefix of the source_authorization string.
-        :returns: Result after appending a new block.
+        :keyword source_token_intent:
+            Required when source is Azure Storage Files and using `TokenCredential` for authentication.
+            This is ignored for other forms of authentication.
+            Specifies the intent for all requests when using `TokenCredential` authentication. Possible values are:
+
+            backup - Specifies requests are intended for backup/admin type operations, meaning that all file/directory
+                 ACLs are bypassed and full permissions are granted. User must also have required RBAC permission.
+
+        :paramtype source_token_intent: Literal['backup']
+        :return: Result after appending a new block.
         :rtype: Dict[str, Union[str, datetime, int]]
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -3269,7 +3322,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob
             #other-client--per-operation-configuration>`__.
-        :returns: Blob-updated property dict (Etag, last modified, append offset, committed block count).
+        :return: Blob-updated property dict (Etag, last modified, append offset, committed block count).
         :rtype: dict(str, Any)
         """
         if self.require_encryption or (self.key_encryption_key is not None):
@@ -3286,7 +3339,7 @@ class BlobClient(StorageAccountHostsMixin, StorageEncryptionMixin):  # pylint: d
 
         The container need not already exist. Defaults to current blob's credentials.
 
-        :returns: A ContainerClient.
+        :return: A ContainerClient.
         :rtype: ~azure.storage.blob.ContainerClient
 
         .. admonition:: Example:

azure/storage/blob/_blob_client_helpers.py

@@ -197,6 +197,7 @@ def _upload_blob_from_url_options(source_url: str, **kwargs: Any) -> Dict[str, A
     overwrite = kwargs.pop('overwrite', False)
     content_settings = kwargs.pop('content_settings', None)
     source_authorization = kwargs.pop('source_authorization', None)
+    source_token_intent = kwargs.pop('source_token_intent', None)
     if content_settings:
         kwargs['blob_http_headers'] = BlobHTTPHeaders(
             blob_cache_control=content_settings.cache_control,
@@ -214,6 +215,7 @@ def _upload_blob_from_url_options(source_url: str, **kwargs: Any) -> Dict[str, A
 
     options = {
         'copy_source_authorization': source_authorization,
+        'file_request_intent': source_token_intent,
         'content_length': 0,
         'copy_source_blob_properties': kwargs.pop('include_source_blob_properties', True),
         'source_content_md5': kwargs.pop('source_content_md5', None),
@@ -268,7 +270,7 @@ def _download_blob_options(
         The string representing the SDK package version.
     :param AzureBlobStorage client:
         The generated Blob Storage client.
-    :returns: A dictionary containing the download blob options.
+    :return: A dictionary containing the download blob options.
     :rtype: Dict[str, Any]
     """
     if length is not None:
@@ -376,7 +378,7 @@ def _quick_query_options(snapshot: Optional[str], query_expression: str, **kwarg
         'timeout': kwargs.pop('timeout', None),
         'cls': return_headers_and_deserialized,
     }
-    options.update(kwargs)
+    options.update({k: v for k, v in kwargs.items() if v is not None})
     return options, delimiter
 
 def _generic_delete_blob_options(delete_snapshots: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]:
@@ -607,6 +609,7 @@ def _start_copy_from_url_options(  # pylint:disable=too-many-statements
     requires_sync = kwargs.pop('requires_sync', None)
     encryption_scope_str = kwargs.pop('encryption_scope', None)
     source_authorization = kwargs.pop('source_authorization', None)
+    source_token_intent = kwargs.pop('source_token_intent', None)
     # If tags is a str, interpret that as copy_source_tags
     copy_source_tags = isinstance(tags, str)
 
@@ -626,6 +629,8 @@ def _start_copy_from_url_options(  # pylint:disable=too-many-statements
             headers['x-ms-encryption-scope'] = encryption_scope_str
         if source_authorization:
             headers['x-ms-copy-source-authorization'] = source_authorization
+        if source_token_intent:
+            headers['x-ms-file-request-intent'] = source_token_intent
         if copy_source_tags:
             headers['x-ms-copy-source-tag-option'] = tags
     else:
@@ -635,6 +640,9 @@ def _start_copy_from_url_options(  # pylint:disable=too-many-statements
         if source_authorization:
             raise ValueError(
                 "Source authorization tokens are only supported for sync copy, please specify requires_sync=True")
+        if source_token_intent:
+            raise ValueError(
+                "Source token intent is only supported for sync copy, please specify requires_sync=True")
         if copy_source_tags:
             raise ValueError(
                 "Copying source tags is only supported for sync copy, please specify requires_sync=True")
@@ -650,19 +658,20 @@ def _start_copy_from_url_options(  # pylint:disable=too-many-statements
 
     options = {
         'copy_source': source_url,
-        'seal_blob': kwargs.pop('seal_destination_blob', None),
         'timeout': timeout,
         'modified_access_conditions': dest_mod_conditions,
-        'blob_tags_string': blob_tags_string,
         'headers': headers,
         'cls': return_response_headers,
     }
+
     if not incremental_copy:
         source_mod_conditions = get_source_conditions(kwargs)
         dest_access_conditions = get_access_conditions(kwargs.pop('destination_lease', None))
         options['source_modified_access_conditions'] = source_mod_conditions
         options['lease_access_conditions'] = dest_access_conditions
         options['tier'] = tier.value if tier else None
+        options['seal_blob'] = kwargs.pop('seal_destination_blob', None)
+        options['blob_tags_string'] = blob_tags_string
     options.update(kwargs)
     return options
 
@@ -729,6 +738,7 @@ def _stage_block_from_url_options(
 ) -> Dict[str, Any]:
     source_url = _encode_source_url(source_url=source_url)
     source_authorization = kwargs.pop('source_authorization', None)
+    source_token_intent = kwargs.pop('source_token_intent', None)
     if source_length is not None and source_offset is None:
         raise ValueError("Source offset value must not be None if length is set.")
     if source_length is not None and source_offset is not None:
@@ -747,6 +757,7 @@ def _stage_block_from_url_options(
                             encryption_algorithm=cpk.algorithm)
     options = {
         'copy_source_authorization': source_authorization,
+        'file_request_intent': source_token_intent,
         'block_id': block_id,
         'content_length': 0,
         'source_url': source_url,
@@ -1010,6 +1021,7 @@ def _upload_pages_from_url_options(
         if_sequence_number_equal_to=kwargs.pop('if_sequence_number_eq', None)
     )
     source_authorization = kwargs.pop('source_authorization', None)
+    source_token_intent = kwargs.pop('source_token_intent', None)
     access_conditions = get_access_conditions(kwargs.pop('lease', None))
     mod_conditions = get_modify_conditions(kwargs)
     source_mod_conditions = get_source_conditions(kwargs)
@@ -1023,6 +1035,7 @@ def _upload_pages_from_url_options(
 
     options = {
         'copy_source_authorization': source_authorization,
+        'file_request_intent': source_token_intent,
         'source_url': source_url,
         'content_length': 0,
         'source_range': source_range,
@@ -1152,6 +1165,7 @@ def _append_block_from_url_options(
             append_position=appendpos_condition
         )
     source_authorization = kwargs.pop('source_authorization', None)
+    source_token_intent = kwargs.pop('source_token_intent', None)
     access_conditions = get_access_conditions(kwargs.pop('lease', None))
     mod_conditions = get_modify_conditions(kwargs)
     source_mod_conditions = get_source_conditions(kwargs)
@@ -1164,6 +1178,7 @@ def _append_block_from_url_options(
 
     options = {
         'copy_source_authorization': source_authorization,
+        'file_request_intent': source_token_intent,
         'source_url': copy_source_url,
         'content_length': 0,
         'source_range': source_range,