FileSystemClient Class

Reference

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: str, file_system_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)

Parameters

Name	Description
account_url Required	str The URI to the storage account.
file_system_name Required	str The file system for the directory or files.
credential	AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None 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 or AzureNamedKeyCredential 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. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key. Default value: None

Keyword-Only Parameters

Name	Description
api_version	str The Storage API version to use for requests. Default value is the most recent service version that is compatible with the current SDK. Setting to an older version may result in reduced feature compatibility.
audience	str The audience to use when requesting tokens for Azure Active Directory authentication. Only has an effect when credential is of type TokenCredential. The value could be https://storage.azure.com/ (default) or https://.blob.core.windows.net.

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

Name	Description
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.
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: int = -1, lease_id: str | None = None, **kwargs) -> DataLakeLeaseClient

Parameters

Name	Description
lease_duration Required	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 Required	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-Only Parameters

Name	Description
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

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

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() -> None

Keyword-Only Parameters

Name	Description
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

create_directory

Create directory

create_directory(directory: DirectoryProperties | str, metadata: Dict[str, str] | None = None, **kwargs) -> DataLakeDirectoryClient

Parameters

Name	Description
directory Required	str or DirectoryProperties The directory with which to interact. This can either be the name of the directory, or an instance of DirectoryProperties.
metadata Required	dict(str, str) Name-value pairs associated with the file as metadata.

Keyword-Only Parameters

Name	Description
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).
owner	str The owner of the file or directory.
group	str The owning group of the file or directory.
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]".
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.
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.
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
DataLakeDirectoryClient	DataLakeDirectoryClient with new directory and metadata.

Examples

Create directory in the file system.


   directory_client = file_system_client.create_directory("mydirectory")

create_file

Create file

create_file(file: FileProperties | str, **kwargs) -> DataLakeFileClient

Parameters

Name	Description
file Required	str or FileProperties The file with which to interact. This can either be the name of the file, or an instance of FileProperties.

Keyword-Only Parameters

Name	Description
content_settings	ContentSettings ContentSettings object used to set path properties.
metadata	dict[str, str] 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).
owner	str The owner of the file or directory.
group	str The owning group of the file or directory.
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]".
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.
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.
expires_on	datetime or int The time to set the file to expiry. If the type of expires_on is an int, expiration time will be set as the number of milliseconds elapsed from creation time. If the type of expires_on is datetime, expiration time will be set absolute to the time provided. If no time zone info is provided, this will be interpreted as UTC.
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
DataLakeFileClient	DataLakeFileClient with new file created.

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: Dict[str, str] | None = None, public_access: PublicAccess | None = None, **kwargs) -> Dict[str, str | datetime]

Parameters

Name	Description
metadata Required	dict(str, str) A dict with name-value pairs to associate with the file system as metadata. Example: {'Category':'test'}
public_access Required	PublicAccess To specify whether data in the file system may be accessed publicly and the level of access.

Keyword-Only Parameters

Name	Description
encryption_scope_options	dict or EncryptionScopeOptions Specifies the default encryption scope to set on the file system and use for all future writes. New in version 12.9.0.
timeout	int Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
dict[str, Union[str, datetime]]	A dictionary of response headers.

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: DirectoryProperties | str, **kwargs) -> DataLakeDirectoryClient

Parameters

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

Keyword-Only Parameters

Name	Description
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
DataLakeDirectoryClient	DataLakeDirectoryClient after deleting specified directory.

Examples

Delete directory in the file system.


   file_system_client.delete_directory("mydirectory")

delete_file

Marks the specified file for deletion.

delete_file(file: FileProperties | str, **kwargs) -> DataLakeFileClient

Parameters

Name	Description
file Required	str or FileProperties The file with which to interact. This can either be the name of the file, or an instance of FileProperties.

Keyword-Only Parameters

Name	Description
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
<xref:azure.storage.file.datalake.DataLakeFileClient>	DataLakeFileClient after deleting specified file.

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: Any) -> None

Keyword-Only Parameters

Name	Description
lease	str or 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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
None

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: Any) -> bool

Keyword-Only Parameters

Name	Description
timeout	int Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
bool	True if a file system exists, False otherwise.

from_connection_string

Create FileSystemClient from a Connection String.

from_connection_string(conn_str: str, file_system_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parameters

Name	Description
conn_str Required	str A connection string to an Azure Storage account.
file_system_name Required	str The name of file system to interact with.
credential	AzureNamedKeyCredential or AzureSasCredential or TokenCredential or str or dict[str, str] or None 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 or AzureNamedKeyCredential 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. If using an instance of AzureNamedKeyCredential, "name" should be the storage account name, and "key" should be the storage account key. Default value: None

Keyword-Only Parameters

Name	Description
audience	str The audience to use when requesting tokens for Azure Active Directory authentication. Only has an effect when credential is of type TokenCredential. The value could be https://storage.azure.com/ (default) or https://.blob.core.windows.net.

Returns

Type	Description
FileSystemClient	A FileSystemClient.

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: DirectoryProperties | str) -> DataLakeDirectoryClient

Parameters

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

Keyword-Only Parameters

Name	Description
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
DataLakeDirectoryClient	A DataLakeDirectoryClient.

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: FileProperties | str) -> DataLakeFileClient

Parameters

Name	Description
file_path Required	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

Keyword-Only Parameters

Name	Description
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
DataLakeFileClient	A 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: Any) -> Dict[str, Any]

Keyword-Only Parameters

Name	Description
lease	DataLakeLeaseClient or str If specified, the operation only succeeds if the file system's lease is active and matches this ID.
timeout	int Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
dict[str, Any]	Access policy information in a dict.

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: Any) -> FileSystemProperties

Keyword-Only Parameters

Name	Description
lease	str or DataLakeLeaseClient If specified, get_file_system_properties only succeeds if the file system's lease is active and matches this ID.
timeout	int Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
FileSystemProperties	Properties for the specified file system within a file system object.

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: str | None = None, recursive: bool | None = True, max_results: int | None = None, **kwargs: Any) -> ItemPaged[PathProperties]

Parameters

Name	Description
path Required	str Filters the results to return only paths under the specified path.
recursive Required	Optional[bool] Optional. Set True for recursive, False for iterative.
max_results Required	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-Only Parameters

Name	Description
upn	bool 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 in the owner, group, and acl fields of PathProperties. 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 translate because they do not have unique friendly names.
timeout	int Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Name

Description

upn

bool

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 in the owner, group, and acl fields of PathProperties. 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 translate because they do not have unique friendly names.

timeout

int

Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
ItemPaged[PathProperties]	An iterable (auto-paging) response of PathProperties.

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: Any) -> ItemPaged[DeletedPathProperties]

Keyword-Only Parameters

Name	Description
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
ItemPaged[DeletedPathProperties]	An iterable (auto-paging) response of DeletedPathProperties.

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: Dict[str, AccessPolicy], public_access: str | PublicAccess | None = None, **kwargs) -> Dict[str, str | datetime]

Parameters

Name	Description
signed_identifiers Required	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 Required	PublicAccess To specify whether data in the file system may be accessed publicly and the level of access.

Keyword-Only Parameters

Name	Description
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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
dict[str, str], dict[str, datetime]	File System-updated property dict (Etag and last modified).

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: Dict[str, str], **kwargs) -> Dict[str, str | datetime]

Parameters

Name	Description
metadata Required	dict[str, str] A dict containing name-value pairs to associate with the file system as metadata. Example: {'category':'test'}

Keyword-Only Parameters

Name	Description
lease	str or DataLakeLeaseClient 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 Sets the server-side timeout for the operation in seconds. For more details see https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. This value is not tracked or validated on the client. To configure client-side network timesouts see here.

Returns

Type	Description
dict[str, str], dict[str, datetime]	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)

Attributes

api_version

The version of the Storage API used for requests.

Returns

Type	Description
str

location_mode

The location mode that the client is currently using.

By default this will be "primary". Options include "primary" and "secondary".

Returns

Type	Description
str

primary_endpoint

The full primary endpoint URL.

Returns

Type	Description
str

primary_hostname

The hostname of the primary endpoint.

Returns

Type	Description
str

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.

Returns

Type	Description
str

Exceptions

Type	Description
ValueError

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.

Returns

Type	Description
Optional[str]

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. :returns: The full endpoint URL to this entity, including SAS token if used. :rtype: str

Share via

FileSystemClient Class

Constructor

Parameters

Keyword-Only Parameters

Examples

Variables

Methods

acquire_lease

Parameters

Keyword-Only Parameters

Returns

Examples

close

Keyword-Only Parameters

create_directory

Parameters

Keyword-Only Parameters

Returns

Examples

create_file

Parameters

Keyword-Only Parameters

Returns

Examples

create_file_system

Parameters

Keyword-Only Parameters

Returns

Examples

delete_directory

Parameters

Keyword-Only Parameters

Returns

Examples

delete_file

Parameters

Keyword-Only Parameters

Returns

Examples

delete_file_system

Keyword-Only Parameters

Returns

Examples

exists

Keyword-Only Parameters

Returns

from_connection_string

Parameters

Keyword-Only Parameters

Returns

Examples

get_directory_client

Parameters

Keyword-Only Parameters

Returns

Examples

get_file_client

Parameters

Keyword-Only Parameters

Returns

Examples

get_file_system_access_policy

Keyword-Only Parameters

Returns

get_file_system_properties

Keyword-Only Parameters

Returns

Examples

get_paths

Parameters

Keyword-Only Parameters

Returns

Examples

list_deleted_paths

Keyword-Only Parameters

Returns

set_file_system_access_policy

Parameters

Keyword-Only Parameters