FileSystemClient class

Definition

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(directory) or get_file_client(file_path) functions.

FileSystemClient(account_url, file_system_name, credential=None, **kwargs)
Inheritance
builtins.object
azure.storage.filedatalake._shared.base_client.StorageAccountHostsMixin
FileSystemClient

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.

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.

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.

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.

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.

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.

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.

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.

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.

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)

Return type

None

Examples

Deleting a file system in the datalake service.


   file_system_client.delete_file_system()

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

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

azure.storage.filedatalake..DataLakeFileClient

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)

Returns

Access policy information in a dict.

Return type

dict[str, 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)

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.

max_results
default value: None

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

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.

Returns

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

Return type

dict[str, str
datetime.datetime]

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'}

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)