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.objectazure.storage.fileshare._shared.base_client_async.AsyncStorageAccountHostsMixinShareDirectoryClientazure.storage.fileshare._shared.base_client.StorageAccountHostsMixinazure.storage.fileshare._directory_client.ShareDirectoryClientShareDirectoryClient
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
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
close_handle
Close an open file handle.
close_handle(handle, **kwargs)
Parameters
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
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
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
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
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
The name of the file to delete.
Return type
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
The name of the subdirectory.
Return type
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
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
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
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
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
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)
Name-value pairs associated with the directory as metadata.
Returns
Directory-updated property dict (Etag and last modified).
Return type
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
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
Creation time for the file Default value: Preserve.
- file_last_write_time
- str or datetime
Last write time for the file Default value: Preserve.
- 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 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
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
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
The name of the file.
- data
- Any
Content of the file.
- length
- int
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)