ShareClient class

Definition

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(directory_path=None) and get_file_client(file_path) functions.

ShareClient(account_url, share_name, snapshot=None, credential=None, **kwargs)
Inheritance
builtins.object
azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin
ShareClient

Parameters

account_url
str

The URI to the storage account. In order to create a client given the full URI to the share, use the from_share_url(share_url, snapshot=None, credential=None, **kwargs) classmethod.

share_name
str

The name of the share with which to interact.

snapshot
str

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

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

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.

from_connection_string

Create ShareClient from a Connection String.

from_share_url
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_quota

Sets the quota for the share.

create_directory

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

create_directory(directory_name, **kwargs)

Parameters

directory_name
str
Required

The name of the directory.

Returns

ShareDirectoryClient

Return type

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_permission_for_share(file_permission, **kwargs)

Parameters

file_permission
str
Required

File permission, a Portable SDDL

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.

create_share(**kwargs)

Returns

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

Return type

dict(str, Any)

Examples

Creates a file share.


   share.create_share()

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.

create_snapshot(**kwargs)

Returns

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

Return type

dict[str, Any]

Examples

Creates a snapshot of the file share.


   share.create_snapshot()

delete_directory

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

delete_directory(directory_name, **kwargs)

Parameters

directory_name
str
Required

The name of the directory.

Return type

None

delete_share

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

delete_share(delete_snapshots=False, **kwargs)

Parameters

delete_snapshots
bool
Required

Indicates if snapshots are to be deleted.

Return type

None

Examples

Deletes the share and any snapshots.


   share.delete_share(delete_snapshots=True)

from_connection_string

Create ShareClient from a Connection String.

from_connection_string(conn_str, share_name, snapshot=None, credential=None, **kwargs)

Parameters

conn_str
str
Required

A connection string to an Azure Storage account.

share_name
str
Required

The name of the share.

snapshot
str
Required

The optional share snapshot on which to operate. This can be the snapshot ID string or the response returned from create_snapshot(**kwargs).

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 or an account shared access key.

credential
default value: None

Returns

A share client.

Return type

Examples

Gets the share client from connection string.


   from azure.storage.fileshare import ShareClient
   share = ShareClient.from_connection_string(self.connection_string, "sharesamples2")

from_share_url

from_share_url(share_url, snapshot=None, credential=None, **kwargs)

Parameters

share_url
str
Required

The full URI to the share.

snapshot
str
Required

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

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 or an account shared access key.

credential
default value: None

Returns

A share client.

Return type

get_directory_client

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

get_directory_client(directory_path=None)

Parameters

directory_path
str
default value: None

Path to the specified directory.

Returns

A Directory Client.

Return type

get_file_client

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

get_file_client(file_path)

Parameters

file_path
str
Required

Path to the specified file.

Returns

A File Client.

Return type

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_permission_for_share(permission_key, **kwargs)

Parameters

permission_key
str
Required

Key of the file permission to retrieve

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.

get_share_access_policy(**kwargs)

Returns

Access policy information in a dict.

Return type

dict[str, 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.

get_share_properties(**kwargs)

Returns

The share properties.

Return type

Examples

Gets the share properties.


   properties = 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.

get_share_stats(**kwargs)

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=None, name_starts_with=None, marker=None, **kwargs)

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.

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 = share.create_directory("mydir")

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

   # List files in the directory
   my_files = list(share.list_directories_and_files(directory_name="mydir"))
   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.

set_share_access_policy(signed_identifiers, **kwargs)

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.

Returns

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

Return type

dict(str, 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.

set_share_metadata(metadata, **kwargs)

Parameters

metadata
dict(str, str)
Required

Name-value pairs associated with the share as metadata.

Returns

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

Return type

dict(str, Any)

Examples

Sets the share metadata.


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

set_share_quota

Sets the quota for the share.

set_share_quota(quota, **kwargs)

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.

Returns

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

Return type

dict(str, Any)

Examples

Sets the share quota.


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