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
str

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
str

The storage account key. This is used for shared key authentication.

Default value: None
sas_token
str

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
str

The protocol to use for requests. Defaults to https.

Default value: https
endpoint_suffix
str

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
str

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
int

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
int

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
int

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
int

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
str

Name of destination share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of destination file.

copy_id
Required
str

Copy identifier provided in the copy.id of the original copy_file operation.

timeout
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

start_range
Required
int

Start of byte range to use for clearing a section of the file. The range can be up to 4 MB in size. 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
int

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
int

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
str

Name of existing share.

directory_name
str

The path to the directory.

Default value: None
file_name
str

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
str

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
str

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
str

A string that represents the snapshot version, if applicable.

Default value: None
timeout
int

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
str

Name of the destination share. The share must exist.

directory_name
Required
str

Name of the destination directory. The directory must exist.

file_name
Required
str

Name of the destination file. If the destination file exists, it will be overwritten. Otherwise, it will be created.

copy_source
Required
str

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

metadata
dict(str, str)<xref:./>

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
int

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
str

Name of existing share.

directory_name
Required
str

Name of directory to create, including the path to the parent directory.

metadata
dict(str, str)<xref::>

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
str

File permission, a portable SDDL

Default value: None
smb_properties

Sets the SMB related file properties

timeout
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of file to create or update.

content_length
Required
int

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
str

File permission, a portable SDDL

Default value: None
smb_properties

Sets the SMB related file properties

timeout
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of file to create or update.

file
Required
str

Content of file as an array of bytes.

index
int

Start index in the array of bytes.

Default value: 0
count
int

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
int

Maximum number of parallel connections to use.

Default value: 2
file_permission
str

File permission, a portable SDDL

Default value: None
smb_properties

Sets the SMB related file properties

timeout
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of file to create or update.

local_file_path
Required
str

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
int

Maximum number of parallel connections to use.

Default value: 2
file_permission
str

File permission, a portable SDDL

Default value: None
smb_properties

Sets the SMB related file properties

timeout
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of file to create or update.

stream
Required

Opened file/stream to upload as the file content.

count
Required
int

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
int

Maximum number of parallel connections to use. Note that parallel upload requires the stream to be seekable.

Default value: 2
file_permission
str

File permission, a portable SDDL

Default value: None
smb_properties

Sets the SMB related file properties

timeout
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of file to create or update.

text
Required
str

Text to upload to the file.

encoding
str

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
str

File permission, a portable SDDL

Default value: None
smb_properties

Sets the SMB related file properties

timeout
int

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
str

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
int

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
int

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
str

Name of existing share.

directory_name
Required
str

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
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

timeout
int

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
str

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
int

The timeout parameter is expressed in seconds.

Default value: None
snapshot
str

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
str

Name of a share.

directory_name
str

The path to a directory.

Default value: None
file_name
str

Name of a file.

Default value: None
timeout
int

The timeout parameter is expressed in seconds.

Default value: None
snapshot
str

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
str

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
str

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
str

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
str

Name of share.

directory_name
str

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
str

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
str

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
str

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
str

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
str

Response header value for Cache-Control when resource is accessed using this shared access signature.

Default value: None
content_disposition
str

Response header value for Content-Disposition when resource is accessed using this shared access signature.

Default value: None
content_encoding
str

Response header value for Content-Encoding when resource is accessed using this shared access signature.

Default value: None
content_language
str

Response header value for Content-Language when resource is accessed using this shared access signature.

Default value: None
content_type
str

Response header value for Content-Type when resource is accessed using this shared access signature.

Default value: None

Returns

Type Description
str

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
str

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
str

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
str

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
str

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
str

Response header value for Cache-Control when resource is accessed using this shared access signature.

Default value: None
content_disposition
str

Response header value for Content-Disposition when resource is accessed using this shared access signature.

Default value: None
content_encoding
str

Response header value for Content-Encoding when resource is accessed using this shared access signature.

Default value: None
content_language
str

Response header value for Content-Language when resource is accessed using this shared access signature.

Default value: None
content_type
str

Response header value for Content-Type when resource is accessed using this shared access signature.

Default value: None

Returns

Type Description
str

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

timeout
int

The timeout parameter is expressed in seconds.

Default value: None
snapshot
str

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
str

Name of existing share.

directory_name
Required
str

The path to an existing directory.

timeout
int

The timeout parameter is expressed in seconds.

Default value: None
snapshot
str

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

timeout
int

The timeout parameter is expressed in seconds.

Default value: None
snapshot
str

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

timeout
int

The timeout parameter is expressed in seconds.

Default value: None
snapshot
str

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
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

start_range
int

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
int

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
int

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
int

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
str

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

file_path
Required
str

Path of file to write to.

open_mode
str

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
int

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
int

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
int

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
int

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
str

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

stream
Required

Opened file/stream to write to.

start_range
int

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
int

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
int

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
int

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
str

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

encoding
str

Python encoding to use when decoding the file data.

Default value: utf-8
start_range
int

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
int

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
int

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
int

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
str

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
str

Name of existing share.

timeout
int

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
str

Name of existing share.

timeout
int

The timeout parameter is expressed in seconds.

Default value: None
snapshot
str

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
str

Name of existing share.

timeout
int

The timeout parameter is expressed in seconds.

Default value: None
snapshot
str

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
str

Name of existing share.

timeout
int

The timeout parameter is expressed in seconds.

Default value: None

Returns

Type Description
int

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
str

Name of existing share.

timeout
int

The timeout parameter is expressed in seconds.

Default value: None

Returns

Type Description
int

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
str

Name of existing share.

directory_name
str

The path to the directory.

Default value: None
num_results
int

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
str

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
int

The timeout parameter is expressed in seconds.

Default value: None
prefix
str

List only the files and/or directories with the given prefix.

Default value: None
snapshot
str

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
str

Name of existing share.

directory_name
str

The path to the directory.

Default value: None
file_name
str

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
int

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
str

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
str

A string that represents the snapshot version, if applicable.

Default value: None
timeout
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

start_range
int

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
int

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
int

The timeout parameter is expressed in seconds.

Default value: None
snapshot
str

A string that represents the snapshot version, if applicable.

Default value: None

Returns

Type Description
<xref:a> list <xref:of> FileRange

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
str

Filters the results to return only shares whose names begin with the specified prefix.

Default value: None
num_results
int

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
str

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
int

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
str

Name of share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of file.

protocol
str

Protocol to use: 'http' or 'https'. If not specified, uses the protocol specified when FileService was initialized.

Default value: None
sas_token
str

Shared access signature token created with generate_shared_access_signature.

Default value: None

Returns

Type Description
str

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

content_length
Required
int

The length to resize the file to.

timeout
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

metadata
dict(str, str)<xref:./>

A dict containing name-value pairs to associate with the directory as metadata. Example: {'category':'test'}

Default value: None
timeout
int

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
str

File permission, a portable SDDL

Default value: None
smb_properties

Sets the SMB related file properties

timeout
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

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
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

content_settings
Required

ContentSettings object used to set the file properties.

file_permission
str

File permission, a portable SDDL

Default value: None
smb_properties

Sets the SMB related file properties

timeout
int

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
int

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
str

Address of the proxy. Ex: '192.168.0.100'

port
Required
int

Port of the proxy. Ex: 6000

user
str

User for proxy authorization.

Default value: None
password
str

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
str

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
int

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
str

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
int

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
str

Name of existing share.

quota
Required
int

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
int

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
str

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
int

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
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

data
Required

Content of the range.

start_range
Required
int

Start of byte range to use for updating a section of the file. The range can be up to 4 MB in size. 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
int

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
int

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
str

Name of existing share.

directory_name
Required
str

The path to the directory.

file_name
Required
str

Name of existing file.

start_range
Required
int

Start of byte range to use for updating a section of the file. The range can be up to 4 MB in size. 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
int

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
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_start_range
Required
int

Start of byte range to use for updating a section of the file. The range can be up to 4 MB in size. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file.

timeout
int

The timeout parameter is expressed in seconds.

Default value: None

Attributes

protocol

request_session

socket_timeout

MAX_CHUNK_GET_SIZE

MAX_CHUNK_GET_SIZE = 8388608

MAX_RANGE_SIZE

MAX_RANGE_SIZE = 4194304

MAX_SINGLE_GET_SIZE

MAX_SINGLE_GET_SIZE = 33554432