ShareDirectoryClient class

Definition

A client to interact with a specific directory, although it may not yet exist.

For operations relating to a specific subdirectory or file in this share, the clients for those entities can also be retrieved using the get_subdirectory_client(directory_name, **kwargs) and get_file_client(file_name, **kwargs) functions.

ShareDirectoryClient(account_url, share_name, directory_path, snapshot=None, credential=None, **kwargs)
Inheritance
builtins.object
azure.storage.fileshare._shared.base_client_async.AsyncStorageAccountHostsMixin
ShareDirectoryClient
azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin
azure.storage.fileshare._directory_client.ShareDirectoryClient
ShareDirectoryClient

Parameters

account_url
str

The URI to the storage account. In order to create a client given the full URI to the directory, use the <xref:azure.storage.fileshare.aio.from_directory_url> classmethod.

share_name
str

The name of the share for the directory.

directory_path
str

The directory path for the directory with which to interact. If specified, this value will override a directory value specified in the directory URL.

snapshot
str

An optional share snapshot on which to operate. This can be the snapshot ID string or the response returned from <xref:ShareClient.create_snapshot>.

credential

The credential with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string or an account shared access key.

Methods

close_all_handles

Close any open file handles.

This operation will block until the service has closed all open handles.

close_handle

Close an open file handle.

create_directory

Creates a new directory under the directory referenced by the client.

create_subdirectory

Creates a new subdirectory and returns a client to interact with the subdirectory.

delete_directory

Marks the directory for deletion. The directory is later deleted during garbage collection.

delete_file

Marks the specified file for deletion. The file is later deleted during garbage collection.

delete_subdirectory

Deletes a subdirectory.

get_directory_properties

Returns all user-defined metadata and system properties for the specified directory. The data returned does not include the directory's list of files.

get_file_client

Get a client to interact with a specific file.

The file need not already exist.

get_subdirectory_client

Get a client to interact with a specific subdirectory.

The subdirectory need not already exist.

list_directories_and_files

Lists all the directories and files under the directory.

list_handles

Lists opened handles on a directory or a file under the directory.

set_directory_metadata

Sets the metadata for the directory.

Each call to this operation replaces all existing metadata attached to the directory. To remove all metadata from the directory, call this operation with an empty metadata dict.

set_http_headers

Sets HTTP headers on the directory.

upload_file

Creates a new file in the directory and returns a ShareFileClient to interact with the file.

close_all_handles

Close any open file handles.

This operation will block until the service has closed all open handles.

close_all_handles(recursive=False, **kwargs)

Parameters

recursive
bool
Required

Boolean that specifies if operation should apply to the directory specified by the client, its files, its subdirectories and their files. Default value is False.

Returns

The number of handles closed (this may be 0 if the specified handle was not found) and the number of handles failed to close in a dict.

Return type

dict[str, int]

close_handle

Close an open file handle.

close_handle(handle, **kwargs)

Parameters

handle
str or Handle
Required

A specific handle to close.

Returns

The number of handles closed (this may be 0 if the specified handle was not found) and the number of handles failed to close in a dict.

Return type

dict[str, int]

create_directory

Creates a new directory under the directory referenced by the client.

create_directory(**kwargs)

Returns

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

Return type

dict(str, Any)

Examples

Creates a directory.


   await directory.create_directory()

create_subdirectory

Creates a new subdirectory and returns a client to interact with the subdirectory.

create_subdirectory(directory_name, **kwargs)

Parameters

directory_name
str
Required

The name of the subdirectory.

Returns

ShareDirectoryClient

Return type

Examples

Create a subdirectory.


   # Create the directory
   await parent_dir.create_directory()

   # Create a subdirectory
   subdir = await parent_dir.create_subdirectory("subdir")

delete_directory

Marks the directory for deletion. The directory is later deleted during garbage collection.

delete_directory(**kwargs)

Return type

None

Examples

Deletes a directory.


   await directory.delete_directory()

delete_file

Marks the specified file for deletion. The file is later deleted during garbage collection.

delete_file(file_name, **kwargs)

Parameters

file_name
str
Required

The name of the file to delete.

Return type

None

Examples

Delete a file in a directory.


   # Delete the file in the directory
   await directory.delete_file(file_name="sample")

delete_subdirectory

Deletes a subdirectory.

delete_subdirectory(directory_name, **kwargs)

Parameters

directory_name
str
Required

The name of the subdirectory.

Return type

None

Examples

Delete a subdirectory.


   await parent_dir.delete_subdirectory("subdir")

get_directory_properties

Returns all user-defined metadata and system properties for the specified directory. The data returned does not include the directory's list of files.

get_directory_properties(**kwargs)

Returns

DirectoryProperties

Return type

get_file_client

Get a client to interact with a specific file.

The file need not already exist.

get_file_client(file_name, **kwargs)

Parameters

file_name
str
Required

The name of the file.

Returns

A File Client.

Return type

get_subdirectory_client

Get a client to interact with a specific subdirectory.

The subdirectory need not already exist.

get_subdirectory_client(directory_name, **kwargs)

Parameters

directory_name
str
Required

The name of the subdirectory.

Returns

A Directory Client.

Return type

Examples

Gets the subdirectory client.


   # Get a directory client and create the directory
   parent = share.get_directory_client("dir1")
   await parent.create_directory()

   # Get a subdirectory client and create the subdirectory "dir1/dir2"
   subdirectory = parent.get_subdirectory_client("dir2")
   await subdirectory.create_directory()

list_directories_and_files

Lists all the directories and files under the directory.

list_directories_and_files(name_starts_with=None, **kwargs)

Parameters

name_starts_with
str
Required

Filters the results to return only entities whose names begin with the specified prefix.

Returns

An auto-paging iterable of dict-like DirectoryProperties and FileProperties

Return type

AsyncItemPaged[DirectoryProperties and FileProperties]

Examples

List directories and files.


   # List the directories and files under the parent directory
   my_list = []
   async for item in parent_dir.list_directories_and_files():
       my_list.append(item)
   print(my_list)

list_handles

Lists opened handles on a directory or a file under the directory.

list_handles(recursive=False, **kwargs)

Parameters

recursive
bool
Required

Boolean that specifies if operation should apply to the directory specified by the client, its files, its subdirectories and their files. Default value is False.

Returns

An auto-paging iterable of HandleItem

Return type

set_directory_metadata

Sets the metadata for the directory.

Each call to this operation replaces all existing metadata attached to the directory. To remove all metadata from the directory, call this operation with an empty metadata dict.

set_directory_metadata(metadata, **kwargs)

Parameters

metadata
dict(str, str)
Required

Name-value pairs associated with the directory as metadata.

Returns

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

Return type

dict(str, Any)

set_http_headers

Sets HTTP headers on the directory.

set_http_headers(file_attributes='none', file_creation_time='preserve', file_last_write_time='preserve', file_permission=None, permission_key=None, **kwargs)

Parameters

file_attributes
str or NTFSAttributes
Required

The file system attributes for files and directories. If not set, indicates preservation of existing values. Here is an example for when the var type is str: 'Temporary|Archive'

file_creation_time
str or datetime
Required

Creation time for the file Default value: Preserve.

file_last_write_time
str or datetime
Required

Last write time for the file Default value: Preserve.

file_permission
str
Required

If specified the permission (security descriptor) shall be set for the directory/file. This header can be used if Permission size is <= 8KB, else x-ms-file-permission-key header shall be used. Default value: Inherit. If SDDL is specified as input, it must have owner, group and dacl. Note: Only one of the x-ms-file-permission or x-ms-file-permission-key should be specified.

permission_key
str
Required

Key of the permission to be set for the directory/file. Note: Only one of the x-ms-file-permission or x-ms-file-permission-key should be specified.

Returns

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

Return type

dict(str, Any)

upload_file

Creates a new file in the directory and returns a ShareFileClient to interact with the file.

upload_file(file_name, data, length=None, **kwargs)

Parameters

file_name
str
Required

The name of the file.

data
Any
Required

Content of the file.

length
int
Required

Length of the file in bytes. Specify its maximum size, up to 1 TiB.

Returns

ShareFileClient

Return type

Examples

Upload a file to a directory.


   # Upload a file to the directory
   with open(SOURCE_FILE, "rb") as source:
       await directory.upload_file(file_name="sample", data=source)