Share via

ShareFileClient Class

  • Reference

A client to interact with a specific file, although that file may not yet exist.

For more optional configuration, please click here.

Inheritance
azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin
ShareFileClient

Constructor

ShareFileClient(account_url: str, share_name: str, file_path: str, snapshot: str | Dict[str, Any] | None = None, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, *, token_intent: Literal['backup'] | None = None, **kwargs: Any)

Parameters

Name Description
account_url
Required
str

The URI to the storage account. In order to create a client given the full URI to the file, use the from_file_url classmethod.
share_name
Required
str

The name of the share for the file.
file_path
Required
str

The file path to the file with which to interact. If specified, this value will override a file value specified in the file URL.
snapshot
str

An optional file snapshot on which to operate. This can be the snapshot ID string or the response returned from create_snapshot.

Default value: None
credential
AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None

The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, an instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials, an account shared access key, or an instance of a TokenCredentials class from azure.identity. If the resource URI already contains a SAS token, this will be ignored in favor of an explicit credential

  • except in the case of AzureSasCredential, where the conflicting SAS tokens will raise a ValueError. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key.
Default value: None

Keyword-Only Parameters

Name Description
token_intent
Literal['backup']

Required when using TokenCredential for authentication and 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.
allow_trailing_dot
bool

If true, the trailing dot will not be trimmed from the target URI.
allow_source_trailing_dot
bool

If true, the trailing dot will not be trimmed from the source URI.
api_version
str

The Storage API version to use for requests. Default value is the most recent service version that is compatible with the current SDK. Setting to an older version may result in reduced feature compatibility.

New in version 12.1.0.
secondary_hostname
str

The hostname of the secondary endpoint.
max_range_size
int

The maximum range size used for a file upload. Defaults to 4*1024*1024.
audience
str

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://.file.core.windows.net.

Methods

abort_copy

Abort an ongoing copy operation.

This will leave a destination file with zero length and full metadata. This will raise an error if the copy operation has already ended.
acquire_lease

Requests a new lease.

If the file does not have an active lease, the File Service creates a lease on the blob and returns a new lease.
clear_range

Clears the specified range and releases the space used in storage for that range.
close

This method is to close the sockets opened by the client. It need not be used when using with a context manager.
close_all_handles

Close any open file handles.

This operation will block until the service has closed all open handles.
close_handle

Close an open file handle.
create_file

Creates a new file.

Note that it only initializes the file with no content.
delete_file

Marks the specified file for deletion. The file is later deleted during garbage collection.
download_file

Downloads a file to the StorageStreamDownloader. The readall() method must be used to read all the content or readinto() must be used to download the file into a stream. Using chunks() returns an iterator which allows the user to iterate over the content in chunks.
exists

Returns True if the file exists and returns False otherwise.
from_connection_string

Create ShareFileClient from a Connection String.
from_file_url

A client to interact with a specific file, although that file may not yet exist.
get_file_properties

Returns all user-defined metadata, standard HTTP properties, and system properties for the file.
get_ranges

Returns the list of valid page ranges for a file or snapshot of a file.
get_ranges_diff

Returns the list of valid page ranges for a file or snapshot of a file.

New in version 12.6.0.
list_handles

Lists handles for file.
rename_file

Rename the source file.
resize_file

Resizes a file to the specified size.
set_file_metadata

Sets user-defined metadata for the specified file as one or more name-value pairs.

Each call to this operation replaces all existing metadata attached to the file. To remove all metadata from the file, call this operation with no metadata dict.
set_http_headers

Sets HTTP headers on the file.
start_copy_from_url

Initiates the copying of data from a source URL into the file referenced by the client.

The status of this copy operation can be found using the get_properties method.
upload_file

Uploads a new file.
upload_range

Upload a range of bytes to a file.
upload_range_from_url

Writes the bytes from one Azure File endpoint into the specified range of another Azure File endpoint.

abort_copy

Abort an ongoing copy operation.

This will leave a destination file with zero length and full metadata. This will raise an error if the copy operation has already ended.

abort_copy(copy_id: str | FileProperties, **kwargs: Any) -> None

Parameters

Name Description
copy_id
Required
str or FileProperties

The copy operation to abort. This can be either an ID, or an instance of FileProperties.

Keyword-Only Parameters

Name Description
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
None

acquire_lease

Requests a new lease.

If the file does not have an active lease, the File Service creates a lease on the blob and returns a new lease.

acquire_lease(lease_id: str | None = None, **kwargs: Any) -> ShareLeaseClient

Parameters

Name Description
lease_id
Required
str

Proposed lease ID, in a GUID string format. The File Service returns 400 (Invalid request) if the proposed lease ID is not in the correct format.

Keyword-Only Parameters

Name Description
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
ShareLeaseClient

A ShareLeaseClient object.

Examples

Acquiring a lease on a file.


   source_file.create_file(1024)
   lease = source_file.acquire_lease()
   source_file.upload_file(b'hello world', lease=lease)

   lease.release()

clear_range

Clears the specified range and releases the space used in storage for that range.

clear_range(offset: int, length: int, **kwargs: Any) -> Dict[str, Any]

Parameters

Name Description
offset
Required
int

Start of byte range to use for clearing a section of the file. The range can be up to 4 MB in size.
length
Required
int

Number of bytes to use for clearing a section of the file. The range can be up to 4 MB in size.

Keyword-Only Parameters

Name Description
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
Dict[str, Any]

File-updated property dict (Etag and last modified).

close

This method is to close the sockets opened by the client. It need not be used when using with a context manager.

close()

Keyword-Only Parameters

Name Description
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

close_all_handles

Close any open file handles.

This operation will block until the service has closed all open handles.

close_all_handles(**kwargs: Any) -> Dict[str, int]

Keyword-Only Parameters

Name Description
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
dict[str, int]

The number of handles closed (this may be 0 if the specified handle was not found) and the number of handles failed to close in a dict.

close_handle

Close an open file handle.

close_handle(handle: str | Handle, **kwargs: Any) -> Dict[str, int]

Parameters

Name Description
handle
Required
str or Handle

A specific handle to close.

Keyword-Only Parameters

Name Description
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
dict[str, int]

The number of handles closed (this may be 0 if the specified handle was not found) and the number of handles failed to close in a dict.

create_file

Creates a new file.

Note that it only initializes the file with no content.

create_file(size: int, file_attributes: str | NTFSAttributes | None = 'none', file_creation_time: str | datetime | None = 'now', file_last_write_time: str | datetime | None = 'now', file_permission: str | None = None, permission_key: str | None = None, **kwargs: Any) -> Dict[str, Any]

Parameters

Name Description
size
Required
int

Specifies the maximum size for the file, up to 1 TB.
file_attributes
Required
str or NTFSAttributes

The file system attributes for files and directories. If not set, the default value would be "None" and the attributes will be set to "Archive". Here is an example for when the var type is str: 'Temporary|Archive'. file_attributes value is not case sensitive.
file_creation_time
Required
str or datetime

Creation time for the file Default value: Now.
file_last_write_time
Required
str or datetime

Last write time for the file Default value: Now.
file_permission
Required
str

If specified the permission (security descriptor) shall be set for the directory/file. This header can be used if Permission size is <= 8KB, else x-ms-file-permission-key header shall be used. Default value: Inherit. If SDDL is specified as input, it must have owner, group and dacl. Note: Only one of the x-ms-file-permission or x-ms-file-permission-key should be specified.
permission_key
Required
str

Key of the permission to be set for the directory/file. Note: Only one of the x-ms-file-permission or x-ms-file-permission-key should be specified.

Keyword-Only Parameters

Name Description
file_permission_format
Literal['sddl', 'binary']

Specifies the format in which the permission is returned. If not specified, SDDL will be the default.
file_change_time
str or datetime

Change time for the file. If not specified, change time will be set to the current date/time.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.
content_settings
ContentSettings

ContentSettings object used to set file properties. Used to set content type, encoding, language, disposition, md5, and cache control.
metadata
Optional[dict[str, str]]

Name-value pairs associated with the file as metadata.
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
dict[str, Any]

File-updated property dict (Etag and last modified).

Examples

Create a file.


   # Create and allocate bytes for the file (no content added yet)
   my_allocated_file.create_file(size=100)

delete_file

Marks the specified file for deletion. The file is later deleted during garbage collection.

delete_file(**kwargs: Any) -> None

Keyword-Only Parameters

Name Description
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
None

Examples

Delete a file.


   my_file.delete_file()

download_file

Downloads a file to the StorageStreamDownloader. The readall() method must be used to read all the content or readinto() must be used to download the file into a stream. Using chunks() returns an iterator which allows the user to iterate over the content in chunks.

download_file(offset: int | None = None, length: int | None = None, **kwargs: Any) -> StorageStreamDownloader

Parameters

Name Description
offset
Required
int

Start of byte range to use for downloading a section of the file. Must be set if length is provided.
length
Required
int

Number of bytes to read from the stream. This is optional, but should be supplied for optimal performance.

Keyword-Only Parameters

Name Description
max_concurrency
int

Maximum number of parallel connections to use when transferring the file in chunks. This option does not affect the underlying connection pool, and may require a separate configuration of the connection pool.
validate_content
bool

If true, calculates an MD5 hash for each chunk of the file. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the file. 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.
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
progress_hook
Callable[[int, int], None]

A callback to track the progress of a long running download. The signature is function(current: int, total: int) where current is the number of bytes transferred so far, and total is the total size of the download.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
<xref:azure.storage.fileshare.StorageStreamDownloader>

A streaming object (StorageStreamDownloader)

Examples

Download a file.


   with open(DEST_FILE, "wb") as data:
       stream = my_file.download_file()
       data.write(stream.readall())

exists

Returns True if the file exists and returns False otherwise.

exists(**kwargs: Any) -> bool

Keyword-Only Parameters

Name Description
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
bool

True if the file exists, False otherwise.

from_connection_string

Create ShareFileClient from a Connection String.

from_connection_string(conn_str: str, share_name: str, file_path: str, snapshot: str | Dict[str, Any] | None = None, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parameters

Name Description
conn_str
Required
str

A connection string to an Azure Storage account.
share_name
Required
str

The name of the share.
file_path
Required
str

The file path.
snapshot
str

An optional file snapshot on which to operate. This can be the snapshot ID string or the response returned from create_snapshot.

Default value: None
credential
AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None

The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, an instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials, an account shared access key, or an instance of a TokenCredentials class from azure.identity. If the resource URI already contains a SAS token, this will be ignored in favor of an explicit credential

  • except in the case of AzureSasCredential, where the conflicting SAS tokens will raise a ValueError. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key.
Default value: None

Keyword-Only Parameters

Name Description
audience
str

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://.file.core.windows.net.

Returns

Type Description
ShareFileClient

A File client.

Examples

Creates the file client with connection string.


   from azure.storage.fileshare import ShareFileClient
   file = ShareFileClient.from_connection_string(
       self.connection_string,
       share_name="helloworld2",
       file_path="myfile")

from_file_url

A client to interact with a specific file, although that file may not yet exist.

from_file_url(file_url: str, snapshot: str | Dict[str, Any] | None = None, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parameters

Name Description
file_url
Required
str

The full URI to the file.
snapshot
str

An optional file snapshot on which to operate. This can be the snapshot ID string or the response returned from create_snapshot.

Default value: None
credential
AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None

The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, an instance of a AzureSasCredential or AzureNamedKeyCredential from azure.core.credentials, an account shared access key, or an instance of a TokenCredentials class from azure.identity. If the resource URI already contains a SAS token, this will be ignored in favor of an explicit credential

  • except in the case of AzureSasCredential, where the conflicting SAS tokens will raise a ValueError. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key.
Default value: None

Keyword-Only Parameters

Name Description
audience
str

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://.file.core.windows.net.

Returns

Type Description
ShareFileClient

A File client.

get_file_properties

Returns all user-defined metadata, standard HTTP properties, and system properties for the file.

get_file_properties(**kwargs: Any) -> FileProperties

Keyword-Only Parameters

Name Description
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
FileProperties

FileProperties

get_ranges

Returns the list of valid page ranges for a file or snapshot of a file.

get_ranges(offset: int | None = None, length: int | None = None, **kwargs: Any) -> List[Dict[str, int]]

Parameters

Name Description
offset
Required
int

Specifies the start offset of bytes over which to get ranges.
length
Required
int

Number of bytes to use over which to get ranges.

Keyword-Only Parameters

Name Description
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
List[dict[str, int]]

A list of valid ranges.

get_ranges_diff

Returns the list of valid page ranges for a file or snapshot of a file.

New in version 12.6.0.

get_ranges_diff(previous_sharesnapshot: str | Dict[str, Any], offset: int | None = None, length: int | None = None, *, include_renames: bool | None = None, **kwargs: Any) -> Tuple[List[Dict[str, int]], List[Dict[str, int]]]

Parameters

Name Description
offset
Required
int

Specifies the start offset of bytes over which to get ranges.
length
Required
int

Number of bytes to use over which to get ranges.
previous_sharesnapshot
Required
str

The snapshot diff parameter that contains an opaque DateTime value that specifies a previous file snapshot to be compared against a more recent snapshot or the current file.

Keyword-Only Parameters

Name Description
include_renames
Optional[bool]

Only valid if previous_sharesnapshot parameter is provided. Specifies whether the changed ranges for a file that has been renamed or moved between the target snapshot (or live file) and the previous snapshot should be listed. If set to True, the valid changed ranges for the file will be returned. If set to False, the operation will result in a 409 (Conflict) response.
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
tuple[list[dict[str, str], list[dict[str, str]]

A tuple of two lists of file ranges as dictionaries with 'start' and 'end' keys. The first element are filled file ranges, the 2nd element is cleared file ranges.

list_handles

Lists handles for file.

list_handles(**kwargs: Any) -> ItemPaged[Handle]

Keyword-Only Parameters

Name Description
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
ItemPaged[Handle]

An auto-paging iterable of Handle

rename_file

Rename the source file.

rename_file(new_name: str, **kwargs: Any) -> ShareFileClient

Parameters

Name Description
new_name
Required
str

The new file name.

Keyword-Only Parameters

Name Description
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.
overwrite
bool

A boolean value for if the destination file already exists, whether this request will overwrite the file or not. If true, the rename will succeed and will overwrite the destination file. If not provided or if false and the destination file does exist, the request will not overwrite the destination file. If provided and the destination file doesn't exist, the rename will succeed.
ignore_read_only
bool

A boolean value that specifies whether the ReadOnly attribute on a preexisting destination file should be respected. If true, the rename will succeed, otherwise, a previous file at the destination with the ReadOnly attribute set will cause the rename to fail.
file_permission
str

If specified the permission (security descriptor) shall be set for the file. This header can be used if Permission size is <= 8KB, else file_permission_key shall be used. If SDDL is specified as input, it must have owner, group and dacl. A value of 'preserve' can be passed to preserve source permissions. Note: Only one of the file_permission or file_permission_key should be specified.
file_permission_key
str

Key of the permission to be set for the file. Note: Only one of the file-permission or file-permission-key should be specified.
file_permission_format
Literal['sddl', 'binary']

Specifies the format in which the permission is returned. If not specified, SDDL will be the default.
file_attributes
NTFSAttributes or str

The file system attributes for the file.
file_creation_time
datetime or str

Creation time for the file.
file_last_write_time
datetime or str

Last write time for the file.
file_change_time
str or datetime

Change time for the file. If not specified, change time will be set to the current date/time.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.
content_type
str

The Content Type of the new file.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.
metadata
Dict[str,str]

A name-value pair to associate with a file storage object.
source_lease
ShareLeaseClient or str

Required if the source file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.
destination_lease
ShareLeaseClient or str

Required if the destination file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

Returns

Type Description
ShareFileClient

The new File Client.

resize_file

Resizes a file to the specified size.

resize_file(size: int, **kwargs: Any) -> Dict[str, Any]

Parameters

Name Description
size
Required
int

Size to resize file to (in bytes)

Keyword-Only Parameters

Name Description
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
Dict[str, Any]

File-updated property dict (Etag and last modified).

set_file_metadata

Sets user-defined metadata for the specified file as one or more name-value pairs.

Each call to this operation replaces all existing metadata attached to the file. To remove all metadata from the file, call this operation with no metadata dict.

set_file_metadata(metadata: Dict[str, Any] | None = None, **kwargs: Any) -> Dict[str, Any]

Parameters

Name Description
metadata
Required
dict[str, str]

Name-value pairs associated with the file as metadata.

Keyword-Only Parameters

Name Description
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
dict[str, Any]

File-updated property dict (Etag and last modified).

set_http_headers

Sets HTTP headers on the file.

set_http_headers(content_settings: ContentSettings, file_attributes: str | NTFSAttributes = 'preserve', file_creation_time: str | datetime | None = 'preserve', file_last_write_time: str | datetime | None = 'preserve', file_permission: str | None = None, permission_key: str | None = None, **kwargs: Any) -> Dict[str, Any]

Parameters

Name Description
content_settings
Required
ContentSettings

ContentSettings object used to set file properties. Used to set content type, encoding, language, disposition, md5, and cache control.
file_attributes
Required
str or NTFSAttributes

The file system attributes for files and directories. If not set, indicates preservation of existing values. Here is an example for when the var type is str: 'Temporary|Archive'
file_creation_time
Required
str or datetime

Creation time for the file Default value: Preserve.
file_last_write_time
Required
str or datetime

Last write time for the file Default value: Preserve.
file_permission
Required
str

If specified the permission (security descriptor) shall be set for the directory/file. This header can be used if Permission size is <= 8KB, else x-ms-file-permission-key header shall be used. Default value: Inherit. If SDDL is specified as input, it must have owner, group and dacl. Note: Only one of the x-ms-file-permission or x-ms-file-permission-key should be specified.
permission_key
Required
str

Key of the permission to be set for the directory/file. Note: Only one of the x-ms-file-permission or x-ms-file-permission-key should be specified.

Keyword-Only Parameters

Name Description
file_permission_format
Literal['sddl', 'binary']

Specifies the format in which the permission is returned. If not specified, SDDL will be the default.
file_change_time
str or datetime

Change time for the file. If not specified, change time will be set to the current date/time.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
dict[str, Any]

File-updated property dict (Etag and last modified).

start_copy_from_url

Initiates the copying of data from a source URL into the file referenced by the client.

The status of this copy operation can be found using the get_properties method.

start_copy_from_url(source_url: str, **kwargs: Any) -> Dict[str, Any]

Parameters

Name Description
source_url
Required
str

Specifies the URL of the source file.

Keyword-Only Parameters

Name Description
file_permission
str

If specified the permission (security descriptor) shall be set for the directory/file. This value can be set to "source" to copy the security descriptor from the source file. Otherwise if set, this value will be used to override the source value. If not set, permission value is inherited from the parent directory of the target file. This setting can be used if Permission size is <= 8KB, otherwise permission_key shall be used. If SDDL is specified as input, it must have owner, group and dacl. Note: Only one of the file_permission or permission_key should be specified.

New in version 12.1.0: This parameter was introduced in API version '2019-07-07'.
permission_key
str

Key of the permission to be set for the directory/file. This value can be set to "source" to copy the security descriptor from the source file. Otherwise if set, this value will be used to override the source value. If not set, permission value is inherited from the parent directory of the target file. Note: Only one of the file_permission or permission_key should be specified.

New in version 12.1.0: This parameter was introduced in API version '2019-07-07'.
file_permission_format
Literal['sddl', 'binary']

Specifies the format in which the permission is returned. If not specified, SDDL will be the default.
file_attributes
NTFSAttributes

This value can be set to "source" to copy file attributes from the source file to the target file, or to clear all attributes, it can be set to "None". Otherwise it can be set to a list of attributes to set on the target file. If this is not set, the default value is "Archive".

New in version 12.1.0: This parameter was introduced in API version '2019-07-07'.
file_creation_time
str or datetime

This value can be set to "source" to copy the creation time from the source file to the target file, or a datetime to set as creation time on the target file. This could also be a string in ISO 8601 format. If this is not set, creation time will be set to the date time value of the creation (or when it was overwritten) of the target file by copy engine.

New in version 12.1.0: This parameter was introduced in API version '2019-07-07'.
file_last_write_time
str or datetime

This value can be set to "source" to copy the last write time from the source file to the target file, or a datetime to set as the last write time on the target file. This could also be a string in ISO 8601 format. If this is not set, value will be the last write time to the file by the copy engine.

New in version 12.1.0: This parameter was introduced in API version '2019-07-07'.
file_change_time
str or datetime

Change time for the file. If not specified, change time will be set to the current date/time.

New in version 12.9.0: This parameter was introduced in API version '2021-06-08'.
ignore_read_only
bool

Specifies the option to overwrite the target file if it already exists and has read-only attribute set.

New in version 12.1.0: This parameter was introduced in API version '2019-07-07'.
set_archive_attribute
bool

Specifies the option to set the archive attribute on the target file. True means the archive attribute will be set on the target file despite attribute overrides or the source file state.

New in version 12.1.0: This parameter was introduced in API version '2019-07-07'.
metadata
Optional[dict[str, str]]

Name-value pairs associated with the file as metadata.
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type Description
dict[str, Any]

Response after data copying operation has been initiated.

Examples

Copy a file from a URL


   destination_file.start_copy_from_url(source_url=source_url)

upload_file

Uploads a new file.

upload_file(data: bytes | str | Iterable | IO, length: int | None = None, file_attributes: str | NTFSAttributes = 'none', file_creation_time: str | datetime | None = 'now', file_last_write_time: str | datetime | None = 'now', file_permission: str | None = None, permission_key: str | None = None, **kwargs) -> Dict[str, Any]

Parameters

Name Description
data
Required
Union[bytes, str, Iterable[AnyStr], IO[AnyStr]]

Content of the file.
length
Required
int

Length of the file in bytes. Specify its maximum size, up to 1 TiB.
file_attributes
Required
str or NTFSAttributes

The file system attributes for files and directories. If not set, the default value would be "None" and the attributes will be set to "Archive". Here is an example for when the var type is str: 'Temporary|Archive'. file_attributes value is not case sensitive.
file_creation_time
Required
str or datetime

Creation time for the file Default value: Now.
file_last_write_time
Required
str or datetime

Last write time for the file Default value: Now.
file_permission
Required
str

If specified the permission (security descriptor) shall be set for the directory/file. This header can be used if Permission size is <= 8KB, else x-ms-file-permission-key header shall be used. Default value: Inherit. If SDDL is specified as input, it must have owner, group and dacl. Note: Only one of the x-ms-file-permission or x-ms-file-permission-key should be specified.
permission_key
Required
str

Key of the permission to be set for the directory/file. Note: Only one of the x-ms-file-permission or x-ms-file-permission-key should be specified.

Keyword-Only Parameters

Name Description
file_change_time
str or datetime

Change time for the file. If not specified, change time will be set to the current date/time.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.
metadata
Optional[dict[str, str]]

Name-value pairs associated with the file as metadata.
content_settings
ContentSettings

ContentSettings object used to set file properties. Used to set content type, encoding, language, disposition, md5, and cache control.
validate_content
bool

If true, calculates an MD5 hash for each range of the file. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the file.
max_concurrency
int

Maximum number of parallel connections to use when transferring the file in chunks. This option does not affect the underlying connection pool, and may require a separate configuration of the connection pool.
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
progress_hook
Callable[[int, Optional[int]], None]

A callback to track the progress of a long running upload. The signature is function(current: int, total: Optional[int]) where current is the number of bytes transferred so far, and total is the size of the blob or None if the size is unknown.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.
encoding
str

Defaults to UTF-8.

Returns

Type Description
dict[str, Any]

File-updated property dict (Etag and last modified).

Examples

Upload a file.


   with open(SOURCE_FILE, "rb") as source:
       my_file.upload_file(source)

upload_range

Upload a range of bytes to a file.

upload_range(data: bytes, offset: int, length: int, **kwargs: Any) -> Dict[str, Any]

Parameters

Name Description
data
Required
bytes

The data to upload.
offset
Required
int

Start of byte range to use for uploading a section of the file. The range can be up to 4 MB in size.
length
Required
int

Number of bytes to use for uploading a section of the file. The range can be up to 4 MB in size.

Keyword-Only Parameters

Name Description
validate_content
bool

If true, calculates an MD5 hash of the page content. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the file.
file_last_write_mode
Literal["preserve", "now"]

If the file last write time should be preserved or overwritten. Possible values are "preserve" or "now". If not specified, file last write time will be changed to the current date/time.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.
encoding
str

Defaults to UTF-8.

Returns

Type Description
Dict[str, Any]

File-updated property dict (Etag and last modified).

upload_range_from_url

Writes the bytes from one Azure File endpoint into the specified range of another Azure File endpoint.

upload_range_from_url(source_url: str, offset: int, length: int, source_offset: int, **kwargs: Any) -> Dict[str, Any]

Parameters

Name Description
offset
Required
int

Start of byte range to use for updating a section of the file. The range can be up to 4 MB in size.
length
Required
int

Number of bytes to use for updating a section of the file. The range can be up to 4 MB in size.
source_url
Required
str

A URL of up to 2 KB in length that specifies an Azure file or blob. The value should be URL-encoded as it would appear in a request URI. If the source is in another account, the source must either be public or must be authenticated via a shared access signature. If the source is public, no authentication is required. Examples: https://myaccount.file.core.windows.net/myshare/mydir/myfile https://otheraccount.file.core.windows.net/myshare/mydir/myfile?sastoken
source_offset
Required
int

This indicates the start of the range of bytes(inclusive) that has to be taken from the copy source. The service will read the same number of bytes as the destination range (length-offset).

Keyword-Only Parameters

Name Description
source_if_modified_since
datetime

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. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the source blob has been modified since the specified date/time.
source_if_unmodified_since
datetime

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. If a date is passed in without timezone info, it is assumed to be UTC. Specify this conditional header to copy the blob only if the source blob has not been modified since the specified date/time.
source_etag
str

The source 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.
source_match_condition
MatchConditions

The source match condition to use upon the etag.
file_last_write_mode
Literal["preserve", "now"]

If the file last write time should be preserved or overwritten. Possible values are "preserve" or "now". If not specified, file last write time will be changed to the current date/time.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.
lease
ShareLeaseClient or str

Required if the file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

New in version 12.1.0.
timeout
int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.
source_authorization
str

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

Type Description
dict[str, Any]

Result after writing to the specified range of the destination Azure File endpoint.

Attributes

api_version

The version of the Storage API used for requests.

Returns

Type Description
str

location_mode

The location mode that the client is currently using.

By default this will be "primary". Options include "primary" and "secondary".

Returns

Type Description
str

primary_endpoint

The full primary endpoint URL.

Returns

Type Description
str

primary_hostname

The hostname of the primary endpoint.

Returns

Type Description
str

secondary_endpoint

The full secondary endpoint URL if configured.

If not available a ValueError will be raised. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Returns

Type Description
str

Exceptions

Type Description
ValueError

secondary_hostname

The hostname of the secondary endpoint.

If not available this will be None. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Returns

Type Description
Optional[str]

url

The full endpoint URL to this entity, including SAS token if used.

This could be either the primary endpoint, or the secondary endpoint depending on the current location_mode. :returns: The full endpoint URL to this entity, including SAS token if used. :rtype: str