ShareFileClient class

Definition

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

ShareFileClient(account_url, share_name, file_path, snapshot=None, credential=None, **kwargs)
Inheritance
builtins.object
azure.storage.fileshare._shared.base_client_async.AsyncStorageAccountHostsMixin
ShareFileClient
azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin
azure.storage.fileshare._file_client.ShareFileClient
ShareFileClient

Parameters

account_url
str

The URI to the storage account. In order to create a client given the full URI to the file, use the <xref:azure.storage.fileshare.aio.from_file_url> classmethod.

share_name
str

The name of the share for the file.

file_path
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 <xref:ShareClient.create_snapshot>.

credential

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 or an account shared access key.

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 a stream with automatic chunking.

get_file_properties

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

get_ranges

Returns the list of valid ranges of a file.

list_handles

Lists handles for 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, **kwargs)

Parameters

copy_id
str or FileProperties
Required

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

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=None, **kwargs)

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.

Returns

A ShareLeaseClient object.

Return type

clear_range

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

clear_range(offset, length, **kwargs)

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.

Returns

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

Return type

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

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, **kwargs)

Parameters

handle
str or Handle
Required

A specific handle to close.

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, file_attributes='none', file_creation_time='now', file_last_write_time='now', file_permission=None, permission_key=None, **kwargs)

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.datetime
Required

Creation time for the file Default value: Now.

file_last_write_time
str or datetime.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.

Returns

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

Return type

dict(str, Any)

Examples

Create a file.


   # Create and allocate bytes for the file (no content added yet)
   await 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)

Return type

None

Examples

Delete a file.


   await my_file.delete_file()

download_file

Downloads a file to a stream with automatic chunking.

download_file(offset=None, length=None, **kwargs)

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.

Returns

A iterable data generator (stream)

Examples

Download a file.


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

get_file_properties

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

get_file_properties(**kwargs)

Returns

FileProperties

Return type

get_ranges

Returns the list of valid ranges of a file.

get_ranges(offset=None, length=None, **kwargs)

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.

Returns

A list of valid ranges.

Return type

List[dict[str, int]]

list_handles

Lists handles for file.

list_handles(**kwargs)

Returns

An auto-paging iterable of HandleItem

Return type

resize_file

Resizes a file to the specified size.

resize_file(size, **kwargs)

Parameters

size
int
Required

Size to resize file to (in bytes)

Returns

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

Return type

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

Parameters

metadata
dict(str, str)
Required

Name-value pairs associated with the file as metadata.

Returns

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

Return type

dict(str, Any)

set_http_headers

Sets HTTP headers on the file.

set_http_headers(content_settings, file_attributes='preserve', file_creation_time='preserve', file_last_write_time='preserve', file_permission=None, permission_key=None, **kwargs)

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.datetime
Required

Creation time for the file Default value: Preserve.

file_last_write_time
str or datetime.datetime
Required

Last write time for the file Default value: Preserve.

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.

Returns

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

Return type

dict(str, 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, **kwargs)

Parameters

source_url
str
Required

Specifies the URL of the source file.

Return type

dict(str, Any)

Examples

Copy a file from a URL


   await destination_file.start_copy_from_url(source_url=source_url)

upload_file

Uploads a new file.

upload_file(data, length=None, file_attributes='none', file_creation_time='now', file_last_write_time='now', file_permission=None, permission_key=None, **kwargs)

Parameters

data
Any
Required

Content of the file.

length
int
Required

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

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.datetime
Required

Creation time for the file Default value: Now.

file_last_write_time
str or datetime.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.

Returns

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

Return type

dict(str, Any)

Examples

Upload a file.


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

upload_range

Upload a range of bytes to a file.

upload_range(data, offset, length, **kwargs)

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.

Returns

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

Return type

Dict[str, 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, offset, length, source_offset, **kwargs)

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