azure.storage.filedatalake package

class azure.storage.filedatalake.DataLakeServiceClient(account_url, credential=None, **kwargs)

A client to interact with the DataLake Service at the account level.

This client provides operations to retrieve and configure the account properties as well as list, create and delete file systems within the account. For operations relating to a specific file system, directory or file, clients for those entities can also be retrieved using the get_client functions.

Variables

• url (str) – The full endpoint URL to the datalake service endpoint. This could be either the primary endpoint, or the secondary endpoint depending on the current location_mode.

• primary_endpoint (str) – The full primary endpoint URL.

• primary_hostname (str) – The hostname of the primary endpoint.

Parameters

• account_url (str) – The URL to the DataLake storage account. Any other entities included in the URL path (e.g. file system or file) will be discarded. This URL can be optionally authenticated with a SAS token.

• credential – The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. If the URL already has a SAS token, specifying an explicit credential will take priority.

Example:

close()

create_file_system(file_system, metadata=None, public_access=None, **kwargs)

Creates a new file system under the specified account.

If the file system with the same name already exists, a ResourceExistsError will be raised. This method returns a client with which to interact with the newly created file system.

Parameters

• file_system (str) – The name of the file system to create.

• metadata (dict(str, str)) – A dict with name-value pairs to associate with the file system as metadata. Example: {‘Category’:’test’}

• public_access (PublicAccess) – Possible values include: file system, file.

Keyword Arguments

timeout (int) – The timeout parameter is expressed in seconds.

Return type

FileSystemClient

Example:

delete_file_system(file_system, **kwargs)

Marks the specified file system for deletion.

The file system and any files contained within it are later deleted during garbage collection. If the file system is not found, a ResourceNotFoundError will be raised.

Parameters

file_system (str or FileSystemProperties) – The file system to delete. This can either be the name of the file system, or an instance of FileSystemProperties.

Keyword Arguments

• lease (DataLakeLeaseClient) – If specified, delete_file_system only succeeds if the file system’s lease is active and matches this ID. Required if the file system has an active lease.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Return type

None

Example:

classmethod from_connection_string(conn_str, credential=None, **kwargs)

Create DataLakeServiceClient from a Connection String.

Parameters

• conn_str (str) – A connection string to an Azure Storage account.

• credential – The credentials with which to authenticate. This is optional if the account URL already has a SAS token, or the connection string already has shared access key values. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. Credentials provided here will take precedence over those in the connection string.

:return a DataLakeServiceClient :rtype ~azure.storage.filedatalake.DataLakeServiceClient

get_directory_client(file_system, directory)

Get a client to interact with the specified directory.

The directory need not already exist.

Parameters

• file_system (str or FileSystemProperties) – The file system that the directory is in. This can either be the name of the file system, or an instance of FileSystemProperties.

• directory (str or DirectoryProperties) – The directory with which to interact. This can either be the name of the directory, or an instance of DirectoryProperties.

Returns

A DataLakeDirectoryClient.

Return type

DataLakeDirectoryClient

Example:

get_file_client(file_system, file_path)

Get a client to interact with the specified file.

The file need not already exist.

Parameters

• file_system (str or FileSystemProperties) – The file system that the file is in. This can either be the name of the file system, or an instance of FileSystemProperties.

• file_path (str or FileProperties) – The file with which to interact. This can either be the full path of the file(from the root directory), or an instance of FileProperties. eg. directory/subdirectory/file

Returns

A DataLakeFileClient.

Return type

DataLakeFileClient

Example:

get_file_system_client(file_system)

Get a client to interact with the specified file system.

The file system need not already exist.

Parameters

file_system (str or FileSystemProperties) – The file system. This can either be the name of the file system, or an instance of FileSystemProperties.

Returns

A FileSystemClient.

Return type

FileSystemClient

Example:

get_user_delegation_key(key_start_time, key_expiry_time, **kwargs)

Obtain a user delegation key for the purpose of signing SAS tokens. A token credential must be present on the service object for this request to succeed.

Parameters

• key_start_time (datetime) – A DateTime value. Indicates when the key becomes valid.

• key_expiry_time (datetime) – A DateTime value. Indicates when the key stops being valid.

Keyword Arguments

timeout (int) – The timeout parameter is expressed in seconds.

Returns

The user delegation key.

Return type

UserDelegationKey

list_file_systems(name_starts_with=None, include_metadata=None, **kwargs)

Returns a generator to list the file systems under the specified account.

The generator will lazily follow the continuation tokens returned by the service and stop when all file systems have been returned.

Parameters

• name_starts_with (str) – Filters the results to return only file systems whose names begin with the specified prefix.

• include_metadata (bool) – Specifies that file system metadata be returned in the response. The default value is False.

Keyword Arguments

• results_per_page (int) – The maximum number of file system names to retrieve per API call. If the request does not specify the server will return up to 5,000 items per page.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

An iterable (auto-paging) of FileSystemProperties.

Return type

ItemPaged[FileSystemProperties]

Example:

property location_mode

The location mode that the client is currently using.

By default this will be “primary”. Options include “primary” and “secondary”.

Type

str

property primary_endpoint

The full primary endpoint URL.

Type

str

property primary_hostname

The hostname of the primary endpoint.

Type

str

property secondary_endpoint

The full secondary endpoint URL if configured.

If not available a ValueError will be raised. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Type

str

Raises

ValueError –

property secondary_hostname

The hostname of the secondary endpoint.

If not available this will be None. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Type

str or None

property url

The full endpoint URL to this entity, including SAS token if used.

This could be either the primary endpoint, or the secondary endpoint depending on the current location_mode().

class azure.storage.filedatalake.FileSystemClient(account_url, file_system_name, credential=None, **kwargs)

A client to interact with a specific file system, even if that file system may not yet exist.

For operations relating to a specific directory or file within this file system, a directory client or file client can be retrieved using the get_directory_client() or get_file_client() functions.

Variables

• url (str) – The full endpoint URL to the file system, including SAS token if used.

• primary_endpoint (str) – The full primary endpoint URL.

• primary_hostname (str) – The hostname of the primary endpoint.

Parameters

• account_url (str) – The URI to the storage account.

• file_system_name (str) – The file system for the directory or files.

• credential – The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. If the URL already has a SAS token, specifying an explicit credential will take priority.

Example:

acquire_lease(lease_duration=-1, lease_id=None, **kwargs)

Requests a new lease. If the file system does not have an active lease, the DataLake service creates a lease on the file system and returns a new lease ID.

Parameters

• lease_duration (int) – Specifies the duration of the lease, in seconds, or negative one (-1) for a lease that never expires. A non-infinite lease can be between 15 and 60 seconds. A lease duration cannot be changed using renew or change. Default is -1 (infinite lease).

• lease_id (str) – Proposed lease ID, in a GUID string format. The DataLake service returns 400 (Invalid request) if the proposed lease ID is not in the correct format.

Keyword Arguments

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

A DataLakeLeaseClient object, that can be run in a context manager.

Return type

DataLakeLeaseClient

Example:

close()

create_directory(directory, content_settings=None, metadata=None, **kwargs)

Create directory

Parameters

• directory (str or DirectoryProperties) – The directory with which to interact. This can either be the name of the directory, or an instance of DirectoryProperties.

• content_settings (ContentSettings) – ContentSettings object used to set path properties.

• metadata (dict(str, str)) – Name-value pairs associated with the blob as metadata.

Keyword Arguments

• or str lease (DataLakeLeaseClient) – Required if the blob has an active lease. Value can be a DataLakeLeaseClient object or the lease ID as a string.

• umask (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. When creating a file or directory and the parent folder does not have a default ACL, the umask restricts the permissions of the file or directory to be created. The resulting permission is given by p & ^u, where p is the permission and u is the umask. For example, if p is 0777 and u is 0057, then the resulting permission is 0720. The default permission is 0777 for a directory and 0666 for a file. The default umask is 0027. The umask must be specified in 4-digit octal notation (e.g. 0766).

• permissions (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

DataLakeDirectoryClient

create_file(file, **kwargs)

Create file

Parameters

• file (str or FileProperties) – The file with which to interact. This can either be the name of the file, or an instance of FileProperties.

• content_settings (ContentSettings) – ContentSettings object used to set path properties.

• metadata (dict(str, str)) – Name-value pairs associated with the blob as metadata.

Keyword Arguments

• or str lease (DataLakeLeaseClient) – Required if the blob has an active lease. Value can be a DataLakeLeaseClient object or the lease ID as a string.

• umask (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. When creating a file or directory and the parent folder does not have a default ACL, the umask restricts the permissions of the file or directory to be created. The resulting permission is given by p & ^u, where p is the permission and u is the umask. For example, if p is 0777 and u is 0057, then the resulting permission is 0720. The default permission is 0777 for a directory and 0666 for a file. The default umask is 0027. The umask must be specified in 4-digit octal notation (e.g. 0766).

• permissions (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

DataLakeFileClient

create_file_system(metadata=None, public_access=None, **kwargs)

Creates a new file system under the specified account.

If the file system with the same name already exists, a ResourceExistsError will be raised. This method returns a client with which to interact with the newly created file system.

Parameters

• metadata (dict(str, str)) – A dict with name-value pairs to associate with the file system as metadata. Example: {‘Category’:’test’}

• public_access (PublicAccess) – Possible values include: file system, file.

Keyword Arguments

timeout (int) – The timeout parameter is expressed in seconds.

Return type

FileSystemClient

Example:

delete_directory(directory, **kwargs)

Marks the specified path for deletion.

Parameters

directory (str or DirectoryProperties) – The directory with which to interact. This can either be the name of the directory, or an instance of DirectoryProperties.

Keyword Arguments

• lease – Required if the blob has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

DataLakeDirectoryClient

delete_file(file, lease=None, **kwargs)

Marks the specified file for deletion.

Parameters

file (str or FileProperties) – The file with which to interact. This can either be the name of the file, or an instance of FileProperties.

Keyword Arguments

• lease – Required if the blob has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

DataLakeFileClient

delete_file_system(**kwargs)

Marks the specified file system for deletion.

The file system and any files contained within it are later deleted during garbage collection. If the file system is not found, a ResourceNotFoundError will be raised.

Keyword Arguments

• or ~azure.storage.filedatalake.DataLakeLeaseClient lease (str) – If specified, delete_file_system only succeeds if the file system’s lease is active and matches this ID. Required if the file system has an active lease.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Return type

None

Example:

classmethod from_connection_string(conn_str, file_system_name, credential=None, **kwargs)

Create FileSystemClient from a Connection String.

Parameters

• conn_str (str) – A connection string to an Azure Storage account.

• file_system_name (str) – The name of file system to interact with.

• credential – The credentials with which to authenticate. This is optional if the account URL already has a SAS token, or the connection string already has shared access key values. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. Credentials provided here will take precedence over those in the connection string.

:return a FileSystemClient :rtype ~azure.storage.filedatalake.FileSystemClient

get_directory_client(directory)

Get a client to interact with the specified directory.

The directory need not already exist.

Parameters

directory (str or DirectoryProperties) – The directory with which to interact. This can either be the name of the directory, or an instance of DirectoryProperties.

Returns

A DataLakeDirectoryClient.

Return type

DataLakeDirectoryClient

Example:

get_file_client(file_path)

Get a client to interact with the specified file.

The file need not already exist.

Parameters

file_path (str or FileProperties) – The file with which to interact. This can either be the path of the file(from root directory), or an instance of FileProperties. eg. directory/subdirectory/file

Returns

A DataLakeFileClient.

Return type

DataLakeFileClient

Example:

get_file_system_properties(**kwargs)

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

Keyword Arguments

• or ~azure.storage.filedatalake.DataLakeLeaseClient lease (str) – If specified, get_file_system_properties only succeeds if the file system’s lease is active and matches this ID.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

Properties for the specified file system within a file system object.

Return type

FileSystemProperties

Example:

get_paths(path=None, recursive=True, max_results=None, **kwargs)

Returns a generator to list the paths(could be files or directories) under the specified file system. The generator will lazily follow the continuation tokens returned by the service.

Parameters

• path (str) – Filters the results to return only paths under the specified path.

• max_results (int) – An optional value that specifies the maximum number of items to return per page. If omitted or greater than 5,000, the response will include up to 5,000 items per page.

Keyword Arguments

• upn – Optional. Valid only when Hierarchical Namespace is enabled for the account. If “true”, the user identity values returned in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User Principal Names. If “false”, the values will be returned as Azure Active Directory Object IDs. The default value is false. Note that group and application Object IDs are not translated because they do not have unique friendly names.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

An iterable (auto-paging) response of PathProperties.

Return type

ItemPaged[PathProperties]

Example:

set_file_system_metadata(metadata=None, **kwargs)

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

Parameters

metadata (dict[str, str]) – A dict containing name-value pairs to associate with the file system as metadata. Example: {‘category’:’test’}

Keyword Arguments

• or ~azure.storage.filedatalake.DataLakeLeaseClient lease (str) – If specified, set_file_system_metadata only succeeds if the file system’s lease is active and matches this ID.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

file system-updated property dict (Etag and last modified).

Example:

property location_mode

The location mode that the client is currently using.

By default this will be “primary”. Options include “primary” and “secondary”.

Type

str

property primary_endpoint

The full primary endpoint URL.

Type

str

property primary_hostname

The hostname of the primary endpoint.

Type

str

property secondary_endpoint

The full secondary endpoint URL if configured.

If not available a ValueError will be raised. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Type

str

Raises

ValueError –

property secondary_hostname

The hostname of the secondary endpoint.

If not available this will be None. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Type

str or None

property url

The full endpoint URL to this entity, including SAS token if used.

This could be either the primary endpoint, or the secondary endpoint depending on the current location_mode().

class azure.storage.filedatalake.DataLakeFileClient(account_url, file_system_name, file_path, credential=None, **kwargs)

A client to interact with the DataLake file, even if the file may not yet exist.

Variables

• url (str) – The full endpoint URL to the file system, including SAS token if used.

• primary_endpoint (str) – The full primary endpoint URL.

• primary_hostname (str) – The hostname of the primary endpoint.

Parameters

• account_url (str) – The URI to the storage account.

• file_system_name (str) – The file system for the directory or files.

• file_path (str) – The whole file path, so that to interact with a specific file. eg. “{directory}/{subdirectory}/{file}”

• credential – The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. If the URL already has a SAS token, specifying an explicit credential will take priority.

Example:

acquire_lease(lease_duration=-1, lease_id=None, **kwargs)

Requests a new lease. If the file or directory does not have an active lease, the DataLake service creates a lease on the file/directory and returns a new lease ID.

Parameters

• lease_duration (int) – Specifies the duration of the lease, in seconds, or negative one (-1) for a lease that never expires. A non-infinite lease can be between 15 and 60 seconds. A lease duration cannot be changed using renew or change. Default is -1 (infinite lease).

• lease_id (str) – Proposed lease ID, in a GUID string format. The DataLake service returns 400 (Invalid request) if the proposed lease ID is not in the correct format.

Keyword Arguments

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

A DataLakeLeaseClient object, that can be run in a context manager.

Return type

DataLakeLeaseClient

Example:

append_data(data, offset, length=None, **kwargs)

Append data to the file.

Parameters

• data – Content to be appended to file

• offset – start position of the data to be appended to.

• length – Size of the data in bytes.

Keyword Arguments

• validate_content (bool) – If true, calculates an MD5 hash of the block 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 blob.

• lease – Required if the blob has an active lease. Value can be a LeaseClient object or the lease ID as a string.

Returns

dict of the response header

close()

create_file(content_settings=None, metadata=None, **kwargs)

Create a new file.

Parameters

• content_settings (ContentSettings) – ContentSettings object used to set path properties.

• metadata (dict(str, str)) – Name-value pairs associated with the blob as metadata.

Keyword Arguments

• or str lease (DataLakeLeaseClient) – Required if the blob has an active lease. Value can be a DataLakeLeaseClient object or the lease ID as a string.

• umask (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. When creating a file or directory and the parent folder does not have a default ACL, the umask restricts the permissions of the file or directory to be created. The resulting permission is given by p & ^u, where p is the permission and u is the umask. For example, if p is 0777 and u is 0057, then the resulting permission is 0720. The default permission is 0777 for a directory and 0666 for a file. The default umask is 0027. The umask must be specified in 4-digit octal notation (e.g. 0766).

• permissions (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

response dict (Etag and last modified).

delete_file(**kwargs)

Marks the specified file for deletion.

Keyword Arguments

• lease – Required if the blob has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

None

flush_data(offset, retain_uncommitted_data=False, **kwargs)

Commit the previous appended data.

Parameters

• offset – offset is equal to the length of the file after commit the previous appended data.

• retain_uncommitted_data (bool) – Valid only for flush operations. If “true”, uncommitted data is retained after the flush operation completes; otherwise, the uncommitted data is deleted after the flush operation. The default is false. Data at offsets less than the specified position are written to the file when flush succeeds, but this optional parameter allows data after the flush position to be retained for a future flush operation.

Keyword Arguments

• close (bool) – Azure Storage Events allow applications to receive notifications when files change. When Azure Storage Events are enabled, a file changed event is raised. This event has a property indicating whether this is the final change to distinguish the difference between an intermediate flush to a file stream and the final close of a file stream. The close query parameter is valid only when the action is “flush” and change notifications are enabled. If the value of close is “true” and the flush operation completes successfully, the service raises a file change notification with a property indicating that this is the final update (the file stream has been closed). If “false” a change notification is raised indicating the file has changed. The default is false. This query parameter is set to true by the Hadoop ABFS driver to indicate that the file stream has been closed.”

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

Returns

response header in dict

classmethod from_connection_string(conn_str, file_system_name, file_path, credential=None, **kwargs)

Create DataLakeFileClient from a Connection String.

Parameters

• conn_str (str) – A connection string to an Azure Storage account.

• file_system_name (str) – The name of file system to interact with.

• directory_name (str) – The name of directory to interact with. The directory is under file system.

• file_name (str) – The name of file to interact with. The file is under directory.

• credential – The credentials with which to authenticate. This is optional if the account URL already has a SAS token, or the connection string already has shared access key values. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. Credentials provided here will take precedence over those in the connection string.

:return a DataLakeFileClient :rtype ~azure.storage.filedatalake.DataLakeFileClient

get_access_control(upn=None, **kwargs)

Parameters

upn (bool) – Optional. Valid only when Hierarchical Namespace is enabled for the account. If “true”, the user identity values returned in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User Principal Names. If “false”, the values will be returned as Azure Active Directory Object IDs. The default value is false. Note that group and application Object IDs are not translated because they do not have unique friendly names.

Keyword Arguments

• lease – Required if the file/directory has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Keyword

response dict.

get_file_properties(**kwargs)

Returns all user-defined metadata, standard HTTP properties, and system properties for the file. It does not return the content of the file.

Keyword Arguments

• lease – Required if the directory or file has an active lease. Value can be a DataLakeLeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Return type

FileProperties

Example:

read_file(offset=None, length=None, stream=None, **kwargs)

Download a file from the service. Return the downloaded data in bytes or write the downloaded data into user provided stream and return the written size.

Parameters

• offset (int) – Start of byte range to use for downloading a section of the file. Must be set if length is provided.

• length (int) – Number of bytes to read from the stream. This is optional, but should be supplied for optimal performance.

• stream (int) – User provided stream to write the downloaded data into.

Keyword Arguments

• lease – If specified, download_blob only succeeds if the blob’s lease is active and matches this ID. Required if the blob has an active lease.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• max_concurrency (int) – The number of parallel connections with which to download.

• 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

downloaded data or the size of data written into the provided stream

Return type

bytes or int

Example:

rename_file(rename_destination, **kwargs)

Rename the source file.

Parameters

• rename_destination (str) – the new file name the user want to rename to. The value must have the following format: “{filesystem}/{directory}/{subdirectory}/{file}”.

• content_settings (ContentSettings) – ContentSettings object used to set path properties.

Keyword Arguments

• source_lease – A lease ID for the source path. If specified, the source path must have an active lease and the leaase ID must match.

• source_lease – ~azure.storage.filedatalake.DataLakeLeaseClient or str

• lease – Required if the file/directory has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• umask (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. When creating a file or directory and the parent folder does not have a default ACL, the umask restricts the permissions of the file or directory to be created. The resulting permission is given by p & ^u, where p is the permission and u is the umask. For example, if p is 0777 and u is 0057, then the resulting permission is 0720. The default permission is 0777 for a directory and 0666 for a file. The default umask is 0027. The umask must be specified in 4-digit octal notation (e.g. 0766).

• permissions – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• source_if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• source_if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• source_etag (str) – The source ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• source_match_condition (MatchConditions) – The source match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

set_access_control(owner=None, group=None, permissions=None, acl=None, **kwargs)

Set the owner, group, permissions, or access control list for a path.

Parameters

• owner (str) – Optional. The owner of the file or directory.

• group (str) – Optional. The owning group of the file or directory.

• permissions (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported. permissions and acl are mutually exclusive.

• acl (str) – Sets POSIX access control rights on files and directories. The value is a comma-separated list of access control entries. Each access control entry (ACE) consists of a scope, a type, a user or group identifier, and permissions in the format “[scope:][type]:[id]:[permissions]”. permissions and acl are mutually exclusive.

Keyword Arguments

• lease – Required if the file/directory has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Keyword

response dict (Etag and last modified).

set_http_headers(content_settings=None, **kwargs)

Sets system properties on the file or directory.

If one property is set for the content_settings, all properties will be overriden.

Parameters

content_settings (ContentSettings) – ContentSettings object used to set file/directory properties.

Keyword Arguments

• or ~azure.storage.filedatalake.DataLakeLeaseClient lease (str) – If specified, set_file_system_metadata only succeeds if the file system’s lease is active and matches this ID.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

file/directory-updated property dict (Etag and last modified)

Return type

Dict[str, Any]

set_metadata(metadata=None, **kwargs)

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

Parameters

metadata (dict[str, str]) – A dict containing name-value pairs to associate with the file system as metadata. Example: {‘category’:’test’}

Keyword Arguments

• or ~azure.storage.filedatalake.DataLakeLeaseClient lease (str) – If specified, set_file_system_metadata only succeeds if the file system’s lease is active and matches this ID.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

file system-updated property dict (Etag and last modified).

Example:

property location_mode

The location mode that the client is currently using.

By default this will be “primary”. Options include “primary” and “secondary”.

Type

str

property primary_endpoint

The full primary endpoint URL.

Type

str

property primary_hostname

The hostname of the primary endpoint.

Type

str

property secondary_endpoint

The full secondary endpoint URL if configured.

If not available a ValueError will be raised. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Type

str

Raises

ValueError –

property secondary_hostname

The hostname of the secondary endpoint.

If not available this will be None. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Type

str or None

property url

The full endpoint URL to this entity, including SAS token if used.

This could be either the primary endpoint, or the secondary endpoint depending on the current location_mode().

class azure.storage.filedatalake.DataLakeDirectoryClient(account_url, file_system_name, directory_name, credential=None, **kwargs)

A client to interact with the DataLake directory, even if the directory may not yet exist.

For operations relating to a specific subdirectory or file under the directory, a directory client or file client can be retrieved using the get_sub_directory_client() or get_file_client() functions.

Variables

• url (str) – The full endpoint URL to the file system, including SAS token if used.

• primary_endpoint (str) – The full primary endpoint URL.

• primary_hostname (str) – The hostname of the primary endpoint.

Parameters

• account_url (str) – The URI to the storage account.

• file_system_name (str) – The file system for the directory or files.

• directory_name (str) – The whole path of the directory. eg. {directory under file system}/{directory to interact with}

• credential – The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. If the URL already has a SAS token, specifying an explicit credential will take priority.

Example:

acquire_lease(lease_duration=-1, lease_id=None, **kwargs)

Requests a new lease. If the file or directory does not have an active lease, the DataLake service creates a lease on the file/directory and returns a new lease ID.

Parameters

• lease_duration (int) – Specifies the duration of the lease, in seconds, or negative one (-1) for a lease that never expires. A non-infinite lease can be between 15 and 60 seconds. A lease duration cannot be changed using renew or change. Default is -1 (infinite lease).

• lease_id (str) – Proposed lease ID, in a GUID string format. The DataLake service returns 400 (Invalid request) if the proposed lease ID is not in the correct format.

Keyword Arguments

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

A DataLakeLeaseClient object, that can be run in a context manager.

Return type

DataLakeLeaseClient

Example:

close()

create_directory(content_settings=None, metadata=None, **kwargs)

Create a new directory.

Parameters

• content_settings (ContentSettings) – ContentSettings object used to set path properties.

• metadata (dict(str, str)) – Name-value pairs associated with the blob as metadata.

Keyword Arguments

• lease (DataLakeLeaseClient or str) – Required if the blob has an active lease. Value can be a DataLakeLeaseClient object or the lease ID as a string.

• umask (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. When creating a file or directory and the parent folder does not have a default ACL, the umask restricts the permissions of the file or directory to be created. The resulting permission is given by p & ^u, where p is the permission and u is the umask. For example, if p is 0777 and u is 0057, then the resulting permission is 0720. The default permission is 0777 for a directory and 0666 for a file. The default umask is 0027. The umask must be specified in 4-digit octal notation (e.g. 0766).

• permissions (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

response dict (Etag and last modified).

create_file(file, **kwargs)

Create a new file and return the file client to be interacted with.

Parameters

file (str or FileProperties) – The file with which to interact. This can either be the name of the file, or an instance of FileProperties.

Keyword Arguments

• content_settings (ContentSettings) – ContentSettings object used to set path properties.

• metadata – Name-value pairs associated with the blob as metadata.

• or str lease (DataLakeLeaseClient) – Required if the blob has an active lease. Value can be a DataLakeLeaseClient object or the lease ID as a string.

• umask (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. When creating a file or directory and the parent folder does not have a default ACL, the umask restricts the permissions of the file or directory to be created. The resulting permission is given by p & ^u, where p is the permission and u is the umask. For example, if p is 0777 and u is 0057, then the resulting permission is 0720. The default permission is 0777 for a directory and 0666 for a file. The default umask is 0027. The umask must be specified in 4-digit octal notation (e.g. 0766).

• permissions (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

DataLakeFileClient

create_sub_directory(sub_directory, content_settings=None, metadata=None, **kwargs)

Create a subdirectory and return the subdirectory client to be interacted with.

Parameters

• sub_directory (str or DirectoryProperties) – The directory with which to interact. This can either be the name of the directory, or an instance of DirectoryProperties.

• content_settings (ContentSettings) – ContentSettings object used to set path properties.

• metadata (dict(str, str)) – Name-value pairs associated with the blob as metadata.

Keyword Arguments

• or str lease (DataLakeLeaseClient) – Required if the blob has an active lease. Value can be a DataLakeLeaseClient object or the lease ID as a string.

• umask (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. When creating a file or directory and the parent folder does not have a default ACL, the umask restricts the permissions of the file or directory to be created. The resulting permission is given by p & ^u, where p is the permission and u is the umask. For example, if p is 0777 and u is 0057, then the resulting permission is 0720. The default permission is 0777 for a directory and 0666 for a file. The default umask is 0027. The umask must be specified in 4-digit octal notation (e.g. 0766).

• permissions (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

DataLakeDirectoryClient for the subdirectory.

delete_directory(**kwargs)

Marks the specified directory for deletion.

Keyword Arguments

• lease – Required if the blob has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

None

delete_sub_directory(sub_directory, **kwargs)

Marks the specified subdirectory for deletion.

Parameters

sub_directory (str or DirectoryProperties) – The directory with which to interact. This can either be the name of the directory, or an instance of DirectoryProperties.

Keyword Arguments

• lease – Required if the blob has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

DataLakeDirectoryClient for the subdirectory

classmethod from_connection_string(conn_str, file_system_name, directory_name, credential=None, **kwargs)

Create DataLakeDirectoryClient from a Connection String.

Parameters

• conn_str (str) – A connection string to an Azure Storage account.

• file_system_name (str) – The name of file system to interact with.

• directory_name (str) – The name of directory to interact with. The directory is under file system.

• credential – The credentials with which to authenticate. This is optional if the account URL already has a SAS token, or the connection string already has shared access key values. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. Credentials provided here will take precedence over those in the connection string.

:return a DataLakeDirectoryClient :rtype ~azure.storage.filedatalake.DataLakeDirectoryClient

get_access_control(upn=None, **kwargs)

Parameters

upn (bool) – Optional. Valid only when Hierarchical Namespace is enabled for the account. If “true”, the user identity values returned in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User Principal Names. If “false”, the values will be returned as Azure Active Directory Object IDs. The default value is false. Note that group and application Object IDs are not translated because they do not have unique friendly names.

Keyword Arguments

• lease – Required if the file/directory has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Keyword

response dict.

get_directory_properties(**kwargs)

Returns all user-defined metadata, standard HTTP properties, and system properties for the directory. It does not return the content of the directory.

Keyword Arguments

• lease – Required if the directory or file has an active lease. Value can be a DataLakeLeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Return type

DirectoryProperties

Example:

get_file_client(file)

Get a client to interact with the specified file.

The file need not already exist.

Parameters

file (str or FileProperties) – The file with which to interact. This can either be the name of the file, or an instance of FileProperties. eg. directory/subdirectory/file

Returns

A DataLakeFileClient.

Return type

DataLakeFileClient

Example:

get_sub_directory_client(sub_directory)

Get a client to interact with the specified subdirectory of the current directory.

The sub subdirectory need not already exist.

Parameters

sub_directory (str or DirectoryProperties) – The directory with which to interact. This can either be the name of the directory, or an instance of DirectoryProperties.

Returns

A DataLakeDirectoryClient.

Return type

DataLakeDirectoryClient

Example:

rename_directory(rename_destination, **kwargs)

Rename the source directory.

Parameters

• rename_destination (str) – the new directory name the user want to rename to. The value must have the following format: “{filesystem}/{directory}/{subdirectory}”.

• content_settings (ContentSettings) – ContentSettings object used to set path properties.

Keyword Arguments

• source_lease – A lease ID for the source path. If specified, the source path must have an active lease and the leaase ID must match.

• source_lease – ~azure.storage.filedatalake.DataLakeLeaseClient or str

• lease – Required if the file/directory has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• umask (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. When creating a file or directory and the parent folder does not have a default ACL, the umask restricts the permissions of the file or directory to be created. The resulting permission is given by p & ^u, where p is the permission and u is the umask. For example, if p is 0777 and u is 0057, then the resulting permission is 0720. The default permission is 0777 for a directory and 0666 for a file. The default umask is 0027. The umask must be specified in 4-digit octal notation (e.g. 0766).

• permissions – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• source_if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• source_if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• source_etag (str) – The source ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• source_match_condition (MatchConditions) – The source match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

DataLakeDirectoryClient

set_access_control(owner=None, group=None, permissions=None, acl=None, **kwargs)

Set the owner, group, permissions, or access control list for a path.

Parameters

• owner (str) – Optional. The owner of the file or directory.

• group (str) – Optional. The owning group of the file or directory.

• permissions (str) – Optional and only valid if Hierarchical Namespace is enabled for the account. Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported. permissions and acl are mutually exclusive.

• acl (str) – Sets POSIX access control rights on files and directories. The value is a comma-separated list of access control entries. Each access control entry (ACE) consists of a scope, a type, a user or group identifier, and permissions in the format “[scope:][type]:[id]:[permissions]”. permissions and acl are mutually exclusive.

Keyword Arguments

• lease – Required if the file/directory has an active lease. Value can be a LeaseClient object or the lease ID as a string.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Keyword

response dict (Etag and last modified).

set_http_headers(content_settings=None, **kwargs)

Sets system properties on the file or directory.

If one property is set for the content_settings, all properties will be overriden.

Parameters

content_settings (ContentSettings) – ContentSettings object used to set file/directory properties.

Keyword Arguments

• or ~azure.storage.filedatalake.DataLakeLeaseClient lease (str) – If specified, set_file_system_metadata only succeeds if the file system’s lease is active and matches this ID.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

file/directory-updated property dict (Etag and last modified)

Return type

Dict[str, Any]

set_metadata(metadata=None, **kwargs)

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

Parameters

metadata (dict[str, str]) – A dict containing name-value pairs to associate with the file system as metadata. Example: {‘category’:’test’}

Keyword Arguments

• or ~azure.storage.filedatalake.DataLakeLeaseClient lease (str) – If specified, set_file_system_metadata only succeeds if the file system’s lease is active and matches this ID.

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

file system-updated property dict (Etag and last modified).

Example:

property location_mode

The location mode that the client is currently using.

By default this will be “primary”. Options include “primary” and “secondary”.

Type

str

property primary_endpoint

The full primary endpoint URL.

Type

str

property primary_hostname

The hostname of the primary endpoint.

Type

str

property secondary_endpoint

The full secondary endpoint URL if configured.

If not available a ValueError will be raised. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Type

str

Raises

ValueError –

property secondary_hostname

The hostname of the secondary endpoint.

If not available this will be None. To explicitly specify a secondary hostname, use the optional secondary_hostname keyword argument on instantiation.

Type

str or None

property url

The full endpoint URL to this entity, including SAS token if used.

This could be either the primary endpoint, or the secondary endpoint depending on the current location_mode().

class azure.storage.filedatalake.DataLakeLeaseClient(client, lease_id=None)

Creates a new DataLakeLeaseClient.

This client provides lease operations on a FileSystemClient, DataLakeDirectoryClient or DataLakeFileClient.

Variables

• id (str) – The ID of the lease currently being maintained. This will be None if no lease has yet been acquired.

• etag (str) – The ETag of the lease currently being maintained. This will be None if no lease has yet been acquired or modified.

• last_modified (datetime) – The last modified timestamp of the lease currently being maintained. This will be None if no lease has yet been acquired or modified.

Parameters

• client (FileSystemClient or DataLakeDirectoryClient or DataLakeFileClient) – The client of the file system, directory, or file to lease.

• lease_id (str) – A string representing the lease ID of an existing lease. This value does not need to be specified in order to acquire a new lease, or break one.

acquire(lease_duration=-1, **kwargs)

Requests a new lease.

If the container does not have an active lease, the Blob service creates a lease on the container and returns a new lease ID.

Parameters

lease_duration (int) – Specifies the duration of the lease, in seconds, or negative one (-1) for a lease that never expires. A non-infinite lease can be between 15 and 60 seconds. A lease duration cannot be changed using renew or change. Default is -1 (infinite lease).

Keyword Arguments

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Return type

None

break_lease(lease_break_period=None, **kwargs)

Break the lease, if the container or blob has an active lease.

Once a lease is broken, it cannot be renewed. Any authorized request can break the lease; the request is not required to specify a matching lease ID. When a lease is broken, the lease break period is allowed to elapse, during which time no lease operation except break and release can be performed on the container or blob. When a lease is successfully broken, the response indicates the interval in seconds until a new lease can be acquired.

Parameters

lease_break_period (int) – This is the proposed duration of seconds that the lease should continue before it is broken, between 0 and 60 seconds. This break period is only used if it is shorter than the time remaining on the lease. If longer, the time remaining on the lease is used. A new lease will not be available before the break period has expired, but the lease may be held for longer than the break period. If this header does not appear with a break operation, a fixed-duration lease breaks after the remaining lease period elapses, and an infinite lease breaks immediately.

Keyword Arguments

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

Approximate time remaining in the lease period, in seconds.

Return type

int

change(proposed_lease_id, **kwargs)

Change the lease ID of an active lease.

Parameters

proposed_lease_id (str) – Proposed lease ID, in a GUID string format. The Blob service returns 400 (Invalid request) if the proposed lease ID is not in the correct format.

Keyword Arguments

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

None

release(**kwargs)

Release the lease.

The lease may be released if the client lease id specified matches that associated with the container or blob. Releasing the lease allows another client to immediately acquire the lease for the container or blob as soon as the release is complete.

Keyword Arguments

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

None

renew(**kwargs)

Renews the lease.

The lease can be renewed if the lease ID specified in the lease client matches that associated with the container or blob. Note that the lease may be renewed even if it has expired as long as the container or blob has not been leased again since the expiration of that lease. When you renew a lease, the lease duration clock resets.

Keyword Arguments

• if_modified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

• if_unmodified_since (datetime) – A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

• etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.

• match_condition (MatchConditions) – The match condition to use upon the etag.

• timeout (int) – The timeout parameter is expressed in seconds.

Returns

None

class azure.storage.filedatalake.ExponentialRetry(initial_backoff=15, increment_base=3, retry_total=3, retry_to_secondary=False, random_jitter_range=3, **kwargs)

Exponential retry.

Constructs an Exponential retry object. The initial_backoff is used for the first retry. Subsequent retries are retried after initial_backoff + increment_power^retry_count seconds. For example, by default the first retry occurs after 15 seconds, the second after (15+3^1) = 18 seconds, and the third after (15+3^2) = 24 seconds.

Parameters

• initial_backoff (int) – The initial backoff interval, in seconds, for the first retry.

• increment_base (int) – The base, in seconds, to increment the initial_backoff by after the first retry.

• max_attempts (int) – The maximum number of retry attempts.

• retry_to_secondary (bool) – Whether the request should be retried to secondary, if able. This should only be enabled of RA-GRS accounts are used and potentially stale data can be handled.

• random_jitter_range (int) – A number in seconds which indicates a range to jitter/randomize for the back-off interval. For example, a random_jitter_range of 3 results in the back-off interval x to vary between x+3 and x-3.

configure_retries(request)

get_backoff_time(settings)

Calculates how long to sleep before retrying.

Returns

An integer indicating how long to wait before retrying the request, or None to indicate no retry should be performed.

Return type

int or None

increment(settings, request, response=None, error=None)

Increment the retry counters.

Parameters

• response – A pipeline response object.

• error – An error encountered during the request, or None if the response was received successfully.

Returns

Whether the retry attempts are exhausted.

send(request)

Abstract send method for a synchronous pipeline. Mutates the request.

Context content is dependent on the HttpTransport.

Parameters

request (PipelineRequest) – The pipeline request object

Returns

The pipeline response object.

Return type

PipelineResponse

sleep(settings, transport)

class azure.storage.filedatalake.LinearRetry(backoff=15, retry_total=3, retry_to_secondary=False, random_jitter_range=3, **kwargs)

Linear retry.

Constructs a Linear retry object.

Parameters

• backoff (int) – The backoff interval, in seconds, between retries.

• max_attempts (int) – The maximum number of retry attempts.

• retry_to_secondary (bool) – Whether the request should be retried to secondary, if able. This should only be enabled of RA-GRS accounts are used and potentially stale data can be handled.

• random_jitter_range (int) – A number in seconds which indicates a range to jitter/randomize for the back-off interval. For example, a random_jitter_range of 3 results in the back-off interval x to vary between x+3 and x-3.

configure_retries(request)

get_backoff_time(settings)

Calculates how long to sleep before retrying.

Returns

An integer indicating how long to wait before retrying the request, or None to indicate no retry should be performed.

Return type

int or None

increment(settings, request, response=None, error=None)

Increment the retry counters.

Parameters

• response – A pipeline response object.

• error – An error encountered during the request, or None if the response was received successfully.

Returns

Whether the retry attempts are exhausted.

send(request)

Abstract send method for a synchronous pipeline. Mutates the request.

Context content is dependent on the HttpTransport.

Parameters

request (PipelineRequest) – The pipeline request object

Returns

The pipeline response object.

Return type

PipelineResponse

sleep(settings, transport)

class azure.storage.filedatalake.LocationMode

Specifies the location the request should be sent to. This mode only applies for RA-GRS accounts which allow secondary read access. All other account types must use PRIMARY.

PRIMARY = 'primary'

Requests should be sent to the primary location.

SECONDARY = 'secondary'

Requests should be sent to the secondary location, if possible.

class azure.storage.filedatalake.PublicAccess

Specifies whether data in the file system may be accessed publicly and the level of access.

File = 'blob'

Specifies public read access for files. file data within this file system can be read via anonymous request, but file system data is not available. Clients cannot enumerate files within the container via anonymous request.

FileSystem = 'container'

Specifies full public read access for file system and file data. Clients can enumerate files within the file system via anonymous request, but cannot enumerate file systems within the storage account.

OFF = 'off'

Specifies that there is no public read access for both the file systems and files within the file system. Clients cannot enumerate the file systems within the storage account as well as the files within the file system.

class azure.storage.filedatalake.ResourceTypes(service=False, file_system=False, object=False)

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

Parameters

• service (bool) – Access to service-level APIs (e.g.List File Systems)

• file_system (bool) – Access to file_system-level APIs (e.g., Create/Delete file system, List Directories/Files)

• object (bool) – Access to object-level APIs for files(e.g. Create File, etc.)

classmethod from_string(string)

Create a ResourceTypes from a string.

To specify service, container, or object you need only to include the first letter of the word in the string. E.g. service and container, you would provide a string “sc”.

Parameters

string (str) – Specify service, container, or object in in the string with the first letter of the word.

Returns

A ResourceTypes object

Return type

ResourceTypes

class azure.storage.filedatalake.StorageErrorCode

An enumeration.

account_already_exists = 'AccountAlreadyExists'

account_being_created = 'AccountBeingCreated'

account_is_disabled = 'AccountIsDisabled'

append_position_condition_not_met = 'AppendPositionConditionNotMet'

authentication_failed = 'AuthenticationFailed'

authorization_failure = 'AuthorizationFailure'

blob_already_exists = 'BlobAlreadyExists'

blob_archived = 'BlobArchived'

blob_being_rehydrated = 'BlobBeingRehydrated'

blob_not_archived = 'BlobNotArchived'

blob_not_found = 'BlobNotFound'

blob_overwritten = 'BlobOverwritten'

blob_tier_inadequate_for_content_length = 'BlobTierInadequateForContentLength'

block_count_exceeds_limit = 'BlockCountExceedsLimit'

block_list_too_long = 'BlockListTooLong'

cannot_change_to_lower_tier = 'CannotChangeToLowerTier'

cannot_delete_file_or_directory = 'CannotDeleteFileOrDirectory'

cannot_verify_copy_source = 'CannotVerifyCopySource'

client_cache_flush_delay = 'ClientCacheFlushDelay'

condition_headers_not_supported = 'ConditionHeadersNotSupported'

condition_not_met = 'ConditionNotMet'

container_already_exists = 'ContainerAlreadyExists'

container_being_deleted = 'ContainerBeingDeleted'

container_disabled = 'ContainerDisabled'

container_not_found = 'ContainerNotFound'

container_quota_downgrade_not_allowed = 'ContainerQuotaDowngradeNotAllowed'

content_length_larger_than_tier_limit = 'ContentLengthLargerThanTierLimit'

content_length_must_be_zero = 'ContentLengthMustBeZero'

copy_across_accounts_not_supported = 'CopyAcrossAccountsNotSupported'

copy_id_mismatch = 'CopyIdMismatch'

delete_pending = 'DeletePending'

destination_path_is_being_deleted = 'DestinationPathIsBeingDeleted'

directory_not_empty = 'DirectoryNotEmpty'

empty_metadata_key = 'EmptyMetadataKey'

feature_version_mismatch = 'FeatureVersionMismatch'

file_lock_conflict = 'FileLockConflict'

file_system_already_exists = 'FilesystemAlreadyExists'

file_system_being_deleted = 'FilesystemBeingDeleted'

file_system_not_found = 'FilesystemNotFound'

incremental_copy_blob_mismatch = 'IncrementalCopyBlobMismatch'

incremental_copy_of_eralier_version_snapshot_not_allowed = 'IncrementalCopyOfEralierVersionSnapshotNotAllowed'

incremental_copy_source_must_be_snapshot = 'IncrementalCopySourceMustBeSnapshot'

infinite_lease_duration_required = 'InfiniteLeaseDurationRequired'

insufficient_account_permissions = 'InsufficientAccountPermissions'

internal_error = 'InternalError'

invalid_authentication_info = 'InvalidAuthenticationInfo'

invalid_blob_or_block = 'InvalidBlobOrBlock'

invalid_blob_tier = 'InvalidBlobTier'

invalid_blob_type = 'InvalidBlobType'

invalid_block_id = 'InvalidBlockId'

invalid_block_list = 'InvalidBlockList'

invalid_destination_path = 'InvalidDestinationPath'

invalid_file_or_directory_path_name = 'InvalidFileOrDirectoryPathName'

invalid_flush_position = 'InvalidFlushPosition'

invalid_header_value = 'InvalidHeaderValue'

invalid_http_verb = 'InvalidHttpVerb'

invalid_input = 'InvalidInput'

invalid_marker = 'InvalidMarker'

invalid_md5 = 'InvalidMd5'

invalid_metadata = 'InvalidMetadata'

invalid_operation = 'InvalidOperation'

invalid_page_range = 'InvalidPageRange'

invalid_property_name = 'InvalidPropertyName'

invalid_query_parameter_value = 'InvalidQueryParameterValue'

invalid_range = 'InvalidRange'

invalid_rename_source_path = 'InvalidRenameSourcePath'

invalid_resource_name = 'InvalidResourceName'

invalid_source_blob_type = 'InvalidSourceBlobType'

invalid_source_blob_url = 'InvalidSourceBlobUrl'

invalid_source_or_destination_resource_type = 'InvalidSourceOrDestinationResourceType'

invalid_source_uri = 'InvalidSourceUri'

invalid_uri = 'InvalidUri'

invalid_version_for_page_blob_operation = 'InvalidVersionForPageBlobOperation'

invalid_xml_document = 'InvalidXmlDocument'

invalid_xml_node_value = 'InvalidXmlNodeValue'

lease_already_broken = 'LeaseAlreadyBroken'

lease_already_present = 'LeaseAlreadyPresent'

lease_id_mismatch_with_blob_operation = 'LeaseIdMismatchWithBlobOperation'

lease_id_mismatch_with_container_operation = 'LeaseIdMismatchWithContainerOperation'

lease_id_mismatch_with_lease_operation = 'LeaseIdMismatchWithLeaseOperation'

lease_id_missing = 'LeaseIdMissing'

lease_is_already_broken = 'LeaseIsAlreadyBroken'

lease_is_breaking_and_cannot_be_acquired = 'LeaseIsBreakingAndCannotBeAcquired'

lease_is_breaking_and_cannot_be_changed = 'LeaseIsBreakingAndCannotBeChanged'

lease_is_broken_and_cannot_be_renewed = 'LeaseIsBrokenAndCannotBeRenewed'

lease_lost = 'LeaseLost'

lease_name_mismatch = 'LeaseNameMismatch'

lease_not_present_with_blob_operation = 'LeaseNotPresentWithBlobOperation'

lease_not_present_with_container_operation = 'LeaseNotPresentWithContainerOperation'

lease_not_present_with_lease_operation = 'LeaseNotPresentWithLeaseOperation'

max_blob_size_condition_not_met = 'MaxBlobSizeConditionNotMet'

md5_mismatch = 'Md5Mismatch'

message_not_found = 'MessageNotFound'

message_too_large = 'MessageTooLarge'

metadata_too_large = 'MetadataTooLarge'

missing_content_length_header = 'MissingContentLengthHeader'

missing_required_header = 'MissingRequiredHeader'

missing_required_query_parameter = 'MissingRequiredQueryParameter'

missing_required_xml_node = 'MissingRequiredXmlNode'

multiple_condition_headers_not_supported = 'MultipleConditionHeadersNotSupported'

no_pending_copy_operation = 'NoPendingCopyOperation'

operation_not_allowed_on_incremental_copy_blob = 'OperationNotAllowedOnIncrementalCopyBlob'

operation_timed_out = 'OperationTimedOut'

out_of_range_input = 'OutOfRangeInput'

out_of_range_query_parameter_value = 'OutOfRangeQueryParameterValue'

parent_not_found = 'ParentNotFound'

path_already_exists = 'PathAlreadyExists'

path_conflict = 'PathConflict'

path_not_found = 'PathNotFound'

pending_copy_operation = 'PendingCopyOperation'

pop_receipt_mismatch = 'PopReceiptMismatch'

previous_snapshot_cannot_be_newer = 'PreviousSnapshotCannotBeNewer'

previous_snapshot_not_found = 'PreviousSnapshotNotFound'

previous_snapshot_operation_not_supported = 'PreviousSnapshotOperationNotSupported'

queue_already_exists = 'QueueAlreadyExists'

queue_being_deleted = 'QueueBeingDeleted'

queue_disabled = 'QueueDisabled'

queue_not_empty = 'QueueNotEmpty'

queue_not_found = 'QueueNotFound'

read_only_attribute = 'ReadOnlyAttribute'

rename_destination_parent_path_not_found = 'RenameDestinationParentPathNotFound'

request_body_too_large = 'RequestBodyTooLarge'

request_url_failed_to_parse = 'RequestUrlFailedToParse'

resource_already_exists = 'ResourceAlreadyExists'

resource_not_found = 'ResourceNotFound'

resource_type_mismatch = 'ResourceTypeMismatch'

sequence_number_condition_not_met = 'SequenceNumberConditionNotMet'

sequence_number_increment_too_large = 'SequenceNumberIncrementTooLarge'

server_busy = 'ServerBusy'

share_already_exists = 'ShareAlreadyExists'

share_being_deleted = 'ShareBeingDeleted'

share_disabled = 'ShareDisabled'

share_has_snapshots = 'ShareHasSnapshots'

share_not_found = 'ShareNotFound'

share_snapshot_count_exceeded = 'ShareSnapshotCountExceeded'

share_snapshot_in_progress = 'ShareSnapshotInProgress'

share_snapshot_operation_not_supported = 'ShareSnapshotOperationNotSupported'

sharing_violation = 'SharingViolation'

snaphot_operation_rate_exceeded = 'SnaphotOperationRateExceeded'

snapshot_count_exceeded = 'SnapshotCountExceeded'

snapshots_present = 'SnapshotsPresent'

source_condition_not_met = 'SourceConditionNotMet'

source_path_is_being_deleted = 'SourcePathIsBeingDeleted'

source_path_not_found = 'SourcePathNotFound'

system_in_use = 'SystemInUse'

target_condition_not_met = 'TargetConditionNotMet'

unauthorized_blob_overwrite = 'UnauthorizedBlobOverwrite'

unsupported_header = 'UnsupportedHeader'

unsupported_http_verb = 'UnsupportedHttpVerb'

unsupported_query_parameter = 'UnsupportedQueryParameter'

unsupported_rest_version = 'UnsupportedRestVersion'

unsupported_xml_node = 'UnsupportedXmlNode'

class azure.storage.filedatalake.UserDelegationKey

Represents a user delegation key, provided to the user by Azure Storage based on their Azure Active Directory access token.

The fields are saved as simple strings since the user does not have to interact with this object; to generate an identify SAS, the user can simply pass it to the right API.

Variables

• signed_oid (str) – Object ID of this token.

• signed_tid (str) – Tenant ID of the tenant that issued this token.

• signed_start (str) – The datetime this token becomes valid.

• signed_expiry (str) – The datetime this token expires.

• signed_service (str) – What service this key is valid for.

• signed_version (str) – The version identifier of the REST service that created this token.

• value (str) – The user delegation key.

class azure.storage.filedatalake.FileSystemProperties

File System properties class.

Variables

• last_modified (datetime) – A datetime object representing the last time the file system was modified.

• etag (str) – The ETag contains a value that you can use to perform operations conditionally.

• lease (LeaseProperties) – Stores all the lease information for the file system.

• public_access (str) – Specifies whether data in the file system may be accessed publicly and the level of access.

• has_immutability_policy (bool) – Represents whether the file system has an immutability policy.

• has_legal_hold (bool) – Represents whether the file system has a legal hold.

• metadata (dict) – A dict with name-value pairs to associate with the file system as metadata.

Returned FileSystemProperties instances expose these values through a dictionary interface, for example: file_system_props["last_modified"]. Additionally, the file system name is available as file_system_props["name"].

class azure.storage.filedatalake.FileSystemPropertiesPaged(*args, **kwargs)

An Iterable of File System properties.

Variables

• service_endpoint (str) – The service URL.

• prefix (str) – A file system name prefix being used to filter the list.

• marker (str) – The continuation token of the current page of results.

• results_per_page (int) – The maximum number of results retrieved per API call.

• continuation_token (str) – The continuation token to retrieve the next page of results.

• location_mode (str) – The location mode being used to list results. The available options include “primary” and “secondary”.

• current_page (list(FileSystemProperties)) – The current page of listed results.

Parameters

• command (callable) – Function to retrieve the next page of items.

• prefix (str) – Filters the results to return only file systems whose names begin with the specified prefix.

• results_per_page (int) – The maximum number of file system names to retrieve per call.

• continuation_token (str) – An opaque continuation token.

Return an iterator of pages.

Parameters

• get_next – Callable that take the continuation token and return a HTTP response

• extract_data – Callable that take an HTTP response and return a tuple continuation token, list of ReturnType

• continuation_token (str) – The continuation token needed by get_next

next()

Return the next item from the iterator. When exhausted, raise StopIteration

class azure.storage.filedatalake.DirectoryProperties(**kwargs)

Variables

• name (str) – name of the directory

• etag (str) – The ETag contains a value that you can use to perform operations conditionally.

• deleted (bool) – if the current directory marked as deleted

• metadata (dict) – Name-value pairs associated with the blob as metadata.

• lease (LeaseProperties) – Stores all the lease information for the directory.

• last_modified (datetime) – A datetime object representing the last time the directory was modified.

• creation_time (datetime) – Indicates when the directory was created, in UTC.

• remaining_retention_days (int) – The number of days that the directory will be retained before being permanently deleted by the service.

• content_settings (ContentSettings) –

get(key, default=None)

has_key(k)

items()

keys()

update(*args, **kwargs)

values()

class azure.storage.filedatalake.PathProperties(**kwargs)

Path properties listed by get_paths api.

Variables

• name (str) – the full path for a file or directory.

• owner (str) – The owner of the file or directory.

• group (str) – he owning group of the file or directory.

• permissions (str) – Sets POSIX access permissions for the file owner, the file owning group, and others. Each class may be granted read, write, or execute permission. The sticky bit is also supported. Both symbolic (rwxrw-rw-) and 4-digit octal notation (e.g. 0766) are supported.

• last_modified (datetime) – A datetime object representing the last time the blob was modified.

• is_directory (bool) – is the path a directory or not.

• etag (str) – The ETag contains a value that you can use to perform operations conditionally.

• content_length – the size of file if the path is a file.

class azure.storage.filedatalake.PathPropertiesPaged(command, recursive, path=None, max_results=None, continuation_token=None, upn=None)

An Iterable of Path properties.

Variables

• path (str) – Filters the results to return only paths under the specified path.

• results_per_page (int) – The maximum number of results retrieved per API call.

• continuation_token (str) – The continuation token to retrieve the next page of results.

• current_page (list(PathProperties)) – The current page of listed results.

Parameters

• command (callable) – Function to retrieve the next page of items.

• path (str) – Filters the results to return only paths under the specified path.

• max_results (int) – The maximum number of psths to retrieve per call.

• continuation_token (str) – An opaque continuation token.

Return an iterator of pages.

Parameters

• get_next – Callable that take the continuation token and return a HTTP response

• extract_data – Callable that take an HTTP response and return a tuple continuation token, list of ReturnType

• continuation_token (str) – The continuation token needed by get_next

next()

Return the next item from the iterator. When exhausted, raise StopIteration

class azure.storage.filedatalake.LeaseProperties

DataLake Lease Properties.

Variables

• status (str) – The lease status of the file. Possible values: locked|unlocked

• state (str) – Lease state of the file. Possible values: available|leased|expired|breaking|broken

• duration (str) – When a file is leased, specifies whether the lease is of infinite or fixed duration.

get(key, default=None)

has_key(k)

items()

keys()

update(*args, **kwargs)

values()

class azure.storage.filedatalake.ContentSettings(content_type=None, content_encoding=None, content_language=None, content_disposition=None, cache_control=None, content_md5=None, **kwargs)

The content settings of a file or directory.

Variables

• content_type (str) – The content type specified for the file or directory. If no content type was specified, the default content type is application/octet-stream.

• content_encoding (str) – If the content_encoding has previously been set for the file, that value is stored.

• content_language (str) – If the content_language has previously been set for the file, that value is stored.

• content_disposition (str) – content_disposition conveys additional information about how to process the response payload, and also can be used to attach additional metadata. If content_disposition has previously been set for the file, that value is stored.

• cache_control (str) – If the cache_control has previously been set for the file, that value is stored.

• content_md5 (str) – If the content_md5 has been set for the file, this response header is stored so that the client can check for message content integrity.

get(key, default=None)

has_key(k)

items()

keys()

update(*args, **kwargs)

values()

class azure.storage.filedatalake.AccountSasPermissions(read=False, write=False, delete=False, list=False, create=False)

classmethod from_string(permission)

Create AccountSasPermissions from a string.

To specify read, write, delete, etc. permissions you need only to include the first letter of the word in the string. E.g. for read and write permissions you would provide a string “rw”.

Parameters

permission (str) – Specify permissions in the string with the first letter of the word.

Returns

A AccountSasPermissions object

Return type

AccountSasPermissions

class azure.storage.filedatalake.FileSystemSasPermissions(read=False, write=False, delete=False, list=False)

FileSystemSasPermissions class to be used with the generate_file_system_sas() function.

Parameters

• read (bool) – Read the content, properties, metadata etc.

• write (bool) – Create or write content, properties, metadata. Lease the file system.

• delete (bool) – Delete the file system.

• list (bool) – List paths in the file system.

classmethod from_string(permission)

Create a ContainerSasPermissions from a string.

To specify read, write, delete, or list permissions you need only to include the first letter of the word in the string. E.g. For read and write permissions, you would provide a string “rw”.

Parameters

permission (str) – The string which dictates the read, write, delete, and list permissions.

Returns

A ContainerSasPermissions object

Return type

ContainerSasPermissions

class azure.storage.filedatalake.DirectorySasPermissions(read=False, create=False, write=False, delete=False)

DirectorySasPermissions class to be used with the generate_directory_sas() function.

Parameters

• read (bool) – Read the content, properties, metadata etc.

• create (bool) – Create a new directory

• write (bool) – Create or write content, properties, metadata. Lease the directory.

• delete (bool) – Delete the directory.

classmethod from_string(permission)

Create a BlobSasPermissions from a string.

To specify read, add, create, write, or delete permissions you need only to include the first letter of the word in the string. E.g. For read and write permissions, you would provide a string “rw”.

Parameters

permission (str) – The string which dictates the read, add, create, write, or delete permissions.

Returns

A BlobSasPermissions object

Return type

BlobSasPermissions

class azure.storage.filedatalake.FileSasPermissions(read=False, create=False, write=False, delete=False)

FileSasPermissions class to be used with the generate_file_sas() function.

Parameters

• read (bool) – Read the content, properties, metadata etc. Use the file as the source of a read operation.

• create (bool) – Write a new file

• write (bool) – Create or write content, properties, metadata. Lease the file.

• delete (bool) – Delete the file.

classmethod from_string(permission)

Create a BlobSasPermissions from a string.

To specify read, add, create, write, or delete permissions you need only to include the first letter of the word in the string. E.g. For read and write permissions, you would provide a string “rw”.

Parameters

permission (str) – The string which dictates the read, add, create, write, or delete permissions.

Returns

A BlobSasPermissions object

Return type

BlobSasPermissions

azure.storage.filedatalake.generate_account_sas(account_name, account_key, resource_types, permission, expiry, start=None, ip=None, **kwargs)

Generates a shared access signature for the blob service.

Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.

Parameters

• account_name (str) – The storage account name used to generate the shared access signature.

• account_key (str) – The access key to generate the shared access signature.

• resource_types (str or ResourceTypes) – Specifies the resource types that are accessible with the account SAS.

• permission (str or AccountSasPermissions) – 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) – The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

• start (datetime or str) – The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

• 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 ip=168.1.5.65 or ip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses.

Keyword Arguments

protocol (str) – Specifies the protocol permitted for a request made. The default value is https.

Returns

A Shared Access Signature (sas) token.

Return type

str

Example:

azure.storage.filedatalake.generate_file_system_sas(account_name, file_system_name, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, ip=None, **kwargs)

Generates a shared access signature for a container.

Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.

Parameters

• account_name (str) – The storage account name used to generate the shared access signature.

• file_system_name (str) – The name of the file system.

• account_key (str) – The access key to generate the shared access signature. Either account_key or user_delegation_key must be specified.

• user_delegation_key (UserDelegationKey) – Instead of an account key, the user could pass in a user delegation key. A user delegation key can be obtained from the service by authenticating with an AAD identity; this can be accomplished by calling get_user_delegation_key(). When present, the SAS is signed with the user delegation key instead.

• permission (str or ContainerSasPermissions) – The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Permissions must be ordered read, 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) – The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

• start (datetime or str) – The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

• 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 ip=168.1.5.65 or ip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses.

Keyword Arguments

• protocol (str) – Specifies the protocol permitted for a request made. The default value is https.

• 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

Example:

azure.storage.filedatalake.generate_directory_sas(account_name, file_system_name, directory_name, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, ip=None, **kwargs)

Generates a shared access signature for a blob.

Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.

Parameters

• account_name (str) – The storage account name used to generate the shared access signature.

• container_name (str) – The name of the container.

• blob_name (str) – The name of the blob.

• snapshot (str) – An optional blob snapshot ID.

• account_key (str) – The access key to generate the shared access signature. Either account_key or user_delegation_key must be specified.

• user_delegation_key (UserDelegationKey) – Instead of an account key, the user could pass in a user delegation key. A user delegation key can be obtained from the service by authenticating with an AAD identity; this can be accomplished by calling get_user_delegation_key(). When present, the SAS is signed with the user delegation key instead.

• permission (str or BlobSasPermissions) – The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Permissions must be ordered read, 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) – The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

• start (datetime or str) – The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

• 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 ip=168.1.5.65 or ip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses.

Keyword Arguments

• protocol (str) – Specifies the protocol permitted for a request made. The default value is https.

• 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

azure.storage.filedatalake.generate_file_sas(account_name, file_system_name, directory_name, file_name, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, ip=None, **kwargs)

Generates a shared access signature for a blob.

Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.

Parameters

• account_name (str) – The storage account name used to generate the shared access signature.

• container_name (str) – The name of the container.

• blob_name (str) – The name of the blob.

• snapshot (str) – An optional blob snapshot ID.

• account_key (str) – The access key to generate the shared access signature. Either account_key or user_delegation_key must be specified.

• user_delegation_key (UserDelegationKey) – Instead of an account key, the user could pass in a user delegation key. A user delegation key can be obtained from the service by authenticating with an AAD identity; this can be accomplished by calling get_user_delegation_key(). When present, the SAS is signed with the user delegation key instead.

• permission (str or BlobSasPermissions) – The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Permissions must be ordered read, 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) – The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

• start (datetime or str) – The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

• 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 ip=168.1.5.65 or ip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses.

Keyword Arguments

• protocol (str) – Specifies the protocol permitted for a request made. The default value is https.

• 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