ShareDirectoryClient Class

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 and get_file_client functions.

Inheritance

azure.storage.fileshare._shared.base_client_async.AsyncStorageAccountHostsMixin

ShareDirectoryClient

azure.storage.fileshare._directory_client.ShareDirectoryClient

ShareDirectoryClient

Constructor

ShareDirectoryClient(account_url: str, share_name: str, directory_path: str, snapshot: Optional[Union[str, Dict[str, Any]]] = None, credential: Optional[Any] = None, **kwargs: Optional[Any])

Parameters

account_url

str

Required

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

Required

The name of the share for the directory.

directory_path

str

Required

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

default value: None

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

credential

default value: None

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, an instance of a AzureSasCredential from azure.core.credentials or an account shared access key.

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.

New in version 12.1.0.

secondary_hostname

str

The hostname of the secondary endpoint.

loop

The event loop to run the asynchronous tasks.

max_range_size

int

The maximum range size used for a file upload. Defaults to 4*1024*1024.

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.
exists	Returns True if a directory exists and returns False otherwise.
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.
rename_directory	Rename the source directory. :paramtype file_attributes:~azure.storage.fileshare.NTFSAttributes or str :keyword file_creation_time: Creation time for the directory. :paramtype file_creation_time:~datetime.datetime or str :keyword file_last_write_time: Last write time for the file. :paramtype file_last_write_time:~datetime.datetime or str :keyword file_change_time: Change time for the directory. If not specified, change time will be set to the current date/time. New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.
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.

async close_all_handles(recursive: bool = False, **kwargs: Any) -> Dict[str, int]

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.

timeout

int

The timeout parameter is expressed in seconds.

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.

async close_handle(handle: Union[str, HandleItem], **kwargs: Any) -> Dict[str, int]

Parameters

handle

str or Handle

Required

A specific handle to close.

timeout

int

The timeout parameter is expressed in seconds.

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.

async create_directory(**kwargs: Any) -> Dict[str, Any]

Parameters

file_attributes

str or NTFSAttributes

The file system attributes for files and directories. If not set, the default value would be "none" and the attributes will be set to "Archive". Here is an example for when the var type is str: 'Temporary|Archive'. file_attributes value is not case sensitive.

file_creation_time

str or datetime

Creation time for the directory. Default value: "now".

file_last_write_time

str or datetime

Last write time for the directory. Default value: "now".

file_permission

str

If specified the permission (security descriptor) shall be set for the directory/file. This header can be used if Permission size is <= 8KB, else 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 file-permission or file-permission-key should be specified.

file_permission_key

str

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

file_change_time

str or datetime

Change time for the directory. If not specified, change time will be set to the current date/time.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.

metadata

dict(<xref:str,str>)

Name-value pairs associated with the directory as metadata.

timeout

int

The timeout parameter is expressed in seconds.

Returns

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

Return type

dict(str, <xref:Any>)

Examples

Creates a directory.

   await directory.create_directory()

create_subdirectory

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

async create_subdirectory(directory_name: str, **kwargs) -> azure.storage.fileshare.aio._directory_client_async.ShareDirectoryClient

Parameters

directory_name

str

Required

The name of the subdirectory.

metadata

dict(<xref:str,str>)

Name-value pairs associated with the subdirectory as metadata.

timeout

int

The timeout parameter is expressed in seconds.

Returns

ShareDirectoryClient

Return type

ShareDirectoryClient

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.

async delete_directory(**kwargs: Any) -> None

Parameters

timeout

int

The timeout parameter is expressed in seconds.

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.

async delete_file(file_name: str, **kwargs: Optional[Any]) -> None

Parameters

file_name

str

Required

The name of the file to delete.

timeout

int

The timeout parameter is expressed in seconds.

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.

async delete_subdirectory(directory_name: str, **kwargs) -> None

Parameters

directory_name

str

Required

The name of the subdirectory.

timeout

int

The timeout parameter is expressed in seconds.

Return type

None

Examples

Delete a subdirectory.

   await parent_dir.delete_subdirectory("subdir")

exists

Returns True if a directory exists and returns False otherwise.

async exists(**kwargs: Any) -> bool

Parameters

timeout

int

The timeout parameter is expressed in seconds.

Returns

True if the directory exists, False otherwise.

Return type

bool

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.

async get_directory_properties(**kwargs: Any) -> DirectoryProperties

Parameters

timeout

int

The timeout parameter is expressed in seconds.

Returns

DirectoryProperties

Return type

DirectoryProperties

get_file_client

Get a client to interact with a specific file.

The file need not already exist.

get_file_client(file_name: str, **kwargs: Any) -> azure.storage.fileshare.aio._file_client_async.ShareFileClient

Parameters

file_name

str

Required

The name of the file.

Returns

A File Client.

Return type

ShareFileClient

get_subdirectory_client

Get a client to interact with a specific subdirectory.

The subdirectory need not already exist.

get_subdirectory_client(directory_name: str, **kwargs: Any) -> azure.storage.fileshare.aio._directory_client_async.ShareDirectoryClient

Parameters

directory_name

str

Required

The name of the subdirectory.

Returns

A Directory Client.

Return type

ShareDirectoryClient

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: Optional[str] = None, **kwargs: Any) -> azure.core.async_paging.AsyncItemPaged

Parameters

name_starts_with

str

Required

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

include

list[str]

Include this parameter to specify one or more datasets to include in the response. Possible str values are "timestamps", "Etag", "Attributes", "PermissionKey".

New in version 12.6.0.

This keyword argument was introduced in API version '2020-10-02'.

include_extended_info

bool

If this is set to true, file id will be returned in listed results.

New in version 12.6.0.

This keyword argument was introduced in API version '2020-10-02'.

timeout

int

The timeout parameter is expressed in seconds.

Returns

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

Return type

AsyncItemPaged[<xref: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: bool = False, **kwargs: Any) -> azure.core.async_paging.AsyncItemPaged

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.

timeout

int

The timeout parameter is expressed in seconds.

Returns

An auto-paging iterable of HandleItem

Return type

AsyncItemPaged[HandleItem]

rename_directory

Rename the source directory.

:paramtype file_attributes:~azure.storage.fileshare.NTFSAttributes or str :keyword file_creation_time:

Creation time for the directory.

:paramtype file_creation_time:~datetime.datetime or str :keyword file_last_write_time:

Last write time for the file.

:paramtype file_last_write_time:~datetime.datetime or str :keyword file_change_time:

Change time for the directory. If not specified, change time will be set to the current date/time.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.

async rename_directory(new_name: str, **kwargs: Any) -> azure.storage.fileshare.aio._directory_client_async.ShareDirectoryClient

Parameters

metadata

<xref:Dict>[<xref:str,str>]

A name-value pair to associate with a file storage object.

destination_lease

ShareLeaseClient or str

Required if the destination file has an active lease. Value can be a ShareLeaseClient object or the lease ID as a string.

Returns

The new Directory Client.

Return type

ShareDirectoryClient

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.

async set_directory_metadata(metadata: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]

Parameters

metadata

dict(str, str)

Required

Name-value pairs associated with the directory as metadata.

timeout

int

The timeout parameter is expressed in seconds.

Returns

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

Return type

dict(str, <xref:Any>)

set_http_headers

Sets HTTP headers on the directory.

async set_http_headers(file_attributes: Union[str, NTFSAttributes] = 'none', file_creation_time: Optional[Union[str, datetime]] = 'preserve', file_last_write_time: Optional[Union[str, datetime]] = 'preserve', file_permission: Optional[str] = None, permission_key: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]

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.

file_change_time

str or datetime

Change time for the directory. If not specified, change time will be set to the current date/time.

New in version 12.8.0: This parameter was introduced in API version '2021-06-08'.

timeout

int

The timeout parameter is expressed in seconds.

Returns

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

Return type

dict(str, <xref:Any>)

upload_file

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

async upload_file(file_name: str, data: Any, length: Optional[int] = None, **kwargs: Any) -> azure.storage.fileshare.aio._file_client_async.ShareFileClient

Parameters

file_name

str

Required

The name of the file.

data

<xref:Any>

Required

Content of the file.

length

int

Required

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

metadata

dict(<xref:str,str>)

Name-value pairs associated with the file as metadata.

content_settings

ContentSettings

ContentSettings object used to set file properties. Used to set content type, encoding, language, disposition, md5, and cache control.

validate_content

bool

If true, calculates an MD5 hash for each range of the file. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the file.

max_concurrency

int

Maximum number of parallel connections to use.

progress_hook

<xref:Callable>[[int, <xref:Optional>[int]], <xref:Awaitable>[None]]

An async callback to track the progress of a long running upload. The signature is function(current: int, total: Optional[int]) where current is the number of bytes transferred so far, and total is the size of the blob or None if the size is unknown.

timeout

int

The timeout parameter is expressed in seconds.

encoding

str

Defaults to UTF-8.

Returns

ShareFileClient

Return type

ShareFileClient

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)