FileService Class
The Server Message Block (SMB) protocol is the preferred file share protocol used on premise today. The Microsoft Azure File service enables customers to leverage the availability and scalability of Azure's Cloud Infrastructure as a Service (IaaS) SMB without having to rewrite SMB client applications.
The Azure File service also offers a compelling alternative to traditional Direct Attached Storage (DAS) and Storage Area Network (SAN) solutions, which are often complex and expensive to install, configure, and operate.
- Inheritance
-
FileService
Constructor
FileService(account_name=None, account_key=None, sas_token=None, protocol='https', endpoint_suffix='core.windows.net', request_session=None, connection_string=None, socket_timeout=None)Parameters
| Name | Description |
|---|---|
|
account_name
|
The storage account name. This is used to authenticate requests signed with an account key and to construct the storage endpoint. It is required unless a connection string is given. Default value: None
|
|
account_key
|
The storage account key. This is used for shared key authentication. Default value: None
|
|
sas_token
|
A shared access signature token to use to authenticate requests instead of the account key. If account key and sas token are both specified, account key will be used to sign. Default value: None
|
|
protocol
|
The protocol to use for requests. Defaults to https. Default value: https
|
|
endpoint_suffix
|
The host base component of the url, minus the account name. Defaults to Azure (core.windows.net). Override this to use the China cloud (core.chinacloudapi.cn). Default value: core.windows.net
|
|
request_session
|
<xref:requests.Session>
The session object to use for http requests. Default value: None
|
|
connection_string
|
If specified, this will override all other parameters besides request session. See http://azure.microsoft.com/en-us/documentation/articles/storage-configure-connection-string/ for the connection string format. Default value: None
|
|
socket_timeout
|
If specified, this will override the default socket timeout. The timeout specified is in seconds. See DEFAULT_SOCKET_TIMEOUT in _constants.py for the default value. Default value: None
|
Variables
| Name | Description |
|---|---|
|
MAX_SINGLE_GET_SIZE
|
The size of the first range get performed by get_file_to_* methods if max_connections is greater than 1. Less data will be returned if the file is smaller than this. |
|
MAX_CHUNK_GET_SIZE
|
The size of subsequent range gets performed by get_file_to_* methods if max_connections is greater than 1 and the file is larger than MAX_SINGLE_GET_SIZE. Less data will be returned if the remainder of the file is smaller than this. If this is set to larger than 4MB, content_validation will throw an error if enabled. However, if content_validation is not desired a size greater than 4MB may be optimal. Setting this below 4MB is not recommended. |
|
MAX_RANGE_SIZE
|
The size of the ranges put by create_file_from_* methods. Smaller ranges may be put if there is less data provided. The maximum range size the service supports is 4MB. |
Methods
| abort_copy_file |
Aborts a pending copy_file operation, and leaves a destination file with zero length and full metadata. |
| clear_range |
Clears the specified range and releases the space used in storage for that range. |
| close_handles |
Returns a generator to close opened handles on a directory or a file under the specified share. The generator will lazily follow the continuation tokens returned by the service and stop when all handles have been closed. The yielded values represent the number of handles that were closed in each transaction. |
| copy_file |
Copies a file asynchronously. This operation returns a copy operation properties object, including a copy ID you can use to check or abort the copy operation. The File service copies files on a best-effort basis. If the destination file exists, it will be overwritten. The destination file cannot be modified while the copy operation is in progress. |
| create_directory |
Creates a new directory under the specified share or parent directory. If the directory with the same name already exists, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_on_exists. |
| create_file |
Creates a new file. See create_file_from_* for high level functions that handle the creation and upload of large files with automatic chunking and progress notifications. |
| create_file_from_bytes |
Creates a new file from an array of bytes, or updates the content of an existing file, with automatic chunking and progress notifications. |
| create_file_from_path |
Creates a new azure file from a local file path, or updates the content of an existing file, with automatic chunking and progress notifications. |
| create_file_from_stream |
Creates a new file from a file/stream, or updates the content of an existing file, with automatic chunking and progress notifications. |
| create_file_from_text |
Creates a new file from str/unicode, or updates the content of an existing file, with automatic chunking and progress notifications. |
| create_permission_for_share |
Create a permission(a security descriptor) at the share level. This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key. :returns a file permission key :rtype str |
| create_share |
Creates a new share under the specified account. If the share with the same name already exists, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_on_exists. |
| delete_directory |
Deletes the specified empty directory. Note that the directory must be empty before it can be deleted. Attempting to delete directories that are not empty will fail. If the directory does not exist, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_not_exist. |
| delete_file |
Marks the specified file for deletion. The file is later deleted during garbage collection. |
| delete_share |
Marks the specified share for deletion. If the share does not exist, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_not_exist. |
| exists |
Returns a boolean indicating whether the share exists if only share name is given. If directory_name is specificed a boolean will be returned indicating if the directory exists. If file_name is specified as well, a boolean will be returned indicating if the file exists. |
| extract_date_and_request_id | |
| generate_account_shared_access_signature |
Generates a shared access signature for the file service. Use the returned signature with the sas_token parameter of the FileService. |
| generate_file_shared_access_signature |
Generates a shared access signature for the file. Use the returned signature with the sas_token parameter of FileService. |
| generate_share_shared_access_signature |
Generates a shared access signature for the share. Use the returned signature with the sas_token parameter of FileService. |
| get_directory_metadata |
Returns all user-defined metadata for the specified directory. |
| get_directory_properties |
Returns all user-defined metadata and system properties for the specified directory. The data returned does not include the directory's list of files. |
| get_file_metadata |
Returns all user-defined metadata for the specified file. |
| get_file_properties |
Returns all user-defined metadata, standard HTTP properties, and system properties for the file. Returns an instance of File with FileProperties and a metadata dict. |
| get_file_service_properties |
Gets the properties of a storage account's File service, including Azure Storage Analytics. |
| get_file_to_bytes |
Downloads a file as an array of bytes, with automatic chunking and progress notifications. Returns an instance of File with properties, metadata, and content. |
| get_file_to_path |
Downloads a file to a file path, with automatic chunking and progress notifications. Returns an instance of File with properties and metadata. |
| get_file_to_stream |
Downloads a file to a stream, with automatic chunking and progress notifications. Returns an instance of File with properties and metadata. |
| get_file_to_text |
Downloads a file as unicode text, with automatic chunking and progress notifications. Returns an instance of File with properties, metadata, and content. |
| get_permission_for_share |
Create a permission(a security descriptor) at the share level. This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key. :returns a file permission(a portable SDDL) :rtype str |
| get_share_acl |
Gets the permissions for the specified share. |
| get_share_metadata |
Returns all user-defined metadata for the specified share. |
| get_share_properties |
Returns all user-defined metadata and system properties for the specified share. The data returned does not include the shares's list of files or directories. |
| get_share_stats |
Gets the approximate size of the data stored on the share, rounded up to the nearest gigabyte. Note that this value may not include all recently created or recently re-sized files. |
| get_share_stats_in_bytes |
Gets the approximate size of the data stored on the share in bytes. Note that this value may not include all recently created or recently re-sized files. |
| list_directories_and_files |
Returns a generator to list the directories and files under the specified share. The generator will lazily follow the continuation tokens returned by the service and stop when all directories and files have been returned or num_results is reached. If num_results is specified and the share has more than that number of files and directories, the generator will have a populated next_marker field once it finishes. This marker can be used to create a new generator if more results are desired. |
| list_handles |
Returns a generator to list opened handles on a directory or a file under the specified share. The generator will lazily follow the continuation tokens returned by the service and stop when all handles have been returned or num_results is reached. If num_results is specified and the share has more than that number of files and directories, the generator will have a populated next_marker field once it finishes. This marker can be used to create a new generator if more results are desired. |
| list_ranges |
Retrieves the valid ranges for a file. |
| list_shares |
Returns a generator to list the shares under the specified account. The generator will lazily follow the continuation tokens returned by the service and stop when all shares have been returned or num_results is reached. If num_results is specified and the account has more than that number of shares, the generator will have a populated next_marker field once it finishes. This marker can be used to create a new generator if more results are desired. |
| make_file_url |
Creates the url to access a file. |
| resize_file |
Resizes a file to the specified size. If the specified byte value is less than the current size of the file, then all ranges above the specified byte value are cleared. |
| set_directory_metadata |
Sets one or more user-defined name-value pairs for the specified directory. Each call to this operation replaces all existing metadata attached to the directory. To remove all metadata from the directory, call this operation with no metadata dict. |
| set_directory_properties | |
| set_file_metadata |
Sets user-defined metadata for the specified file as one or more name-value pairs. |
| set_file_properties |
Sets system properties on the file. If one property is set for the content_settings, all properties will be overriden. |
| set_file_service_properties |
Sets the properties of a storage account's File service, including Azure Storage Analytics. If an element (ex HourMetrics) is left as None, the existing settings on the service for that functionality are preserved. |
| set_proxy |
Sets the proxy server host and port for the HTTP CONNECT Tunnelling. |
| set_share_acl |
Sets the permissions for the specified share or stored access policies that may be used with Shared Access Signatures. |
| set_share_metadata |
Sets one or more user-defined name-value pairs for the specified share. Each call to this operation replaces all existing metadata attached to the share. To remove all metadata from the share, call this operation with no metadata dict. |
| set_share_properties |
Sets service-defined properties for the specified share. |
| snapshot_share |
Creates a snapshot of an existing share under the specified account. |
| update_range |
Writes the bytes specified by the request body into the specified range. |
| update_range_from_file_url |
Writes the bytes from one Azure File endpoint into the specified range of another Azure File endpoint. |
abort_copy_file
Aborts a pending copy_file operation, and leaves a destination file with zero length and full metadata.
abort_copy_file(share_name, directory_name, file_name, copy_id, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of destination share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of destination file. |
|
copy_id
Required
|
Copy identifier provided in the copy.id of the original copy_file operation. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
clear_range
Clears the specified range and releases the space used in storage for that range.
clear_range(share_name, directory_name, file_name, start_range, end_range, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
start_range
Required
|
Start of byte range to use for clearing a section of the file. The range can be up to 4 MB in size. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. |
|
end_range
Required
|
End of byte range to use for clearing a section of the file. The range can be up to 4 MB in size. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
close_handles
Returns a generator to close opened handles on a directory or a file under the specified share. The generator will lazily follow the continuation tokens returned by the service and stop when all handles have been closed. The yielded values represent the number of handles that were closed in each transaction.
close_handles(share_name, directory_name=None, file_name=None, recursive=None, handle_id=None, marker=None, snapshot=None, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
|
The path to the directory. Default value: None
|
|
file_name
|
Name of existing file. Default value: None
|
|
recursive
|
Boolean that specifies if operation should apply to the directory specified in the URI, its files, its subdirectories and their files. Default value: None
|
|
handle_id
|
Required. Specifies handle ID opened on the file or directory to be closed. Astrix ('*') is a wildcard that specifies all handles. Default value: None
|
|
marker
|
An opaque continuation token. This value can be retrieved from the next_marker field of a previous generator object if it has not finished closing handles. If specified, this generator will begin closing handles from the point where the previous generator stopped. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
copy_file
Copies a file asynchronously. This operation returns a copy operation properties object, including a copy ID you can use to check or abort the copy operation. The File service copies files on a best-effort basis.
If the destination file exists, it will be overwritten. The destination file cannot be modified while the copy operation is in progress.
copy_file(share_name, directory_name, file_name, copy_source, metadata=None, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of the destination share. The share must exist. |
|
directory_name
Required
|
Name of the destination directory. The directory must exist. |
|
file_name
Required
|
Name of the destination file. If the destination file exists, it will be overwritten. Otherwise, it will be created. |
|
copy_source
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 |
|
metadata
|
Name-value pairs associated with the file as metadata. If no name-value pairs are specified, the operation will copy the metadata from the source blob or file to the destination file. If one or more name-value pairs are specified, the destination file is created with the specified metadata, and the metadata is not copied from the source blob or file. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Returns
| Type | Description |
|---|---|
|
Copy operation properties such as status, source, and ID. |
create_directory
Creates a new directory under the specified share or parent directory. If the directory with the same name already exists, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_on_exists.
create_directory(share_name, directory_name, metadata=None, fail_on_exist=False, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
Name of directory to create, including the path to the parent directory. |
|
metadata
|
A dict with name_value pairs to associate with the share as metadata. Example:{'Category':'test'} Default value: None
|
|
fail_on_exist
|
specify whether to throw an exception when the directory exists. False by default. Default value: False
|
|
file_permission
|
File permission, a portable SDDL Default value: None
|
|
smb_properties
|
Sets the SMB related file properties |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Returns
| Type | Description |
|---|---|
|
True if directory is created, False if directory already exists. |
create_file
Creates a new file.
See create_file_from_* for high level functions that handle the creation and upload of large files with automatic chunking and progress notifications.
create_file(share_name, directory_name, file_name, content_length, content_settings=None, metadata=None, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of file to create or update. |
|
content_length
Required
|
Length of the file in bytes. |
|
content_settings
|
ContentSettings object used to set file properties. Default value: None
|
|
metadata
|
Name-value pairs associated with the file as metadata. Default value: None
|
|
file_permission
|
File permission, a portable SDDL Default value: None
|
|
smb_properties
|
Sets the SMB related file properties |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
create_file_from_bytes
Creates a new file from an array of bytes, or updates the content of an existing file, with automatic chunking and progress notifications.
create_file_from_bytes(share_name, directory_name, file_name, file, index=0, count=None, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of file to create or update. |
|
file
Required
|
Content of file as an array of bytes. |
|
index
|
Start index in the array of bytes. Default value: 0
|
|
count
|
Number of bytes to upload. Set to None or negative value to upload all bytes starting from index. Default value: None
|
|
content_settings
|
ContentSettings object used to set file properties. Default value: None
|
|
metadata
|
Name-value pairs associated with the file as metadata. Default value: None
|
|
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. Default value: False
|
|
progress_callback
|
<xref:func>(<xref:current>, <xref:total>)
Callback for progress with signature function(current, total) where current is the number of bytes transfered so far and total is the size of the file, or None if the total size is unknown. Default value: None
|
|
max_connections
|
Maximum number of parallel connections to use. Default value: 2
|
|
file_permission
|
File permission, a portable SDDL Default value: None
|
|
smb_properties
|
Sets the SMB related file properties |
|
timeout
|
The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually. Default value: None
|
create_file_from_path
Creates a new azure file from a local file path, or updates the content of an existing file, with automatic chunking and progress notifications.
create_file_from_path(share_name, directory_name, file_name, local_file_path, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of file to create or update. |
|
local_file_path
Required
|
Path of the local file to upload as the file content. |
|
content_settings
|
ContentSettings object used for setting file properties. Default value: None
|
|
metadata
|
Name-value pairs associated with the file as metadata. Default value: None
|
|
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. Default value: False
|
|
progress_callback
|
<xref:func>(<xref:current>, <xref:total>)
Callback for progress with signature function(current, total) where current is the number of bytes transfered so far and total is the size of the file, or None if the total size is unknown. Default value: None
|
|
max_connections
|
Maximum number of parallel connections to use. Default value: 2
|
|
file_permission
|
File permission, a portable SDDL Default value: None
|
|
smb_properties
|
Sets the SMB related file properties |
|
timeout
|
The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually. Default value: None
|
create_file_from_stream
Creates a new file from a file/stream, or updates the content of an existing file, with automatic chunking and progress notifications.
create_file_from_stream(share_name, directory_name, file_name, stream, count, content_settings=None, metadata=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of file to create or update. |
|
stream
Required
|
Opened file/stream to upload as the file content. |
|
count
Required
|
Number of bytes to read from the stream. This is required, a file cannot be created if the count is unknown. |
|
content_settings
|
ContentSettings object used to set file properties. Default value: None
|
|
metadata
|
Name-value pairs associated with the file as metadata. Default value: None
|
|
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. Default value: False
|
|
progress_callback
|
<xref:func>(<xref:current>, <xref:total>)
Callback for progress with signature function(current, total) where current is the number of bytes transfered so far and total is the size of the file, or None if the total size is unknown. Default value: None
|
|
max_connections
|
Maximum number of parallel connections to use. Note that parallel upload requires the stream to be seekable. Default value: 2
|
|
file_permission
|
File permission, a portable SDDL Default value: None
|
|
smb_properties
|
Sets the SMB related file properties |
|
timeout
|
The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually. Default value: None
|
create_file_from_text
Creates a new file from str/unicode, or updates the content of an existing file, with automatic chunking and progress notifications.
create_file_from_text(share_name, directory_name, file_name, text, encoding='utf-8', content_settings=None, metadata=None, validate_content=False, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of file to create or update. |
|
text
Required
|
Text to upload to the file. |
|
encoding
|
Python encoding to use to convert the text to bytes. Default value: utf-8
|
|
content_settings
|
ContentSettings object used to set file properties. Default value: None
|
|
metadata
|
Name-value pairs associated with the file as metadata. Default value: None
|
|
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. Default value: False
|
|
file_permission
|
File permission, a portable SDDL Default value: None
|
|
smb_properties
|
Sets the SMB related file properties |
|
timeout
|
The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually. Default value: None
|
create_permission_for_share
Create a permission(a security descriptor) at the share level. This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key.
:returns a file permission key :rtype str
create_permission_for_share(share_name, file_permission, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of share. |
|
file_permission
Required
|
File permission, a Portable SDDL |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
create_share
Creates a new share under the specified account. If the share with the same name already exists, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_on_exists.
create_share(share_name, metadata=None, quota=None, fail_on_exist=False, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of share to create. |
|
metadata
|
A dict with name_value pairs to associate with the share as metadata. Example:{'Category':'test'} Default value: None
|
|
quota
|
Specifies the maximum size of the share, in gigabytes. Must be greater than 0, and less than or equal to 5TB (5120). Default value: None
|
|
fail_on_exist
|
Specify whether to throw an exception when the share exists. False by default. Default value: False
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Returns
| Type | Description |
|---|---|
|
True if share is created, False if share already exists. |
delete_directory
Deletes the specified empty directory. Note that the directory must be empty before it can be deleted. Attempting to delete directories that are not empty will fail.
If the directory does not exist, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_not_exist.
delete_directory(share_name, directory_name, fail_not_exist=False, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
Name of directory to delete, including the path to the parent directory. |
|
fail_not_exist
|
Specify whether to throw an exception when the directory doesn't exist. Default value: False
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Returns
| Type | Description |
|---|---|
|
True if directory is deleted, False otherwise. |
delete_file
Marks the specified file for deletion. The file is later deleted during garbage collection.
delete_file(share_name, directory_name, file_name, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
delete_share
Marks the specified share for deletion. If the share does not exist, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_not_exist.
delete_share(share_name, fail_not_exist=False, timeout=None, snapshot=None, delete_snapshots=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of share to delete. |
|
fail_not_exist
|
Specify whether to throw an exception when the share doesn't exist. False by default. Default value: False
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Specify this argument to delete a specific snapshot only. delete_snapshots must be None if this is specified. Default value: None
|
|
delete_snapshots
|
To delete a share that has snapshots, this must be specified as DeleteSnapshot.Include. Default value: None
|
Returns
| Type | Description |
|---|---|
|
True if share is deleted, False share doesn't exist. |
exists
Returns a boolean indicating whether the share exists if only share name is given. If directory_name is specificed a boolean will be returned indicating if the directory exists. If file_name is specified as well, a boolean will be returned indicating if the file exists.
exists(share_name, directory_name=None, file_name=None, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of a share. |
|
directory_name
|
The path to a directory. Default value: None
|
|
file_name
|
Name of a file. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A boolean indicating whether the resource exists. |
extract_date_and_request_id
static extract_date_and_request_id(retry_context)Parameters
| Name | Description |
|---|---|
|
retry_context
Required
|
|
generate_account_shared_access_signature
Generates a shared access signature for the file service. Use the returned signature with the sas_token parameter of the FileService.
generate_account_shared_access_signature(resource_types, permission, expiry, start=None, ip=None, protocol=None)Parameters
| Name | Description |
|---|---|
|
resource_types
Required
|
<xref:ResourceTypes>
Specifies the resource types that are accessible with the account SAS. |
|
permission
Required
|
<xref:AccountPermissions>
The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. |
|
expiry
Required
|
The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. |
|
start
|
The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Default value: None
|
|
ip
|
Specifies an IP address or a range of IP addresses from which to accept requests. If the IP address from which the request originates does not match the IP address or address range specified on the SAS token, the request is not authenticated. For example, specifying sip=168.1.5.65 or sip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses. Default value: None
|
|
protocol
|
Specifies the protocol permitted for a request made. Possible values are both HTTPS and HTTP (https,http) or HTTPS only (https). The default value is https,http. Note that HTTP only is not a permitted value. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A Shared Access Signature (sas) token. |
generate_file_shared_access_signature
Generates a shared access signature for the file. Use the returned signature with the sas_token parameter of FileService.
generate_file_shared_access_signature(share_name, directory_name=None, file_name=None, permission=None, expiry=None, start=None, id=None, ip=None, protocol=None, cache_control=None, content_disposition=None, content_encoding=None, content_language=None, content_type=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of share. |
|
directory_name
|
Name of directory. SAS tokens cannot be created for directories, so this parameter should only be present if file_name is provided. Default value: None
|
|
file_name
|
Name of file. Default value: None
|
|
permission
|
The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Permissions must be ordered read, create, write, delete, list. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Default value: None
|
|
expiry
|
The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Default value: None
|
|
start
|
The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Default value: None
|
|
id
|
A unique value up to 64 characters in length that correlates to a stored access policy. To create a stored access policy, use set_file_service_properties. Default value: None
|
|
ip
|
Specifies an IP address or a range of IP addresses from which to accept requests. If the IP address from which the request originates does not match the IP address or address range specified on the SAS token, the request is not authenticated. For example, specifying sip=168.1.5.65 or sip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses. Default value: None
|
|
protocol
|
Specifies the protocol permitted for a request made. Possible values are both HTTPS and HTTP (https,http) or HTTPS only (https). The default value is https,http. Note that HTTP only is not a permitted value. Default value: None
|
|
cache_control
|
Response header value for Cache-Control when resource is accessed using this shared access signature. Default value: None
|
|
content_disposition
|
Response header value for Content-Disposition when resource is accessed using this shared access signature. Default value: None
|
|
content_encoding
|
Response header value for Content-Encoding when resource is accessed using this shared access signature. Default value: None
|
|
content_language
|
Response header value for Content-Language when resource is accessed using this shared access signature. Default value: None
|
|
content_type
|
Response header value for Content-Type when resource is accessed using this shared access signature. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A Shared Access Signature (sas) token. |
generate_share_shared_access_signature
Generates a shared access signature for the share. Use the returned signature with the sas_token parameter of FileService.
generate_share_shared_access_signature(share_name, permission=None, expiry=None, start=None, id=None, ip=None, protocol=None, cache_control=None, content_disposition=None, content_encoding=None, content_language=None, content_type=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of share. |
|
permission
|
The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Permissions must be ordered read, create, write, delete, list. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Default value: None
|
|
expiry
|
The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Default value: None
|
|
start
|
The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Default value: None
|
|
id
|
A unique value up to 64 characters in length that correlates to a stored access policy. To create a stored access policy, use set_share_acl. Default value: None
|
|
ip
|
Specifies an IP address or a range of IP addresses from which to accept requests. If the IP address from which the request originates does not match the IP address or address range specified on the SAS token, the request is not authenticated. For example, specifying sip=168.1.5.65 or sip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses. Default value: None
|
|
protocol
|
Specifies the protocol permitted for a request made. Possible values are both HTTPS and HTTP (https,http) or HTTPS only (https). The default value is https,http. Note that HTTP only is not a permitted value. Default value: None
|
|
cache_control
|
Response header value for Cache-Control when resource is accessed using this shared access signature. Default value: None
|
|
content_disposition
|
Response header value for Content-Disposition when resource is accessed using this shared access signature. Default value: None
|
|
content_encoding
|
Response header value for Content-Encoding when resource is accessed using this shared access signature. Default value: None
|
|
content_language
|
Response header value for Content-Language when resource is accessed using this shared access signature. Default value: None
|
|
content_type
|
Response header value for Content-Type when resource is accessed using this shared access signature. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A Shared Access Signature (sas) token. |
get_directory_metadata
Returns all user-defined metadata for the specified directory.
get_directory_metadata(share_name, directory_name, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A dictionary representing the directory metadata name, value pairs. |
get_directory_properties
Returns all user-defined metadata and system properties for the specified directory. The data returned does not include the directory's list of files.
get_directory_properties(share_name, directory_name, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to an existing directory. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
properties for the specified directory within a directory object. |
get_file_metadata
Returns all user-defined metadata for the specified file.
get_file_metadata(share_name, directory_name, file_name, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A dictionary representing the file metadata name, value pairs. |
get_file_properties
Returns all user-defined metadata, standard HTTP properties, and system properties for the file. Returns an instance of File with FileProperties and a metadata dict.
get_file_properties(share_name, directory_name, file_name, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
a file object including properties and metadata. |
get_file_service_properties
Gets the properties of a storage account's File service, including Azure Storage Analytics.
get_file_service_properties(timeout=None)Parameters
| Name | Description |
|---|---|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Returns
| Type | Description |
|---|---|
|
The file service properties. |
get_file_to_bytes
Downloads a file as an array of bytes, with automatic chunking and progress notifications. Returns an instance of File with properties, metadata, and content.
get_file_to_bytes(share_name, directory_name, file_name, start_range=None, end_range=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
start_range
|
Start of byte range to use for downloading a section of the file. If no end_range is given, all bytes after the start_range will be downloaded. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
end_range
|
End of byte range to use for downloading a section of the file. If end_range is given, start_range must be provided. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
validate_content
|
If set to true, validates an MD5 hash for each retrieved portion of the file. 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 the service will only return transactional MD5s for chunks 4MB or less so the first get request will be of size self.MAX_CHUNK_GET_SIZE instead of self.MAX_SINGLE_GET_SIZE. If self.MAX_CHUNK_GET_SIZE was set to greater than 4MB an error will be thrown. As computing the MD5 takes processing time and more requests will need to be done due to the reduced chunk size there may be some increase in latency. Default value: False
|
|
progress_callback
|
<xref:func>(<xref:current>, <xref:total>)
Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the file if known. Default value: None
|
|
max_connections
|
If set to 2 or greater, an initial get will be done for the first self.MAX_SINGLE_GET_SIZE bytes of the file. If this is the entire file, the method returns at this point. If it is not, it will download the remaining data parallel using the number of threads equal to max_connections. Each chunk will be of size self.MAX_CHUNK_GET_SIZE. If set to 1, a single large get request will be done. This is not generally recommended but available if very few threads should be used, network requests are very expensive, or a non-seekable stream prevents parallel download. This may also be valuable if the file is being concurrently modified to enforce atomicity or if many files are expected to be empty as an extra request is required for empty files if max_connections is greater than 1. Default value: 2
|
|
timeout
|
The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A File with properties, content, and metadata. |
get_file_to_path
Downloads a file to a file path, with automatic chunking and progress notifications. Returns an instance of File with properties and metadata.
get_file_to_path(share_name, directory_name, file_name, file_path, open_mode='wb', start_range=None, end_range=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
file_path
Required
|
Path of file to write to. |
|
open_mode
|
Mode to use when opening the file. Note that specifying append only open_mode prevents parallel download. So, max_connections must be set to 1 if this open_mode is used. Default value: wb
|
|
start_range
|
Start of byte range to use for downloading a section of the file. If no end_range is given, all bytes after the start_range will be downloaded. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
end_range
|
End of byte range to use for downloading a section of the file. If end_range is given, start_range must be provided. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
validate_content
|
If set to true, validates an MD5 hash for each retrieved portion of the file. 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 the service will only return transactional MD5s for chunks 4MB or less so the first get request will be of size self.MAX_CHUNK_GET_SIZE instead of self.MAX_SINGLE_GET_SIZE. If self.MAX_CHUNK_GET_SIZE was set to greater than 4MB an error will be thrown. As computing the MD5 takes processing time and more requests will need to be done due to the reduced chunk size there may be some increase in latency. Default value: False
|
|
progress_callback
|
<xref:func>(<xref:current>, <xref:total>)
Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the file if known. Default value: None
|
|
max_connections
|
If set to 2 or greater, an initial get will be done for the first self.MAX_SINGLE_GET_SIZE bytes of the file. If this is the entire file, the method returns at this point. If it is not, it will download the remaining data parallel using the number of threads equal to max_connections. Each chunk will be of size self.MAX_CHUNK_GET_SIZE. If set to 1, a single large get request will be done. This is not generally recommended but available if very few threads should be used, network requests are very expensive, or a non-seekable stream prevents parallel download. This may also be valuable if the file is being concurrently modified to enforce atomicity or if many files are expected to be empty as an extra request is required for empty files if max_connections is greater than 1. Default value: 2
|
|
timeout
|
The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A File with properties and metadata. |
get_file_to_stream
Downloads a file to a stream, with automatic chunking and progress notifications. Returns an instance of File with properties and metadata.
get_file_to_stream(share_name, directory_name, file_name, stream, start_range=None, end_range=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
stream
Required
|
Opened file/stream to write to. |
|
start_range
|
Start of byte range to use for downloading a section of the file. If no end_range is given, all bytes after the start_range will be downloaded. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
end_range
|
End of byte range to use for downloading a section of the file. If end_range is given, start_range must be provided. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
validate_content
|
If set to true, validates an MD5 hash for each retrieved portion of the file. 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 the service will only return transactional MD5s for chunks 4MB or less so the first get request will be of size self.MAX_CHUNK_GET_SIZE instead of self.MAX_SINGLE_GET_SIZE. If self.MAX_CHUNK_GET_SIZE was set to greater than 4MB an error will be thrown. As computing the MD5 takes processing time and more requests will need to be done due to the reduced chunk size there may be some increase in latency. Default value: False
|
|
progress_callback
|
<xref:func>(<xref:current>, <xref:total>)
Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the file if known. Default value: None
|
|
max_connections
|
If set to 2 or greater, an initial get will be done for the first self.MAX_SINGLE_GET_SIZE bytes of the file. If this is the entire file, the method returns at this point. If it is not, it will download the remaining data parallel using the number of threads equal to max_connections. Each chunk will be of size self.MAX_CHUNK_GET_SIZE. If set to 1, a single large get request will be done. This is not generally recommended but available if very few threads should be used, network requests are very expensive, or a non-seekable stream prevents parallel download. This may also be valuable if the file is being concurrently modified to enforce atomicity or if many files are expected to be empty as an extra request is required for empty files if max_connections is greater than 1. Default value: 2
|
|
timeout
|
The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A File with properties and metadata. |
get_file_to_text
Downloads a file as unicode text, with automatic chunking and progress notifications. Returns an instance of File with properties, metadata, and content.
get_file_to_text(share_name, directory_name, file_name, encoding='utf-8', start_range=None, end_range=None, validate_content=False, progress_callback=None, max_connections=2, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
encoding
|
Python encoding to use when decoding the file data. Default value: utf-8
|
|
start_range
|
Start of byte range to use for downloading a section of the file. If no end_range is given, all bytes after the start_range will be downloaded. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
end_range
|
End of byte range to use for downloading a section of the file. If end_range is given, start_range must be provided. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
validate_content
|
If set to true, validates an MD5 hash for each retrieved portion of the file. 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 the service will only return transactional MD5s for chunks 4MB or less so the first get request will be of size self.MAX_CHUNK_GET_SIZE instead of self.MAX_SINGLE_GET_SIZE. If self.MAX_CHUNK_GET_SIZE was set to greater than 4MB an error will be thrown. As computing the MD5 takes processing time and more requests will need to be done due to the reduced chunk size there may be some increase in latency. Default value: False
|
|
progress_callback
|
<xref:func>(<xref:current>, <xref:total>)
Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the file if known. Default value: None
|
|
max_connections
|
If set to 2 or greater, an initial get will be done for the first self.MAX_SINGLE_GET_SIZE bytes of the file. If this is the entire file, the method returns at this point. If it is not, it will download the remaining data parallel using the number of threads equal to max_connections. Each chunk will be of size self.MAX_CHUNK_GET_SIZE. If set to 1, a single large get request will be done. This is not generally recommended but available if very few threads should be used, network requests are very expensive, or a non-seekable stream prevents parallel download. This may also be valuable if the file is being concurrently modified to enforce atomicity or if many files are expected to be empty as an extra request is required for empty files if max_connections is greater than 1. Default value: 2
|
|
timeout
|
The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A File with properties, content, and metadata. |
get_permission_for_share
Create a permission(a security descriptor) at the share level. This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key.
:returns a file permission(a portable SDDL) :rtype str
get_permission_for_share(share_name, file_permission_key, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of share. |
|
file_permission_key
Required
|
Key of the file permission to retrieve |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
get_share_acl
Gets the permissions for the specified share.
get_share_acl(share_name, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A dictionary of access policies associated with the share. |
get_share_metadata
Returns all user-defined metadata for the specified share.
get_share_metadata(share_name, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A dictionary representing the share metadata name, value pairs. |
get_share_properties
Returns all user-defined metadata and system properties for the specified share. The data returned does not include the shares's list of files or directories.
get_share_properties(share_name, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
A Share that exposes properties and metadata. |
get_share_stats
Gets the approximate size of the data stored on the share, rounded up to the nearest gigabyte.
Note that this value may not include all recently created or recently re-sized files.
get_share_stats(share_name, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Returns
| Type | Description |
|---|---|
|
the approximate size of the data stored on the share. |
get_share_stats_in_bytes
Gets the approximate size of the data stored on the share in bytes.
Note that this value may not include all recently created or recently re-sized files.
get_share_stats_in_bytes(share_name, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Returns
| Type | Description |
|---|---|
|
the approximate size of the data stored on the share. |
list_directories_and_files
Returns a generator to list the directories and files under the specified share. The generator will lazily follow the continuation tokens returned by the service and stop when all directories and files have been returned or num_results is reached.
If num_results is specified and the share has more than that number of files and directories, the generator will have a populated next_marker field once it finishes. This marker can be used to create a new generator if more results are desired.
list_directories_and_files(share_name, directory_name=None, num_results=None, marker=None, timeout=None, prefix=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
|
The path to the directory. Default value: None
|
|
num_results
|
Specifies the maximum number of files to return, including all directory elements. If the request does not specify num_results or specifies a value greater than 5,000, the server will return up to 5,000 items. Setting num_results to a value less than or equal to zero results in error response code 400 (Bad Request). Default value: None
|
|
marker
|
An opaque continuation token. This value can be retrieved from the next_marker field of a previous generator object if num_results was specified and that generator has finished enumerating results. If specified, this generator will begin returning results from the point where the previous generator stopped. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
prefix
|
List only the files and/or directories with the given prefix. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
list_handles
Returns a generator to list opened handles on a directory or a file under the specified share. The generator will lazily follow the continuation tokens returned by the service and stop when all handles have been returned or num_results is reached.
If num_results is specified and the share has more than that number of files and directories, the generator will have a populated next_marker field once it finishes. This marker can be used to create a new generator if more results are desired.
list_handles(share_name, directory_name=None, file_name=None, recursive=None, max_results=None, marker=None, snapshot=None, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
|
The path to the directory. Default value: None
|
|
file_name
|
Name of existing file. Default value: None
|
|
recursive
|
Boolean that specifies if operation should apply to the directory specified in the URI, its files, its subdirectories and their files. Default value: None
|
|
max_results
|
Specifies the maximum number of handles taken on files and/or directories to return. If the request does not specify max_results or specifies a value greater than 5,000, the server will return up to 5,000 items. Setting max_results to a value less than or equal to zero results in error response code 400 (Bad Request). Default value: None
|
|
marker
|
An opaque continuation token. This value can be retrieved from the next_marker field of a previous generator object if max_results was specified and that generator has finished enumerating results. If specified, this generator will begin returning results from the point where the previous generator stopped. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
list_ranges
Retrieves the valid ranges for a file.
list_ranges(share_name, directory_name, file_name, start_range=None, end_range=None, timeout=None, snapshot=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
start_range
|
Specifies the start offset of bytes over which to list ranges. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
end_range
|
Specifies the end offset of bytes over which to list ranges. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
snapshot
|
A string that represents the snapshot version, if applicable. Default value: None
|
Returns
| Type | Description |
|---|---|
|
a list of valid ranges |
list_shares
Returns a generator to list the shares under the specified account. The generator will lazily follow the continuation tokens returned by the service and stop when all shares have been returned or num_results is reached.
If num_results is specified and the account has more than that number of shares, the generator will have a populated next_marker field once it finishes. This marker can be used to create a new generator if more results are desired.
list_shares(prefix=None, marker=None, num_results=None, include_metadata=False, timeout=None, include_snapshots=False)Parameters
| Name | Description |
|---|---|
|
prefix
|
Filters the results to return only shares whose names begin with the specified prefix. Default value: None
|
|
num_results
|
Specifies the maximum number of shares to return. Default value: None
|
|
include_metadata
|
Specifies that share metadata be returned in the response. Default value: False
|
|
marker
|
An opaque continuation token. This value can be retrieved from the next_marker field of a previous generator object if num_results was specified and that generator has finished enumerating results. If specified, this generator will begin returning results from the point where the previous generator stopped. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
|
include_snapshots
|
Specifies that share snapshots be returned in the response. Default value: False
|
make_file_url
Creates the url to access a file.
make_file_url(share_name, directory_name, file_name, protocol=None, sas_token=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of file. |
|
protocol
|
Protocol to use: 'http' or 'https'. If not specified, uses the protocol specified when FileService was initialized. Default value: None
|
|
sas_token
|
Shared access signature token created with generate_shared_access_signature. Default value: None
|
Returns
| Type | Description |
|---|---|
|
file access URL. |
resize_file
Resizes a file to the specified size. If the specified byte value is less than the current size of the file, then all ranges above the specified byte value are cleared.
resize_file(share_name, directory_name, file_name, content_length, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
content_length
Required
|
The length to resize the file to. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
set_directory_metadata
Sets one or more user-defined name-value pairs for the specified directory. Each call to this operation replaces all existing metadata attached to the directory. To remove all metadata from the directory, call this operation with no metadata dict.
set_directory_metadata(share_name, directory_name, metadata=None, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
metadata
|
A dict containing name-value pairs to associate with the directory as metadata. Example: {'category':'test'} Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
set_directory_properties
set_directory_properties(share_name, directory_name, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of the share |
|
directory_name
Required
|
Name of the directory |
|
file_permission
|
File permission, a portable SDDL Default value: None
|
|
smb_properties
|
Sets the SMB related file properties |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
set_file_metadata
Sets user-defined metadata for the specified file as one or more name-value pairs.
set_file_metadata(share_name, directory_name, file_name, metadata=None, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
metadata
|
Dict containing name and 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 headers. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
set_file_properties
Sets system properties on the file. If one property is set for the content_settings, all properties will be overriden.
set_file_properties(share_name, directory_name, file_name, content_settings, timeout=None, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
content_settings
Required
|
ContentSettings object used to set the file properties. |
|
file_permission
|
File permission, a portable SDDL Default value: None
|
|
smb_properties
|
Sets the SMB related file properties |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
set_file_service_properties
Sets the properties of a storage account's File service, including Azure Storage Analytics. If an element (ex HourMetrics) is left as None, the existing settings on the service for that functionality are preserved.
set_file_service_properties(hour_metrics=None, minute_metrics=None, cors=None, timeout=None)Parameters
| Name | Description |
|---|---|
|
hour_metrics
|
<xref:Metrics>
The hour metrics settings provide a summary of request statistics grouped by API in hourly aggregates for files. Default value: None
|
|
minute_metrics
|
<xref:Metrics>
The minute metrics settings provide request statistics for each minute for files. Default value: None
|
|
cors
|
list(CorsRule)
You can include up to five CorsRule elements in the list. If an empty list is specified, all CORS rules will be deleted, and CORS will be disabled for the service. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
set_proxy
Sets the proxy server host and port for the HTTP CONNECT Tunnelling.
set_proxy(host, port, user=None, password=None)Parameters
| Name | Description |
|---|---|
|
host
Required
|
Address of the proxy. Ex: '192.168.0.100' |
|
port
Required
|
Port of the proxy. Ex: 6000 |
|
user
|
User for proxy authorization. Default value: None
|
|
password
|
Password for proxy authorization. Default value: None
|
set_share_acl
Sets the permissions for the specified share or stored access policies that may be used with Shared Access Signatures.
set_share_acl(share_name, signed_identifiers=None, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
signed_identifiers
|
dict(str, AccessPolicy)
A dictionary of access policies to associate with the share. The dictionary may contain up to 5 elements. An empty dictionary will clear the access policies set on the service. Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
set_share_metadata
Sets one or more user-defined name-value pairs for the specified share. Each call to this operation replaces all existing metadata attached to the share. To remove all metadata from the share, call this operation with no metadata dict.
set_share_metadata(share_name, metadata=None, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
metadata
|
A dict containing name-value pairs to associate with the share as metadata. Example: {'category':'test'} Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
set_share_properties
Sets service-defined properties for the specified share.
set_share_properties(share_name, quota, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
quota
Required
|
Specifies the maximum size of the share, in gigabytes. Must be greater than 0, and less than or equal to 5 TB (5120 GB). |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
snapshot_share
Creates a snapshot of an existing share under the specified account.
snapshot_share(share_name, metadata=None, quota=None, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
The name of the share to create a snapshot of. |
|
metadata
|
<xref:<xref:a dict> of <xref:str to str:>>
A dict with name_value pairs to associate with the share as metadata. Example:{'Category':'test'} Default value: None
|
|
quota
|
Specifies the maximum size of the share, in gigabytes. Must be greater than 0, and less than or equal to 5TB (5120). Default value: None
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Returns
| Type | Description |
|---|---|
|
snapshot properties |
update_range
Writes the bytes specified by the request body into the specified range.
update_range(share_name, directory_name, file_name, data, start_range, end_range, validate_content=False, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
data
Required
|
Content of the range. |
|
start_range
Required
|
Start of byte range to use for updating a section of the file. The range can be up to 4 MB in size. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. |
|
end_range
Required
|
End of byte range to use for updating a section of the file. The range can be up to 4 MB in size. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. |
|
validate_content
|
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. Default value: False
|
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
update_range_from_file_url
Writes the bytes from one Azure File endpoint into the specified range of another Azure File endpoint.
update_range_from_file_url(share_name, directory_name, file_name, start_range, end_range, source, source_start_range, timeout=None)Parameters
| Name | Description |
|---|---|
|
share_name
Required
|
Name of existing share. |
|
directory_name
Required
|
The path to the directory. |
|
file_name
Required
|
Name of existing file. |
|
start_range
Required
|
Start of byte range to use for updating a section of the file. The range can be up to 4 MB in size. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. |
|
end_range
Required
|
End of byte range to use for updating a section of the file. The range can be up to 4 MB in size. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. |
|
source
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_start_range
Required
|
Start of byte range to use for updating a section of the file. The range can be up to 4 MB in size. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file. |
|
timeout
|
The timeout parameter is expressed in seconds. Default value: None
|
Attributes
protocol
request_session
socket_timeout
MAX_CHUNK_GET_SIZE
MAX_CHUNK_GET_SIZE = 8388608MAX_RANGE_SIZE
MAX_RANGE_SIZE = 4194304MAX_SINGLE_GET_SIZE
MAX_SINGLE_GET_SIZE = 33554432
Azure SDK for Python