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.
ivar str url: The full endpoint URL to the file system, including SAS token if used.
ivar str primary_endpoint: The full primary endpoint URL.
ivar str primary_hostname: The hostname of the primary endpoint.
param str account_url: The URI to the storage account.
param file_system_name: The file system for the directory or files.
type file_system_name: str
param 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.
FileSystemClient(account_url, file_system_name, credential=None, **kwargs)
- Inheritance
-
builtins.objectazure.storage.filedatalake._shared.base_client_async.AsyncStorageAccountHostsMixinFileSystemClientazure.storage.filedatalake._shared.base_client.StorageAccountHostsMixinazure.storage.filedatalake._file_system_client.FileSystemClientFileSystemClient
Examples
Get a FileSystemClient from an existing DataLakeServiceClient.
# Instantiate a DataLakeServiceClient using a connection string
from azure.storage.filedatalake.aio import DataLakeServiceClient
datalake_service_client = DataLakeServiceClient.from_connection_string(self.connection_string)
async with datalake_service_client:
# Instantiate a FileSystemClient
file_system_client = datalake_service_client.get_file_system_client("mynewfilesystems")
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 in the file system.
|
| 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. |
| 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
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.
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 = await file_system_client.acquire_lease()
# Delete file system by passing in the lease
await 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
The directory with which to interact. This can either be the name of the directory, or an instance of DirectoryProperties.
- metadata
- dict(str, str)
Name-value pairs associated with the file as metadata.
Returns
DataLakeDirectoryClient
Examples
Create directory in the file system.
directory_client = await file_system_client.create_directory("mydirectory")
create_file
Create file
create_file(file, **kwargs)
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.
- metadata
- dict(str, str)
Name-value pairs associated with the file as metadata.
Returns
DataLakeFileClient
Examples
Create file in the file system.
file_client = await 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)
A dict with name-value pairs to associate with the file system as metadata. Example: {'Category':'test'}
- public_access
- PublicAccess
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.
await file_system_client.create_file_system()
delete_directory
Marks the specified path for deletion.
delete_directory(directory, **kwargs)
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
DataLakeDirectoryClient
Examples
Delete directory in the file system.
await file_system_client.delete_directory("mydirectory")
delete_file
Marks the specified file for deletion.
Delete file in the file system.
await file_system_client.delete_file("myfile")
delete_file(file, **kwargs)
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.
Returns
DataLakeFileClient
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
Examples
Deleting a file system in the datalake service.
await file_system_client.delete_file_system()
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
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
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)
Returns
Access policy information in a dict.
Return type
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 = await 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
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.
Returns
An iterable (auto-paging) response of PathProperties.
Return type
Examples
List the blobs in the file system.
path_list = file_system_client.get_paths()
async 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]
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
To specify whether data in the file system may be accessed publicly and the level of access.
Returns
filesystem-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]
A dict containing name-value pairs to associate with the file system as metadata. Example: {'category':'test'}
Returns
file system-updated property dict (Etag and last modified).
Examples
Setting metadata on the container.
# Create key, value pairs for metadata
metadata = {'type': 'test'}
# Set metadata on the file system
await file_system_client.set_file_system_metadata(metadata=metadata)