FileSystemClient Class

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.

Inheritance
azure.storage.filedatalake._shared.base_client.StorageAccountHostsMixin
FileSystemClient

Constructor

FileSystemClient(account_url, file_system_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.

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, an 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

Get a FileSystemClient from an existing DataLakeServiceClient.


   # Instantiate a DataLakeServiceClient using a connection string
   from azure.storage.filedatalake import DataLakeServiceClient
   datalake_service_client = DataLakeServiceClient.from_connection_string(self.connection_string)

   # Instantiate a FileSystemClient
   file_system_client = datalake_service_client.get_file_system_client("mynewfilesystem")

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

acquire_lease

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.

close

This method is to close the sockets opened by the client. It need not be used when using with a context manager.

create_directory

Create directory

create_file

Create file

create_file_system

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.

delete_directory

Marks the specified path for deletion.

delete_file

Marks the specified file for deletion.

delete_file_system

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.

exists

Returns True if a file system exists and returns False otherwise.

from_connection_string

Create FileSystemClient from a Connection String.

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

get_directory_client

Get a client to interact with the specified directory.

The directory need not already exist.

get_file_client

Get a client to interact with the specified file.

The file need not already exist.

get_file_system_access_policy

Gets the permissions for the specified file system. The permissions indicate whether file system data may be accessed publicly.

get_file_system_properties

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.

get_paths

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.

list_deleted_paths

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

New in version 12.4.0: This operation was introduced in API version '2020-06-12'.

set_file_system_access_policy

Sets the permissions for the specified file system or stored access policies that may be used with Shared Access Signatures. The permissions indicate whether files in a file system may be accessed publicly.

set_file_system_metadata

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.

acquire_lease

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.

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

Parameters

lease_duration
int
default value: -1

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

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.

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

Examples

Acquiring a lease on the file system.


   # Acquire a lease on the file system
   lease = file_system_client.acquire_lease()

   # Delete file system by passing in the lease
   file_system_client.delete_file_system(lease=lease)

close

This method is to close the sockets opened by the client. It need not be used when using with a context manager.

close()

create_directory

Create directory

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

Parameters

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

Examples

Create directory in the file system.


   directory_client = file_system_client.create_directory("mydirectory")

create_file

Create file

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
Required

ContentSettings object used to set path properties.

metadata
dict(str, str)
Required

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

Examples

Create file in the file system.


   file_client = file_system_client.create_file("myfile")

create_file_system

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.

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

Parameters

metadata
dict(str, str)
default value: None

A dict with name-value pairs to associate with the file system as metadata. Example: {'Category':'test'}

public_access
PublicAccess
default value: None

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

timeout
int

The timeout parameter is expressed in seconds.

Return type

Examples

Creating a file system in the datalake service.


   file_system_client.create_file_system()

delete_directory

Marks the specified path for deletion.

delete_directory(directory, **kwargs)

Parameters

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

Examples

Delete directory in the file system.


   file_system_client.delete_directory("mydirectory")

delete_file

Marks the specified file for deletion.

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

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

DataLakeFileClient

Examples

Delete file in the file system.


   file_system_client.delete_file("myfile")

delete_file_system

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.

delete_file_system(**kwargs)

Parameters

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

Examples

Deleting a file system in the datalake service.


   file_system_client.delete_file_system()

exists

Returns True if a file system exists and returns False otherwise.

exists(**kwargs)

Parameters

timeout
int

The timeout parameter is expressed in seconds.

Returns

boolean

from_connection_string

Create FileSystemClient from a Connection String.

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

from_connection_string(conn_str, file_system_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.

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, an 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

Examples

Create FileSystemClient from connection string


   from azure.storage.filedatalake import FileSystemClient
   file_system_client = FileSystemClient.from_connection_string(self.connection_string, "filesystem")

get_directory_client

Get a client to interact with the specified directory.

The directory need not already exist.

get_directory_client(directory)

Parameters

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

Examples

Getting the directory client to interact with a specific directory.


   # Get the DataLakeDirectoryClient from the FileSystemClient to interact with a specific file
   directory_client = file_system_client.get_directory_client("mynewdirectory")

get_file_client

Get a client to interact with the specified file.

The file need not already exist.

get_file_client(file_path)

Parameters

file_path
str or FileProperties
Required

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

Examples

Getting the file client to interact with a specific file.


   # Get the FileClient from the FileSystemClient to interact with a specific file
   file_client = file_system_client.get_file_client("mynewfile")

get_file_system_access_policy

Gets the permissions for the specified file system. The permissions indicate whether file system data may be accessed publicly.

get_file_system_access_policy(**kwargs)

Parameters

lease
DataLakeLeaseClient or str

If specified, the operation only succeeds if the file system's lease is active and matches this ID.

timeout
int

The timeout parameter is expressed in seconds.

Returns

Access policy information in a dict.

Return type

dict[str, <xref:Any>]

get_file_system_properties

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.

get_file_system_properties(**kwargs)

Parameters

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

Examples

Getting properties on the file system.


   properties = file_system_client.get_file_system_properties()

get_paths

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.

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

Parameters

path
str
default value: None

Filters the results to return only paths under the specified path.

max_results
int
default value: True

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.

upn
default value: None

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

Examples

List the paths in the file system.


   path_list = file_system_client.get_paths()
   for path in path_list:
       print(path.name + '\n')

list_deleted_paths

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

New in version 12.4.0: This operation was introduced in API version '2020-06-12'.

list_deleted_paths(**kwargs)

Parameters

path_prefix
str

Filters the results to return only paths under the specified path.

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

timeout
int

The timeout parameter is expressed in seconds.

Returns

An iterable (auto-paging) response of DeletedPathProperties.

Return type

set_file_system_access_policy

Sets the permissions for the specified file system or stored access policies that may be used with Shared Access Signatures. The permissions indicate whether files in a file system may be accessed publicly.

set_file_system_access_policy(signed_identifiers, public_access=None, **kwargs)

Parameters

signed_identifiers
dict[str, AccessPolicy]
Required

A dictionary of access policies to associate with the file system. The dictionary may contain up to 5 elements. An empty dictionary will clear the access policies set on the service.

public_access
PublicAccess
default value: None

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

lease
DataLakeLeaseClient or str

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

File System-updated property dict (Etag and last modified).

Return type

set_file_system_metadata

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.

set_file_system_metadata(metadata, **kwargs)

Parameters

metadata
dict[str, str]
Required

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

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

filesystem-updated property dict (Etag and last modified).

Examples

Setting metadata on the file system.


   # Create key, value pairs for metadata
   metadata = {'type': 'test'}

   # Set metadata on the file system
   file_system_client.set_file_system_metadata(metadata=metadata)