FileService Class

Reference

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

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.
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_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	bool 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
CopyProperties	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	bool 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	SMBProperties Sets the SMB related file properties
timeout	int The timeout parameter is expressed in seconds. default value: None

Returns

Type	Description
bool	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 ContentSettings object used to set file properties. default value: None
metadata	dict(str, str) 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	SMBProperties 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 ContentSettings object used to set file properties. default value: None
metadata	dict(str, str) Name-value pairs associated with the file as metadata. default value: None
validate_content	bool 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	SMBProperties 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 ContentSettings object used for setting file properties. default value: None
metadata	dict(str, str) Name-value pairs associated with the file as metadata. default value: None
validate_content	bool 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	SMBProperties 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	IOBase 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 ContentSettings object used to set file properties. default value: None
metadata	dict(str, str) Name-value pairs associated with the file as metadata. default value: None
validate_content	bool 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	SMBProperties 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 ContentSettings object used to set file properties. default value: None
metadata	dict(str, str) Name-value pairs associated with the file as metadata. default value: None
validate_content	bool 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	SMBProperties 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 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

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	dict(str, 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
fail_on_exist	bool 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
bool	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	bool 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
bool	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

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	bool 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	DeleteSnapshot To delete a share that has snapshots, this must be specified as DeleteSnapshot.Include. default value: None

Returns

Type	Description
bool	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
bool	A boolean indicating whether the resource exists.

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

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	SharePermissions 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	datetime or str 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	datetime or str 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
dict(str, str)	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
Directory	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
dict(str, str)	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
File	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
ServiceProperties	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	bool 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
File	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	bool 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
File	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	IOBase 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	bool 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
File	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	bool 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
File	A File with properties, content, and metadata.

: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

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
dict(str, AccessPolicy)	A dictionary of access policies associated with the share.

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
dict(str, str)	A dictionary representing the share metadata name, value pairs.

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
Share	A Share that exposes properties and metadata.

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.

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.

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	bool 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	bool 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	bool 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	SMBProperties 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(str, str) 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 ContentSettings object used to set the file properties.
file_permission	str File permission, a portable SDDL default value: None
smb_properties	SMBProperties 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

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

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

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

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
Share	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	bytes 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	bool If true, calculates an MD5 hash of the page content. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the file. 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

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