FileService class

Definition

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.

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)
Inheritance
builtins.object
FileService

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.

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

share_name
str
Required

Name of destination share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of destination file.

copy_id
str
Required

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

timeout
int
default value: None

The timeout parameter is expressed in seconds.

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

start_range
int
Required

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

end_range
int
Required

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

timeout
int
default value: None

The timeout parameter is expressed in seconds.

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

share_name
str
Required

Name of existing share.

directory_name
str
default value: None

The path to the directory.

file_name
str
default value: None

Name of existing file.

recursive
bool
default value: None

Boolean that specifies if operation should apply to the directory specified in the URI, its files, its subdirectories and their files.

handle_id
str
default value: None

Required. Specifies handle ID opened on the file or directory to be closed. Astrix (‘*’) is a wildcard that specifies all handles.

marker
str
default value: None

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.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

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

share_name
str
Required

Name of the destination share. The share must exist.

directory_name
str
Required

Name of the destination directory. The directory must exist.

file_name
str
Required

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

copy_source
str
Required

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

metadata
dict(str, str).
default value: None

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
default value: None

The timeout parameter is expressed in seconds.

Returns

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

Return type

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

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

metadata
dict(str, str):
default value: None

A dict with name_value pairs to associate with the share as metadata. Example:{'Category':'test'}

fail_on_exist
bool
default value: False

specify whether to throw an exception when the directory exists. False by default.

file_permission
str
default value: None

File permission, a portable SDDL

smb_properties
SMBProperties
default value: None

Sets the SMB related file properties

timeout
int
Required

The timeout parameter is expressed in seconds.

Returns

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

Return type

bool

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of file to create or update.

content_length
int
Required

Length of the file in bytes.

content_settings
ContentSettings
default value: None

ContentSettings object used to set file properties.

metadata
dict(str, str)
default value: None

Name-value pairs associated with the file as metadata.

file_permission
str
default value: None

File permission, a portable SDDL

smb_properties
SMBProperties
default value: None

Sets the SMB related file properties

timeout
int
Required

The timeout parameter is expressed in seconds.

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of file to create or update.

file
str
Required

Content of file as an array of bytes.

index
int
default value: 0

Start index in the array of bytes.

count
int
default value: None

Number of bytes to upload. Set to None or negative value to upload all bytes starting from index.

content_settings
ContentSettings
default value: None

ContentSettings object used to set file properties.

metadata
dict(str, str)
default value: None

Name-value pairs associated with the file as metadata.

validate_content
bool
default value: False

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
func(current, total)
default value: None

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
default value: 2

Maximum number of parallel connections to use.

file_permission
str
default value: None

File permission, a portable SDDL

smb_properties
SMBProperties
default value: None

Sets the SMB related file properties

timeout
int
Required

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

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of file to create or update.

local_file_path
str
Required

Path of the local file to upload as the file content.

content_settings
ContentSettings
default value: None

ContentSettings object used for setting file properties.

metadata
dict(str, str)
default value: None

Name-value pairs associated with the file as metadata.

validate_content
bool
default value: False

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
func(current, total)
default value: None

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
default value: 2

Maximum number of parallel connections to use.

file_permission
str
default value: None

File permission, a portable SDDL

smb_properties
SMBProperties
Required

Sets the SMB related file properties

timeout
int
default value: None

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

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of file to create or update.

stream
io.IOBase
Required

Opened file/stream to upload as the file content.

count
int
Required

Number of bytes to read from the stream. This is required, a file cannot be created if the count is unknown.

content_settings
ContentSettings
default value: None

ContentSettings object used to set file properties.

metadata
dict(str, str)
default value: None

Name-value pairs associated with the file as metadata.

validate_content
bool
default value: False

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
func(current, total)
default value: None

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
default value: 2

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

file_permission
str
default value: None

File permission, a portable SDDL

smb_properties
SMBProperties
default value: None

Sets the SMB related file properties

timeout
int
Required

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

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of file to create or update.

text
str
Required

Text to upload to the file.

encoding
str
default value: utf-8

Python encoding to use to convert the text to bytes.

content_settings
ContentSettings
default value: None

ContentSettings object used to set file properties.

metadata
dict(str, str)
default value: None

Name-value pairs associated with the file as metadata.

validate_content
bool
default value: False

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.

file_permission
str
default value: None

File permission, a portable SDDL

smb_properties
SMBProperties
default value: None

Sets the SMB related file properties

timeout
int
Required

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_permission_for_share

Create a permission(a security descriptor) at the share level. This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key.

:returns a file permission key :rtype str

create_permission_for_share(share_name, file_permission, timeout=None)

Parameters

share_name
Required

Name of share.

file_permission
Required

File permission, a Portable SDDL

timeout
default value: None

The timeout parameter is expressed in seconds.

create_share

Creates a new share under the specified account. If the share with the same name already exists, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_on_exists.

create_share(share_name, metadata=None, quota=None, fail_on_exist=False, timeout=None)

Parameters

share_name
str
Required

Name of share to create.

metadata
dict(str, str)
default value: None

A dict with name_value pairs to associate with the share as metadata. Example:{'Category':'test'}

quota
int
default value: None

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
default value: False

Specify whether to throw an exception when the share exists. False by default.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

Returns

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

Return type

bool

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

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

fail_not_exist
bool
default value: False

Specify whether to throw an exception when the directory doesn't exist.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

Returns

True if directory is deleted, False otherwise.

Return type

bool

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

delete_share

Marks the specified share for deletion. If the share does not exist, the operation fails on the service. By default, the exception is swallowed by the client. To expose the exception, specify True for fail_not_exist.

delete_share(share_name, fail_not_exist=False, timeout=None, snapshot=None, delete_snapshots=None)

Parameters

share_name
str
Required

Name of share to delete.

fail_not_exist
bool
default value: False

Specify whether to throw an exception when the share doesn't exist. False by default.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

snapshot
str
default value: None

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.

delete_snapshots
DeleteSnapshot
default value: None

To delete a share that has snapshots, this must be specified as DeleteSnapshot.Include.

Returns

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

Return type

bool

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

share_name
str
Required

Name of a share.

directory_name
str
default value: None

The path to a directory.

file_name
str
default value: None

Name of a file.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

A boolean indicating whether the resource exists.

Return type

bool

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

resource_types
ResourceTypes
Required

Specifies the resource types that are accessible with the account SAS.

permission
AccountPermissions
Required

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
datetime or str
Required

The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

start
datetime or str
default value: None

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
default value: None

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
default value: None

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

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

share_name
str
Required

Name of share.

directory_name
str
default value: None

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
default value: None

Name of file.

permission
FilePermissions
default value: None

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
datetime or str
default value: None

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
default value: None

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
default value: None

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
default value: None

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
default value: None

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
default value: None

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

content_disposition
str
default value: None

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

content_encoding
str
default value: None

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

content_language
str
default value: None

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

content_type
str
default value: None

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

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

share_name
str
Required

Name of share.

permission
SharePermissions
default value: None

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
datetime or str
default value: None

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
default value: None

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
default value: None

A unique value up to 64 characters in length that correlates to a stored access policy. To create a stored access policy, use <xref:azure.storage.file.fileservice.set_share_acl>.

ip
str
default value: None

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
default value: None

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
default value: None

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

content_disposition
str
default value: None

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

content_encoding
str
default value: None

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

content_language
str
default value: None

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

content_type
str
default value: None

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

Returns all user-defined metadata for the specified directory.

get_directory_metadata(share_name, directory_name, timeout=None, snapshot=None)

Parameters

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

A dictionary representing the directory metadata name, value pairs.

Return type

dict(str, str)

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to an existing directory.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

properties for the specified directory within a directory object.

Return type

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

A dictionary representing the file metadata name, value pairs.

Return type

dict(str, str)

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

a file object including properties and metadata.

Return type

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

timeout
int
default value: None

The timeout parameter is expressed in seconds.

Returns

The file service properties.

Return type

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

start_range
int
default value: None

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
default value: None

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
default value: False

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
func(current, total)
default value: None

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
default value: 2

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
default value: None

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.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

A File with properties, content, and metadata.

Return type

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

file_path
str
Required

Path of file to write to.

open_mode
str
default value: wb

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
default value: None

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
default value: None

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
default value: False

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
func(current, total)
default value: None

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
default value: 2

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
default value: None

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.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

A File with properties and metadata.

Return type

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

stream
io.IOBase
Required

Opened file/stream to write to.

start_range
int
default value: None

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
default value: None

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
default value: False

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
func(current, total)
default value: None

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
default value: 2

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
default value: None

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.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

A File with properties and metadata.

Return type

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

encoding
str
default value: utf-8

Python encoding to use when decoding the file data.

start_range
int
default value: None

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
default value: None

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
default value: False

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
func(current, total)
default value: None

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
default value: 2

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
default value: None

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.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

A File with properties, content, and metadata.

Return type

get_permission_for_share

Create a permission(a security descriptor) at the share level. This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key.

:returns a file permission(a portable SDDL) :rtype str

get_permission_for_share(share_name, file_permission_key, timeout=None)

Parameters

share_name
Required

Name of share.

file_permission_key
Required

Key of the file permission to retrieve

timeout
default value: None

The timeout parameter is expressed in seconds.

get_share_acl

Gets the permissions for the specified share.

get_share_acl(share_name, timeout=None)

Parameters

share_name
str
Required

Name of existing share.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

Returns

A dictionary of access policies associated with the share.

Return type

dict(str, <xref:azure.storage.common.models.AccessPolicy>)

get_share_metadata

Returns all user-defined metadata for the specified share.

get_share_metadata(share_name, timeout=None, snapshot=None)

Parameters

share_name
str
Required

Name of existing share.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

A dictionary representing the share metadata name, value pairs.

Return type

dict(str, str)

get_share_properties

Returns all user-defined metadata and system properties for the specified share. The data returned does not include the shares's list of files or directories.

get_share_properties(share_name, timeout=None, snapshot=None)

Parameters

share_name
str
Required

Name of existing share.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

A Share that exposes properties and metadata.

Return type

get_share_stats

Gets the approximate size of the data stored on the share, rounded up to the nearest gigabyte.

Note that this value may not include all recently created or recently re-sized files.

get_share_stats(share_name, timeout=None)

Parameters

share_name
str
Required

Name of existing share.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

Returns

the approximate size of the data stored on the share.

Return type

int

get_share_stats_in_bytes

Gets the approximate size of the data stored on the share in bytes.

Note that this value may not include all recently created or recently re-sized files.

get_share_stats_in_bytes(share_name, timeout=None)

Parameters

share_name
str
Required

Name of existing share.

timeout
int
default value: None

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

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

share_name
str
Required

Name of existing share.

directory_name
str
default value: None

The path to the directory.

num_results
int
default value: None

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
default value: None

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
default value: None

The timeout parameter is expressed in seconds.

prefix
str
default value: None

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

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

list_handles

Returns a generator to list opened handles on a directory or a file under the specified share. The generator will lazily follow the continuation tokens returned by the service and stop when all handles have been returned or num_results is reached.

If num_results is specified and the share has more than that number of files and directories, the generator will have a populated next_marker field once it finishes. This marker can be used to create a new generator if more results are desired.

list_handles(share_name, directory_name=None, file_name=None, recursive=None, max_results=None, marker=None, snapshot=None, timeout=None)

Parameters

share_name
str
Required

Name of existing share.

directory_name
str
default value: None

The path to the directory.

file_name
str
default value: None

Name of existing file.

recursive
bool
default value: None

Boolean that specifies if operation should apply to the directory specified in the URI, its files, its subdirectories and their files.

max_results
int
default value: None

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).

marker
str
default value: None

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.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

start_range
int
default value: None

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
default value: None

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
default value: None

The timeout parameter is expressed in seconds.

snapshot
str
default value: None

A string that represents the snapshot version, if applicable.

Returns

a list of valid ranges

Return type

a list of <xref:azure.storage.file.models.FileRange>

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

prefix
str
default value: None

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

num_results
int
default value: None

Specifies the maximum number of shares to return.

include_metadata
bool
default value: None

Specifies that share metadata be returned in the response.

marker
str
default value: False

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
default value: None

The timeout parameter is expressed in seconds.

include_snapshots
bool
default value: False

Specifies that share snapshots be returned in the response.

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

share_name
str
Required

Name of share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of file.

protocol
str
default value: None

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

sas_token
str
default value: None

Shared access signature token created with generate_shared_access_signature.

Returns

file access URL.

Return type

str

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

content_length
int
Required

The length to resize the file to.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

metadata
dict(str, str).
default value: None

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

timeout
int
default value: None

The timeout parameter is expressed in seconds.

set_directory_properties

set_directory_properties(share_name, directory_name, file_permission=None, smb_properties=<azure.storage.file.models.SMBProperties object>, timeout=None)

Parameters

share_name
Required

Name of the share

directory_name
Required

Name of the directory

file_permission
str
default value: None

File permission, a portable SDDL

smb_properties
SMBProperties
Required

Sets the SMB related file properties

timeout
int
default value: None

The timeout parameter is expressed in seconds.

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

metadata
dict(str, str)
default value: None

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
default value: None

The timeout parameter is expressed in seconds.

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

content_settings
ContentSettings
Required

ContentSettings object used to set the file properties.

file_permission
str
default value: None

File permission, a portable SDDL

smb_properties
SMBProperties
default value: None

Sets the SMB related file properties

timeout
int
Required

The timeout parameter is expressed in seconds.

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

hour_metrics
Metrics
default value: None

The hour metrics settings provide a summary of request statistics grouped by API in hourly aggregates for files.

minute_metrics
Metrics
default value: None

The minute metrics settings provide request statistics for each minute for files.

cors
list(CorsRule)
default value: None

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
default value: None

The timeout parameter is expressed in seconds.

set_share_acl

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

set_share_acl(share_name, signed_identifiers=None, timeout=None)

Parameters

share_name
str
Required

Name of existing share.

signed_identifiers
dict(str, AccessPolicy)
default value: None

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
default value: None

The timeout parameter is expressed in seconds.

set_share_metadata

Sets one or more user-defined name-value pairs for the specified share. Each call to this operation replaces all existing metadata attached to the share. To remove all metadata from the share, call this operation with no metadata dict.

set_share_metadata(share_name, metadata=None, timeout=None)

Parameters

share_name
str
Required

Name of existing share.

metadata
dict(str, str)
default value: None

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

timeout
int
default value: None

The timeout parameter is expressed in seconds.

set_share_properties

Sets service-defined properties for the specified share.

set_share_properties(share_name, quota, timeout=None)

Parameters

share_name
str
Required

Name of existing share.

quota
int
Required

Specifies the maximum size of the share, in gigabytes. Must be greater than 0, and less than or equal to 5 TB (5120 GB).

timeout
int
default value: None

The timeout parameter is expressed in seconds.

snapshot_share

Creates a snapshot of an existing share under the specified account.

snapshot_share(share_name, metadata=None, quota=None, timeout=None)

Parameters

share_name
str
Required

The name of the share to create a snapshot of.

metadata
a dict of str to str:
default value: None

A dict with name_value pairs to associate with the share as metadata. Example:{'Category':'test'}

quota
int
default value: None

Specifies the maximum size of the share, in gigabytes. Must be greater than 0, and less than or equal to 5TB (5120).

timeout
int
default value: None

The timeout parameter is expressed in seconds.

Returns

snapshot properties

Return type

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

data
bytes
Required

Content of the range.

start_range
int
Required

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

end_range
int
Required

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

validate_content
bool
default value: False

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
default value: None

The timeout parameter is expressed in seconds.

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

share_name
str
Required

Name of existing share.

directory_name
str
Required

The path to the directory.

file_name
str
Required

Name of existing file.

start_range
int
Required

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

end_range
int
Required

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

source
str
Required

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

source_start_range
int
Required

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

timeout
int
default value: None

The timeout parameter is expressed in seconds.

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