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.objectazure.storage.fileshare._shared.base_client_async.AsyncStorageAccountHostsMixinShareFileClientazure.storage.fileshare._shared.base_client.StorageAccountHostsMixinazure.storage.fileshare._file_client.ShareFileClientShareFileClient
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
The copy operation to abort. This can be either an ID, or an instance of FileProperties.
Return type
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
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
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
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
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
close_handle
Close an open file handle.
close_handle(handle, **kwargs)
Parameters
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
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
Specifies the maximum size for the file, up to 1 TB.
- file_attributes
- 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
- str or datetime.datetime
Creation time for the file Default value: Now.
- file_last_write_time
- str or datetime.datetime
Last write time for the file Default value: Now.
- file_permission
- 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
- 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.
Returns
File-updated property dict (Etag and last modified).
Return type
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
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
Start of byte range to use for downloading a section of the file. Must be set if length is provided.
- length
- int
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
Specifies the start offset of bytes over which to get ranges.
- length
- int
Number of bytes to use over which to get ranges.
Returns
A list of valid ranges.
Return type
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
Size to resize file to (in bytes)
Returns
File-updated property dict (Etag and last modified).
Return type
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)
Name-value pairs associated with the file as metadata.
Returns
File-updated property dict (Etag and last modified).
Return type
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
ContentSettings object used to set file properties. Used to set content type, encoding, language, disposition, md5, and cache control.
- file_attributes
- 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
- str or datetime.datetime
Creation time for the file Default value: Preserve.
- file_last_write_time
- str or datetime.datetime
Last write time for the file Default value: Preserve.
- file_permission
- 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
- 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.
Returns
File-updated property dict (Etag and last modified).
Return type
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
Specifies the URL of the source file.
Return type
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
Content of the file.
- length
- int
Length of the file in bytes. Specify its maximum size, up to 1 TiB.
- file_attributes
- 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
- str or datetime.datetime
Creation time for the file Default value: Now.
- file_last_write_time
- str or datetime.datetime
Last write time for the file Default value: Now.
- file_permission
- 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
- 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.
Returns
File-updated property dict (Etag and last modified).
Return type
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
The data to upload.
- offset
- 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
- int
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
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
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
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
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
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).