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: Optional[Union[str, Dict[str, Any]]] = None, credential: Optional[Any] = None, **kwargs: Any)

Parameters

account_url: str

Required

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: str

Required

The name of the share for the file.

file_path: str

Required

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

default value: None

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

credential

default value: None

The credential 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 from azure.core.credentials or an account shared access key.

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.

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_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.
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. :paramtype file_attributes:~azure.storage.fileshare.NTFSAttributes or str :keyword file_creation_time: Creation time for the file. :paramtype file_creation_time:~datetime.datetime or str :keyword file_last_write_time: Last write time for the file. :paramtype file_last_write_time:~datetime.datetime or str :keyword file_change_time: 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'.
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. param Any data: Content of the file. param int length: Length of the file in bytes. Specify its maximum size, up to 1 TiB. param file_attributes: 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. type file_attributes: str or ~azure.storage.fileshare.NTFSAttributes param file_creation_time: Creation time for the file Default value: Now. type file_creation_time: str or ~datetime.datetime param file_last_write_time: Last write time for the file Default value: Now. type file_last_write_time: str or ~datetime.datetime param file_permission: 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. type file_permission: str param permission_key: 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. type permission_key: str
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: Union[str, FileProperties], **kwargs: Any) -> None

Parameters

copy_id: str or FileProperties

Required

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

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

The timeout parameter is expressed in seconds.

Return type

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: Optional[str] = None, **kwargs: Any) -> azure.storage.fileshare._lease.ShareLeaseClient

Parameters

lease_id: str

Required

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.

timeout: int

The timeout parameter is expressed in seconds.

Returns

A ShareLeaseClient object.

Return type

ShareLeaseClient

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) -> Dict[str, Any]

Parameters

offset: int

Required

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

length: int

Required

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

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

The timeout parameter is expressed in seconds.

Returns

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

Return type

<xref:Dict>[str, <xref:Any>]

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]

Parameters

timeout: int

The timeout parameter is expressed in seconds.

Returns

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.

Return type

dict[str, int]

close_handle

Close an open file handle.

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

Parameters

handle: str or Handle

Required

A specific handle to close.

timeout: int

The timeout parameter is expressed in seconds.

Returns

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.

Return type

dict[str, int]

create_file

Creates a new file.

Note that it only initializes the file with no content.

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

Parameters

size: int

Required

Specifies the maximum size for the file, up to 1 TB.

file_attributes: str or NTFSAttributes

Required

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: str or datetime

Required

Creation time for the file Default value: Now.

file_last_write_time: str or datetime

Required

Last write time for the file Default value: Now.

file_permission: str

Required

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: str

Required

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.

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: dict(<xref: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

The timeout parameter is expressed in seconds.

Returns

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

Return type

dict(str, <xref:Any>)

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

Parameters

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

The timeout parameter is expressed in seconds.

Return type

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: Optional[int] = None, length: Optional[int] = None, **kwargs: Any) -> azure.storage.fileshare._download.StorageStreamDownloader

Parameters

offset: int

Required

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

length: int

Required

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

max_concurrency: int

Maximum number of parallel connections to use.

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: <xref: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

The timeout parameter is expressed in seconds.

Returns

A streaming object (StorageStreamDownloader)

Return type

<xref:azure.storage.fileshare.StorageStreamDownloader>

Examples

Download a file.


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

from_connection_string

Create ShareFileClient from a Connection String.

from_connection_string(conn_str: str, share_name: str, file_path: str, snapshot: Optional[Union[str, Dict[str, Any]]] = None, credential: Optional[Any] = None, **kwargs: Any) -> azure.storage.fileshare._file_client.ShareFileClient

Parameters

conn_str: str

Required

A connection string to an Azure Storage account.

share_name: str

Required

The name of the share.

file_path: str

Required

The file path.

snapshot: str

Required

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

credential

default value: None

credential

default value: None

Returns

A File client.

Return type

ShareFileClient

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: Optional[Union[str, Dict[str, Any]]] = None, credential: Optional[Any] = None, **kwargs: Any) -> azure.storage.fileshare._file_client.ShareFileClient

Parameters

file_url: str

Required

The full URI to the file.

snapshot: str

Required

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

credential

default value: None

credential

default value: None

Returns

A File client.

Return type

ShareFileClient

get_file_properties

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

get_file_properties(**kwargs: Any) -> FileProperties

Parameters

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

The timeout parameter is expressed in seconds.

Returns

FileProperties

Return type

FileProperties

get_ranges

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

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

Parameters

offset: int

Required

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

length: int

Required

Number of bytes to use over which to get ranges.

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

The timeout parameter is expressed in seconds.

Returns

A list of valid ranges.

Return type

<xref:List>[dict[str, int]]

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: Union[str, Dict[str, Any]], offset: Optional[int] = None, length: Optional[int] = None, **kwargs: Any) -> Tuple[List[Dict[str, int]], List[Dict[str, int]]]

Parameters

offset: int

Required

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

length: int

default value: None

Number of bytes to use over which to get ranges.

previous_sharesnapshot: str

default value: None

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.

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

The timeout parameter is expressed in seconds.

Returns

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.

Return type

tuple(list(dict(str, str), list(dict(str, str))

list_handles

Lists handles for file.

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

Parameters

timeout: int

The timeout parameter is expressed in seconds.

Returns

An auto-paging iterable of HandleItem

Return type

ItemPaged[HandleItem]

rename_file

Rename the source file.

:paramtype file_attributes:~azure.storage.fileshare.NTFSAttributes or str :keyword file_creation_time:

Creation time for the file.

:paramtype file_creation_time:~datetime.datetime or str :keyword file_last_write_time:

Last write time for the file.

:paramtype file_last_write_time:~datetime.datetime or str :keyword file_change_time:

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'.

rename_file(new_name: str, **kwargs: Any) -> azure.storage.fileshare._file_client.ShareFileClient

Parameters

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: <xref:Dict>[<xref: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

The new File Client.

Return type

ShareFileClient

resize_file

Resizes a file to the specified size.

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

Parameters

size: int

Required

Size to resize file to (in bytes)

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

The timeout parameter is expressed in seconds.

Returns

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

Return type

<xref:Dict>[str, <xref:Any>]

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: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]

Parameters

metadata: dict(str, str)

Required

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

The timeout parameter is expressed in seconds.

Returns

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

Return type

dict(str, <xref:Any>)

set_http_headers

Sets HTTP headers on the file.

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

Parameters

content_settings: ContentSettings

Required

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

file_attributes: str or NTFSAttributes

Required

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: str or datetime

Required

Creation time for the file Default value: Preserve.

file_last_write_time: str or datetime

Required

Last write time for the file Default value: Preserve.

file_permission: str

Required

permission_key: str

Required

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.

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

The timeout parameter is expressed in seconds.

Returns

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

Return type

dict(str, <xref:Any>)

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) -> Any

Parameters

source_url: str

Required

Specifies the URL of the source file.

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_attributes: str or 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

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

The timeout parameter is expressed in seconds.

Return type

dict(str, <xref:Any>)

Examples

Copy a file from a URL


   destination_file.start_copy_from_url(source_url=source_url)

upload_file

Uploads a new file.

param Any data: Content of the file.

param int length: Length of the file in bytes. Specify its maximum size, up to 1 TiB.

param file_attributes: 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.

type file_attributes: str or ~azure.storage.fileshare.NTFSAttributes

param file_creation_time: Creation time for the file Default value: Now.

type file_creation_time: str or ~datetime.datetime

param file_last_write_time: Last write time for the file Default value: Now.

type file_last_write_time: str or ~datetime.datetime

param file_permission: 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.

type file_permission: str

param permission_key: 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.

type permission_key: str

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

Parameters

file_change_time

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'.

paramtype file_change_time: str or ~datetime.datetime

keyword dict(str,str) metadata: Name-value pairs associated with the file as metadata.

keyword ~azure.storage.fileshare.ContentSettings content_settings: ContentSettings object used to set file properties. Used to set content type, encoding, language, disposition, md5, and cache control.

keyword bool validate_content: 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.

keyword int max_concurrency: Maximum number of parallel connections to use.

keyword lease: 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.

paramtype lease: ~azure.storage.fileshare.ShareLeaseClient or str

keyword progress_hook: 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.

paramtype progress_hook: Callable[[int, Optional[int]], None]

keyword int timeout: The timeout parameter is expressed in seconds.

keyword str encoding: Defaults to UTF-8.

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

rtype: dict(str, Any)

Example: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) -> Dict[str, Any]

Parameters

data: bytes

Required

The data to upload.

offset: int

Required

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

length: int

Required

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

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: <xref:Literal>[<xref:"preserve">, <xref:"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

The timeout parameter is expressed in seconds.

encoding: str

Defaults to UTF-8.

Returns

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

Return type

<xref:Dict>[str, <xref:Any>]

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

offset: int

Required

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

length: int

Required

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

source_url: str

Required

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: int

Required

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).

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

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: <xref:Literal>[<xref:"preserve">, <xref:"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

The timeout parameter is expressed in seconds.

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.