azure.storage.file.fileservice module

class azure.storage.file.fileservice.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)[source]

Bases: azure.storage.storageclient.StorageClient

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.

Variables:
  • 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.
Parameters:
  • 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.
  • account_key (str) – The storage account key. This is used for shared key authentication.
  • 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.
  • protocol (str) – The protocol to use for requests. Defaults to 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).
  • request_session (requests.Session) – The session object to use for http requests.
  • 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.
  • 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.
MAX_CHUNK_GET_SIZE = 8388608
MAX_RANGE_SIZE = 4194304
MAX_SINGLE_GET_SIZE = 33554432
abort_copy_file(share_name, directory_name, file_name, copy_id, timeout=None)[source]
Aborts a pending copy_file operation, and leaves a destination file with zero length and full metadata.
Parameters:
  • share_name (str) – Name of destination share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of destination file.
  • copy_id (str) – Copy identifier provided in the copy.id of the original copy_file operation.
  • timeout (int) – The timeout parameter is expressed in seconds.
clear_range(share_name, directory_name, file_name, start_range, end_range, timeout=None)[source]

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

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • start_range (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 (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.
copy_file(share_name, directory_name, file_name, copy_source, metadata=None, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of the destination share. The share must exist.
  • directory_name (str) – Name of the destination directory. The directory must exist.
  • file_name (str) – Name of the destination file. If the destination file exists, it will be overwritten. Otherwise, it will be created.
  • copy_source (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 (A dict mapping str to str.) – 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.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

Copy operation properties such as status, source, and ID.

Return type:

CopyProperties

create_directory(share_name, directory_name, metadata=None, fail_on_exist=False, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – Name of directory to create, including the path to the parent directory.
  • metadata (dict of str to str:) – A dict with name_value pairs to associate with the share as metadata. Example:{‘Category’:’test’}
  • fail_on_exist (bool) – specify whether to throw an exception when the directory exists. False by default.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

True if directory is created, False if directory already exists.

Return type:

bool

create_file(share_name, directory_name, file_name, content_length, content_settings=None, metadata=None, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of file to create or update.
  • content_length (int) – Length of the file in bytes.
  • content_settings (ContentSettings) – ContentSettings object used to set file properties.
  • metadata (a dict mapping str to str) – Name-value pairs associated with the file as metadata.
  • timeout (int) – The timeout parameter is expressed in seconds.
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)[source]

Creates a new file from an array of bytes, or updates the content of an existing file, with automatic chunking and progress notifications.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of file to create or update.
  • file (str) – Content of file as an array of bytes.
  • index (int) – Start index in the array of bytes.
  • count (int) – Number of bytes to upload. Set to None or negative value to upload all bytes starting from index.
  • content_settings (ContentSettings) – ContentSettings object used to set file properties.
  • metadata (a dict mapping str to str) – Name-value pairs associated with the file as metadata.
  • 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.
  • progress_callback (callback function in format of func(current, 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.
  • max_connections (int) – Maximum number of parallel connections to use.
  • 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.
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, timeout=None)[source]

Creates a new azure file from a local file path, or updates the content of an existing file, with automatic chunking and progress notifications.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of file to create or update.
  • local_file_path (str) – Path of the local file to upload as the file content.
  • content_settings (ContentSettings) – ContentSettings object used for setting file properties.
  • metadata (a dict mapping str to str) – Name-value pairs associated with the file as metadata.
  • 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.
  • progress_callback (callback function in format of func(current, 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.
  • max_connections (int) – Maximum number of parallel connections to use.
  • 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.
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)[source]

Creates a new file from a file/stream, or updates the content of an existing file, with automatic chunking and progress notifications.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of file to create or update.
  • stream (io.IOBase) – Opened file/stream to upload as the file content.
  • count (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.
  • metadata (a dict mapping str to str) – Name-value pairs associated with the file as metadata.
  • 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.
  • progress_callback (callback function in format of func(current, 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.
  • max_connections (int) – Maximum number of parallel connections to use. Note that parallel upload requires the stream to be seekable.
  • 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.
create_file_from_text(share_name, directory_name, file_name, text, encoding='utf-8', content_settings=None, metadata=None, validate_content=False, timeout=None)[source]

Creates a new file from str/unicode, or updates the content of an existing file, with automatic chunking and progress notifications.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of file to create or update.
  • text (str) – Text to upload to the file.
  • encoding (str) – Python encoding to use to convert the text to bytes.
  • content_settings (ContentSettings) – ContentSettings object used to set file properties.
  • metadata (a dict mapping str to str) – Name-value pairs associated with the file as metadata.
  • 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.
  • 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.
create_share(share_name, metadata=None, quota=None, fail_on_exist=False, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of share to create.
  • metadata (a dict of str to str:) – A dict with name_value pairs to associate with the share as metadata. Example:{‘Category’:’test’}
  • quota (int) – Specifies the maximum size of the share, in gigabytes. Must be greater than 0, and less than or equal to 5TB (5120).
  • fail_on_exist (bool) – Specify whether to throw an exception when the share exists. False by default.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

True if share is created, False if share already exists.

Return type:

bool

delete_directory(share_name, directory_name, fail_not_exist=False, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (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.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

True if directory is deleted, False otherwise.

Return type:

bool

delete_file(share_name, directory_name, file_name, timeout=None)[source]

Marks the specified file for deletion. The file is later deleted during garbage collection.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • timeout (int) – The timeout parameter is expressed in seconds.
delete_share(share_name, fail_not_exist=False, timeout=None)[source]

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.

Parameters:
  • share_name (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.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

True if share is deleted, False share doesn’t exist.

Return type:

bool

exists(share_name, directory_name=None, file_name=None, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of a share.
  • directory_name (str) – The path to a directory.
  • file_name (str) – Name of a file.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

A boolean indicating whether the resource exists.

Return type:

bool

generate_account_shared_access_signature(resource_types, permission, expiry, start=None, ip=None, protocol=None)[source]

Generates a shared access signature for the file service. Use the returned signature with the sas_token parameter of the FileService.

Parameters:
  • resource_types (ResourceTypes) – Specifies the resource types that are accessible with the account SAS.
  • permission (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 (date 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 (date 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.
  • 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.
  • 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.
Returns:

A Shared Access Signature (sas) token.

Return type:

str

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)[source]

Generates a shared access signature for the file. Use the returned signature with the sas_token parameter of FileService.

Parameters:
  • share_name (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.
  • file_name (str) – Name of file.
  • 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.
  • expiry (date 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 (date 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.
  • 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.
  • 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.
  • 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.
  • cache_control (str) – Response header value for Cache-Control when resource is accessed using this shared access signature.
  • content_disposition (str) – Response header value for Content-Disposition when resource is accessed using this shared access signature.
  • content_encoding (str) – Response header value for Content-Encoding when resource is accessed using this shared access signature.
  • content_language (str) – Response header value for Content-Language when resource is accessed using this shared access signature.
  • content_type (str) – Response header value for Content-Type when resource is accessed using this shared access signature.
Returns:

A Shared Access Signature (sas) token.

Return type:

str

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)[source]

Generates a shared access signature for the share. Use the returned signature with the sas_token parameter of FileService.

Parameters:
  • share_name (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.
  • expiry (date 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 (date 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.
  • 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().
  • 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.
  • 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.
  • cache_control (str) – Response header value for Cache-Control when resource is accessed using this shared access signature.
  • content_disposition (str) – Response header value for Content-Disposition when resource is accessed using this shared access signature.
  • content_encoding (str) – Response header value for Content-Encoding when resource is accessed using this shared access signature.
  • content_language (str) – Response header value for Content-Language when resource is accessed using this shared access signature.
  • content_type (str) – Response header value for Content-Type when resource is accessed using this shared access signature.
Returns:

A Shared Access Signature (sas) token.

Return type:

str

get_directory_metadata(share_name, directory_name, timeout=None)[source]

Returns all user-defined metadata for the specified directory.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

A dictionary representing the directory metadata name, value pairs.

Return type:

a dict mapping str to str

get_directory_properties(share_name, directory_name, timeout=None)[source]

Returns all user-defined metadata and system properties for the specified directory. The data returned does not include the directory’s list of files.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to an existing directory.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

properties for the specified directory within a directory object.

Return type:

Directory

get_file_metadata(share_name, directory_name, file_name, timeout=None)[source]

Returns all user-defined metadata for the specified file.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

A dictionary representing the file metadata name, value pairs.

Return type:

dict mapping str to str.

get_file_properties(share_name, directory_name, file_name, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

a file object including properties and metadata.

Return type:

File

get_file_service_properties(timeout=None)[source]

Gets the properties of a storage account’s File service, including Azure Storage Analytics.

Parameters:timeout (int) – The timeout parameter is expressed in seconds.
Returns:The file service properties.
Return type:ServiceProperties
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)[source]

Downloads a file as an array of bytes, with automatic chunking and progress notifications. Returns an instance of File with properties, metadata, and content.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (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.
  • 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.
  • 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.
  • progress_callback (callback function in format of func(current, 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.
  • 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.
  • 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.
Returns:

A File with properties, content, and metadata.

Return type:

File

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)[source]

Downloads a file to a file path, with automatic chunking and progress notifications. Returns an instance of File with properties and metadata.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • file_path (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.
  • 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.
  • 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.
  • 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.
  • progress_callback (callback function in format of func(current, 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.
  • 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.
  • 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.
Returns:

A File with properties and metadata.

Return type:

File

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)[source]

Downloads a file to a stream, with automatic chunking and progress notifications. Returns an instance of File with properties and metadata.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • stream (io.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.
  • 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.
  • 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.
  • progress_callback (callback function in format of func(current, 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.
  • 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.
  • 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.
Returns:

A File with properties and metadata.

Return type:

File

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)[source]

Downloads a file as unicode text, with automatic chunking and progress notifications. Returns an instance of File with properties, metadata, and content.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • encoding (str) – Python encoding to use when decoding the file data.
  • 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.
  • 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.
  • 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.
  • progress_callback (callback function in format of func(current, 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.
  • 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.
  • 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.
Returns:

A File with properties, content, and metadata.

Return type:

File

get_share_acl(share_name, timeout=None)[source]

Gets the permissions for the specified share.

Parameters:
  • share_name (str) – Name of existing share.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

A dictionary of access policies associated with the share.

Return type:

dict of str to AccessPolicy

get_share_metadata(share_name, timeout=None)[source]

Returns all user-defined metadata for the specified share.

Parameters:
  • share_name (str) – Name of existing share.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

A dictionary representing the share metadata name, value pairs.

Return type:

a dict mapping str to str

get_share_properties(share_name, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of existing share.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

A Share that exposes properties and metadata.

Return type:

Share

get_share_stats(share_name, timeout=None)[source]

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 resized files.

Parameters:
  • share_name (str) – Name of existing share.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

the approximate size of the data stored on the share.

Return type:

int

list_directories_and_files(share_name, directory_name=None, num_results=None, marker=None, timeout=None, prefix=None)[source]

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.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • 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).
  • 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.
  • timeout (int) – The timeout parameter is expressed in seconds.
  • prefix (str) – List only the files and/or directories with the given prefix.
list_ranges(share_name, directory_name, file_name, start_range=None, end_range=None, timeout=None)[source]

Retrieves the valid ranges for a file.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (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.
  • 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.
  • timeout (int) – The timeout parameter is expressed in seconds.
Returns:

a list of valid ranges

Return type:

a list of FileRange

list_shares(prefix=None, marker=None, num_results=None, include_metadata=False, timeout=None)[source]

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.

Parameters:
  • prefix (str) – Filters the results to return only shares whose names begin with the specified prefix.
  • num_results (int) – Specifies the maximum number of shares to return.
  • include_metadata (bool) – Specifies that share metadata be returned in the response.
  • 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.
  • timeout (int) – The timeout parameter is expressed in seconds.
make_file_url(share_name, directory_name, file_name, protocol=None, sas_token=None)[source]

Creates the url to access a file.

Parameters:
  • share_name (str) – Name of share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of file.
  • protocol (str) – Protocol to use: ‘http’ or ‘https’. If not specified, uses the protocol specified when FileService was initialized.
  • sas_token (str) – Shared access signature token created with generate_shared_access_signature.
Returns:

file access URL.

Return type:

str

resize_file(share_name, directory_name, file_name, content_length, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • content_length (int) – The length to resize the file to.
  • timeout (int) – The timeout parameter is expressed in seconds.
set_directory_metadata(share_name, directory_name, metadata=None, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • metadata (A dict mapping str to str.) – A dict containing name-value pairs to associate with the directory as metadata. Example: {‘category’:’test’}
  • timeout (int) – The timeout parameter is expressed in seconds.
set_file_metadata(share_name, directory_name, file_name, metadata=None, timeout=None)[source]

Sets user-defined metadata for the specified file as one or more name-value pairs.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • metadata (dict mapping str to 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.
  • timeout (int) – The timeout parameter is expressed in seconds.
set_file_properties(share_name, directory_name, file_name, content_settings, timeout=None)[source]

Sets system properties on the file. If one property is set for the content_settings, all properties will be overriden.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • content_settings (ContentSettings) – ContentSettings object used to set the file properties.
  • timeout (int) – The timeout parameter is expressed in seconds.
set_file_service_properties(hour_metrics=None, minute_metrics=None, cors=None, timeout=None)[source]

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.

Parameters:
  • hour_metrics (Metrics) – The hour metrics settings provide a summary of request statistics grouped by API in hourly aggregates for files.
  • minute_metrics (Metrics) – The minute metrics settings provide request statistics for each minute for files.
  • cors (list of 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.
  • timeout (int) – The timeout parameter is expressed in seconds.
set_share_acl(share_name, signed_identifiers=None, timeout=None)[source]

Sets the permissions for the specified share or stored access policies that may be used with Shared Access Signatures.

Parameters:
  • share_name (str) – Name of existing share.
  • signed_identifiers (dict of str to 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.
  • timeout (int) – The timeout parameter is expressed in seconds.
set_share_metadata(share_name, metadata=None, timeout=None)[source]

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.

Parameters:
  • share_name (str) – Name of existing share.
  • metadata (a dict mapping str to str) – A dict containing name-value pairs to associate with the share as metadata. Example: {‘category’:’test’}
  • timeout (int) – The timeout parameter is expressed in seconds.
set_share_properties(share_name, quota, timeout=None)[source]

Sets service-defined properties for the specified share.

Parameters:
  • share_name (str) – Name of existing share.
  • quota (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.
update_range(share_name, directory_name, file_name, data, start_range, end_range, validate_content=False, timeout=None)[source]

Writes the bytes specified by the request body into the specified range.

Parameters:
  • share_name (str) – Name of existing share.
  • directory_name (str) – The path to the directory.
  • file_name (str) – Name of existing file.
  • data (bytes) – Content of the range.
  • start_range (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 (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.
  • timeout (int) – The timeout parameter is expressed in seconds.