DataLakeDirectoryClient Class

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.

Inheritance
azure.storage.filedatalake._path_client.PathClient
DataLakeDirectoryClient

Constructor

DataLakeDirectoryClient(account_url, file_system_name, directory_name, credential=None, **kwargs)

Parameters

account_url
str
Required

The URI to the storage account.

file_system_name
str
Required

The file system for the directory or files.

directory_name
str
Required

The whole path of the directory. eg. {directory under file system}/{directory to interact with}

credential
Required

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, an instance of a AzureSasCredential from azure.core.credentials, and account shared access key, or an instance of a TokenCredentials class from azure.identity. If the resource URI already contains a SAS token, this will be ignored in favor of an explicit credential

  • except in the case of AzureSasCredential, where the conflicting SAS tokens will raise a ValueError.

Examples

Creating the DataLakeServiceClient from connection string.


   from azure.storage.filedatalake import DataLakeDirectoryClient
   DataLakeDirectoryClient.from_connection_string(connection_string, "myfilesystem", "mydirectory")

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.

Methods

create_directory

Create a new directory.

create_file

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

create_sub_directory

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

delete_directory

Marks the specified directory for deletion.

delete_sub_directory

Marks the specified subdirectory for deletion.

exists

Returns True if a directory exists and returns False otherwise.

from_connection_string

Create DataLakeDirectoryClient from a Connection String.

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

get_directory_properties

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

get_file_client

Get a client to interact with the specified file.

The file need not already exist.

get_sub_directory_client

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

The sub subdirectory need not already exist.

rename_directory

Rename the source directory.

create_directory

Create a new directory.

create_directory(metadata=None, **kwargs)

Parameters

metadata
dict(str, str)
default value: None

Name-value pairs associated with the file as metadata.

content_settings
ContentSettings

ContentSettings object used to set path properties.

lease
DataLakeLeaseClient or str

Required if the file 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).

Examples

Create directory.


   directory_client.create_directory()

create_file

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

create_file(file, **kwargs)

Parameters

file
str or FileProperties
Required

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

Name-value pairs associated with the file as metadata.

lease
DataLakeLeaseClient or str

Required if the file 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

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

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

Parameters

sub_directory
str or DirectoryProperties
Required

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

metadata
dict(str, str)
default value: None

Name-value pairs associated with the file as metadata.

content_settings
ContentSettings

ContentSettings object used to set path properties.

lease
DataLakeLeaseClient or str

Required if the file 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

Marks the specified directory for deletion.

delete_directory(**kwargs)

Parameters

lease
DataLakeLeaseClient or str

Required if the file 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

Examples

Delete directory.


   new_directory.delete_directory()

delete_sub_directory

Marks the specified subdirectory for deletion.

delete_sub_directory(sub_directory, **kwargs)

Parameters

sub_directory
str or DirectoryProperties
Required

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

lease
DataLakeLeaseClient or str

Required if the file 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

exists

Returns True if a directory exists and returns False otherwise.

exists(**kwargs)

Parameters

timeout
int

The timeout parameter is expressed in seconds.

Returns

boolean

from_connection_string

Create DataLakeDirectoryClient from a Connection String.

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

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

Parameters

conn_str
str
Required

A connection string to an Azure Storage account.

file_system_name
str
Required

The name of file system to interact with.

directory_name
str
Required

The name of directory to interact with. The directory is under file system.

credential
Required

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, an instance of a AzureSasCredential from azure.core.credentials, 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.

credential
default value: None

get_directory_properties

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

get_directory_properties(**kwargs)

Parameters

lease
DataLakeLeaseClient or str

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

<xref:DirectoryProperties>

Examples

Getting the properties for a file/directory.


   props = new_directory.get_directory_properties()

get_file_client

Get a client to interact with the specified file.

The file need not already exist.

get_file_client(file)

Parameters

file
str or FileProperties
Required

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

get_sub_directory_client

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

The sub subdirectory need not already exist.

get_sub_directory_client(sub_directory)

Parameters

sub_directory
str or DirectoryProperties
Required

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

rename_directory

Rename the source directory.

rename_directory(new_name, **kwargs)

Parameters

new_name
str
Required

the new directory name the user want to rename to. The value must have the following format: "{filesystem}/{directory}/{subdirectory}".

source_lease
DataLakeLeaseClient or str

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

lease
DataLakeLeaseClient or str

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.

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

Examples

Rename the source directory.


   new_dir_name = "testdir2"
   print("Renaming the directory named '{}' to '{}'.".format(dir_name, new_dir_name))
   new_directory = directory_client\
       .rename_directory(new_name=directory_client.file_system_name + '/' + new_dir_name)