ShareClient Class

A client to interact with a specific share, although that share may not yet exist.

For operations relating to a specific directory or file in this share, the clients for those entities can also be retrieved using the get_directory_client and get_file_client functions.

Inheritance

azure.storage.fileshare._shared.base_client_async.AsyncStorageAccountHostsMixin

ShareClient

azure.storage.fileshare._share_client.ShareClient

ShareClient

Constructor

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

Parameters

account_url

str

Required

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

share_name

str

Required

The name of the share with which to interact.

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

acquire_lease	Requests a new lease. If the share does not have an active lease, the Share Service creates a lease on the share and returns a new lease. New in version 12.5.0.
create_directory	Creates a directory in the share and returns a client to interact with the directory.
create_permission_for_share	Create a permission (a security descriptor) at the share level. This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key.
create_share	Creates a new Share under the account. If a share with the same name already exists, the operation fails.
create_snapshot	Creates a snapshot of the share. A snapshot is a read-only version of a share that's taken at a point in time. It can be read, copied, or deleted, but not modified. Snapshots provide a way to back up a share as it appears at a moment in time. A snapshot of a share has the same name as the base share from which the snapshot is taken, with a DateTime value appended to indicate the time at which the snapshot was taken.
delete_directory	Marks the directory for deletion. The directory is later deleted during garbage collection.
delete_share	Marks the specified share for deletion. The share is later deleted during garbage collection.
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_permission_for_share	Get a permission (a security descriptor) for a given key. This 'permission' can be used for the files/directories in the share.
get_share_access_policy	Gets the permissions for the share. The permissions indicate whether files in a share may be accessed publicly.
get_share_properties	Returns all user-defined metadata and system properties for the specified share. The data returned does not include the shares's list of files or directories.
get_share_stats	Gets the approximate size of the data stored on the share in bytes. Note that this value may not include all recently created or recently re-sized files.
list_directories_and_files	Lists the directories and files under the share.
set_share_access_policy	Sets the permissions for the share, or stored access policies that may be used with Shared Access Signatures. The permissions indicate whether files in a share may be accessed publicly.
set_share_metadata	Sets the metadata for the share. Each call to this operation replaces all existing metadata attached to the share. To remove all metadata from the share, call this operation with no metadata dict.
set_share_properties	Sets the share properties. New in version 12.3.0.
set_share_quota	Sets the quota for the share.

acquire_lease

Requests a new lease.

If the share does not have an active lease, the Share Service creates a lease on the share and returns a new lease.

New in version 12.5.0.

async acquire_lease(**kwargs: Any) -> azure.storage.fileshare.aio._lease_async.ShareLeaseClient

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 Share Service returns 400 (Invalid request) if the proposed lease ID is not in the correct format.

timeout

int

The timeout parameter is expressed in seconds.

Returns

A ShareLeaseClient object.

Return type

ShareLeaseClient

create_directory

Creates a directory in the share and returns a client to interact with the directory.

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

Parameters

directory_name

str

Required

The name of the directory.

metadata

dict(<xref:str,str>)

Name-value pairs associated with the directory as metadata.

timeout

int

The timeout parameter is expressed in seconds.

Returns

ShareDirectoryClient

Return type

ShareDirectoryClient

create_permission_for_share

Create a permission (a security descriptor) at the share level.

This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key.

async create_permission_for_share(file_permission: str, **kwargs: Any) -> str

Parameters

file_permission

str

Required

File permission, a Portable SDDL

timeout

int

The timeout parameter is expressed in seconds.

Returns

A file permission key

Return type

str

create_share

Creates a new Share under the account. If a share with the same name already exists, the operation fails.

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

Parameters

metadata

dict(<xref:str,str>)

Name-value pairs associated with the share as metadata.

quota

int

The quota to be allotted.

access_tier

Specifies the access tier of the share. Possible values: 'TransactionOptimized', 'Hot', 'Cool'

timeout

int

The timeout parameter is expressed in seconds.

protocols

str or ShareProtocols

Protocols to enable on the share. Only one protocol can be enabled on the share.

root_squash

str or ShareRootSquash

Root squash to set on the share. Only valid for NFS shares. Possible values include: 'NoRootSquash', 'RootSquash', 'AllSquash'.

Returns

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

Return type

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

Examples

Creates a file share.

   # Create share with Access Tier set to Hot
   await share.create_share(access_tier=ShareAccessTier("Hot"))

create_snapshot

Creates a snapshot of the share.

A snapshot is a read-only version of a share that's taken at a point in time. It can be read, copied, or deleted, but not modified. Snapshots provide a way to back up a share as it appears at a moment in time.

A snapshot of a share has the same name as the base share from which the snapshot is taken, with a DateTime value appended to indicate the time at which the snapshot was taken.

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

Parameters

metadata

dict(<xref:str,str>)

Name-value pairs associated with the share as metadata.

timeout

int

The timeout parameter is expressed in seconds.

Returns

Share-updated property dict (Snapshot ID, Etag, and last modified).

Return type

dict[str, <xref:Any>]

Examples

Creates a snapshot of the file share.

   await share.create_snapshot()

delete_directory

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

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

Parameters

directory_name

str

Required

The name of the directory.

timeout

int

The timeout parameter is expressed in seconds.

Return type

None

delete_share

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

async delete_share(delete_snapshots: Optional[bool] = False, **kwargs) -> None

Parameters

delete_snapshots

bool

Required

Indicates if snapshots are to be deleted.

timeout

int

The timeout parameter is expressed in seconds.

lease

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

New in version 12.5.0.

This keyword argument was introduced in API version '2020-08-04'.

Examples

Deletes the share and any snapshots.

   await share.delete_share(delete_snapshots=True)

get_directory_client

Get a client to interact with the specified directory. The directory need not already exist.

get_directory_client(directory_path: Optional[str] = None) -> azure.storage.fileshare.aio._directory_client_async.ShareDirectoryClient

Parameters

directory_path

str

default value: None

Path to the specified directory.

Returns

A Directory Client.

Return type

ShareDirectoryClient

get_file_client

Get a client to interact with the specified file. The file need not already exist.

get_file_client(file_path: str) -> azure.storage.fileshare.aio._file_client_async.ShareFileClient

Parameters

file_path

str

Required

Path to the specified file.

Returns

A File Client.

Return type

ShareFileClient

get_permission_for_share

Get a permission (a security descriptor) for a given key.

This 'permission' can be used for the files/directories in the share.

async get_permission_for_share(permission_key: str, **kwargs: Any) -> str

Parameters

permission_key

str

Required

Key of the file permission to retrieve

timeout

int

The timeout parameter is expressed in seconds.

Returns

A file permission (a portable SDDL)

Return type

str

get_share_access_policy

Gets the permissions for the share. The permissions indicate whether files in a share may be accessed publicly.

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

Parameters

timeout

int

The timeout parameter is expressed in seconds.

lease

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

New in version 12.5.0.

This keyword argument was introduced in API version '2020-08-04'.

Returns

Access policy information in a dict.

Return type

dict[str, <xref:Any>]

get_share_properties

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

async get_share_properties(**kwargs: Any) -> ShareProperties

Parameters

timeout

int

The timeout parameter is expressed in seconds.

lease

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

New in version 12.5.0.

This keyword argument was introduced in API version '2020-08-04'.

Returns

The share properties.

Return type

ShareProperties

Examples

Gets the share properties.

   properties = await share.get_share_properties()

get_share_stats

Gets the approximate size of the data stored on the share in bytes.

Note that this value may not include all recently created or recently re-sized files.

async get_share_stats(**kwargs: Any) -> int

Parameters

timeout

int

The timeout parameter is expressed in seconds.

lease

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

New in version 12.5.0.

This keyword argument was introduced in API version '2020-08-04'.

Returns

The approximate size of the data (in bytes) stored on the share.

Return type

int

list_directories_and_files

Lists the directories and files under the share.

list_directories_and_files(directory_name: Optional[str] = None, name_starts_with: Optional[str] = None, marker: Optional[str] = None, **kwargs: Any) -> Iterable[Dict[str, str]]

Parameters

directory_name

str

Required

Name of a directory.

name_starts_with

str

Required

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

marker

str

Required

An opaque continuation token. This value can be retrieved from the next_marker field of a previous generator object. If specified, this generator will begin returning results from this point.

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

Examples

List directories and files in the share.

   # Create a directory in the share
   dir_client = await share.create_directory("mydir")

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

   # List files in the directory
   my_files = []
   async for item in share.list_directories_and_files(directory_name="mydir"):
       my_files.append(item)
   print(my_files)

set_share_access_policy

Sets the permissions for the share, or stored access policies that may be used with Shared Access Signatures. The permissions indicate whether files in a share may be accessed publicly.

async set_share_access_policy(signed_identifiers: Dict[str, AccessPolicy], **kwargs: Any) -> Dict[str, str]

Parameters

signed_identifiers

dict(str, AccessPolicy)

Required

A dictionary of access policies to associate with the share. The dictionary may contain up to 5 elements. An empty dictionary will clear the access policies set on the service.

timeout

int

The timeout parameter is expressed in seconds.

lease

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

New in version 12.5.0.

This keyword argument was introduced in API version '2020-08-04'.

Returns

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

Return type

dict(str, <xref:Any>)

set_share_metadata

Sets the metadata for the share.

Each call to this operation replaces all existing metadata attached to the share. To remove all metadata from the share, call this operation with no metadata dict.

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

Parameters

metadata

dict(str, str)

Required

Name-value pairs associated with the share as metadata.

timeout

int

The timeout parameter is expressed in seconds.

lease

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

New in version 12.5.0.

This keyword argument was introduced in API version '2020-08-04'.

Returns

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

Return type

dict(str, <xref:Any>)

Examples

Sets the share metadata.

   data = {'category': 'test'}
   await share.set_share_metadata(metadata=data)

set_share_properties

Sets the share properties.

New in version 12.3.0.

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

Parameters

access_tier

str or <xref:azure.storage.fileshare.models.ShareAccessTier>

Specifies the access tier of the share. Possible values: 'TransactionOptimized', 'Hot', and 'Cool'

quota

int

Specifies the maximum size of the share, in gigabytes. Must be greater than 0, and less than or equal to 5TB.

timeout

int

The timeout parameter is expressed in seconds.

root_squash

str or ShareRootSquash

Root squash to set on the share. Only valid for NFS shares. Possible values include: 'NoRootSquash', 'RootSquash', 'AllSquash'

lease

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

Returns

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

Return type

dict(str, <xref:Any>)

Examples

Sets the share properties.

   # Set the tier for the first share to Hot
   await share1.set_share_properties(access_tier="Hot")
   # Set the quota for the first share to 3
   await share1.set_share_properties(quota=3)
   # Set the tier for the second share to Cool and quota to 2
   await share2.set_share_properties(access_tier=ShareAccessTier("Cool"), quota=2)

   # Get the shares' properties
   props1 = await share1.get_share_properties()
   props2 = await share2.get_share_properties()
   print(props1.access_tier)
   print(props1.quota)
   print(props2.access_tier)
   print(props2.quota)

set_share_quota

Sets the quota for the share.

async set_share_quota(quota: int, **kwargs: Any) -> Dict[str, Any]

Parameters

quota

int

Required

Specifies the maximum size of the share, in gigabytes. Must be greater than 0, and less than or equal to 5TB.

timeout

int

The timeout parameter is expressed in seconds.

lease

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

New in version 12.5.0.

This keyword argument was introduced in API version '2020-08-04'.

Returns

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

Return type

dict(str, <xref:Any>)

Examples

Sets the share quota.

   # Set the quota for the share to 1GB
   await share.set_share_quota(quota=1)