Share Lease Feature

sdk/storage/azure-storage-file-share/azure/storage/fileshare/_file_client.py

@@ -266,7 +266,7 @@ def from_connection_string(
 
     @distributed_trace
     def acquire_lease(self, lease_id=None, **kwargs):
-        # type: (int, Optional[str], **Any) -> BlobLeaseClient
+        # type: (Optional[str], **Any) -> ShareLeaseClient
         """Requests a new lease.
 
         If the file does not have an active lease, the File
@@ -283,15 +283,15 @@ def acquire_lease(self, lease_id=None, **kwargs):
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../samples/blob_samples_common.py
-                :start-after: [START acquire_lease_on_blob]
-                :end-before: [END acquire_lease_on_blob]
+            .. literalinclude:: ../samples/file_samples_client.py
+                :start-after: [START acquire_and_release_lease_on_file]
+                :end-before: [END acquire_and_release_lease_on_file]
                 :language: python
-                :dedent: 8
-                :caption: Acquiring a lease on a blob.
+                :dedent: 12
+                :caption: Acquiring a lease on a file.
         """
         lease = ShareLeaseClient(self, lease_id=lease_id)  # type: ignore
-        lease.acquire(**kwargs)
+        lease.acquire(lease_duration=-1, **kwargs)
         return lease
 
     @distributed_trace

sdk/storage/azure-storage-file-share/azure/storage/fileshare/_lease.py

@@ -7,23 +7,25 @@
 import uuid
 
 from typing import (  # pylint: disable=unused-import
-    Optional, Any, TypeVar, TYPE_CHECKING
+    Union, Optional, Any, TypeVar, TYPE_CHECKING
 )
 
 from azure.core.tracing.decorator import distributed_trace
 
 from ._shared.response_handlers import return_response_headers, process_storage_error
 from ._generated.models import StorageErrorException
+from ._generated.operations import FileOperations
 
 if TYPE_CHECKING:
     from datetime import datetime
     ShareFileClient = TypeVar("ShareFileClient")
+    ShareClient = TypeVar("ShareClient")
 
 
 class ShareLeaseClient(object):
     """Creates a new ShareLeaseClient.
 
-    This client provides lease operations on a ShareFileClient.
+    This client provides lease operations on a ShareClient or ShareFileClient.
 
     :ivar str id:
         The ID of the lease currently being maintained. This will be `None` if no
@@ -36,23 +38,28 @@ class ShareLeaseClient(object):
         This will be `None` if no lease has yet been acquired or modified.
 
     :param client:
-        The client of the file to lease.
-    :type client: ~azure.storage.fileshare.ShareFileClient
+        The client of the file or share to lease.
+    :type client: ~azure.storage.fileshare.ShareFileClient or
+        ~azure.storage.fileshare.ShareClient
     :param str lease_id:
         A string representing the lease ID of an existing lease. This value does not
         need to be specified in order to acquire a new lease, or break one.
     """
     def __init__(
             self, client, lease_id=None
     ):  # pylint: disable=missing-client-constructor-parameter-credential,missing-client-constructor-parameter-kwargs
-        # type: (ShareFileClient, Optional[str]) -> None
+        # type: (Union[ShareFileClient, ShareClient], Optional[str]) -> None
         self.id = lease_id or str(uuid.uuid4())
         self.last_modified = None
         self.etag = None
         if hasattr(client, 'file_name'):
             self._client = client._client.file  # type: ignore # pylint: disable=protected-access
+            self._snapshot = None
+        elif hasattr(client, 'share_name'):
+            self._client = client._client.share
+            self._snapshot = client.snapshot
         else:
-            raise TypeError("Lease must use ShareFileClient.")
+            raise TypeError("Lease must use ShareFileClient or ShareClient.")
 
     def __enter__(self):
         return self
@@ -61,25 +68,33 @@ def __exit__(self, *args):
         self.release()
 
     @distributed_trace
-    def acquire(self, **kwargs):
+    def acquire(self, lease_duration=-1, **kwargs):
         # type: (int, **Any) -> None
         """Requests a new lease. This operation establishes and manages a lock on a
-        file for write and delete operations. If the file does not have an active lease,
-        the File service creates a lease on the file. If the file has an active lease,
+        file or share for write and delete operations. If the file or share does not have an active lease,
+        the File or Share service creates a lease on the file or share. If the file has an active lease,
         you can only request a new lease using the active lease ID.
 
 
-        If the file does not have an active lease, the File service creates a
+        If the file or share does not have an active lease, the File or Share service creates a
         lease on the file and returns a new lease ID.
 
+        :param int lease_duration:
+            Specifies the duration of the lease, in seconds, or negative one
+            (-1) for a lease that never expires. File leases never expire. A non-infinite share lease can be
+            between 15 and 60 seconds. A share lease duration cannot be changed
+            using renew or change. Default is -1 (infinite share lease).
+
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :rtype: None
         """
         try:
+            if self._snapshot:
+                kwargs['sharesnapshot'] = self._snapshot
             response = self._client.acquire_lease(
                 timeout=kwargs.pop('timeout', None),
-                duration=-1,
+                duration=lease_duration,
                 proposed_lease_id=self.id,
                 cls=return_response_headers,
                 **kwargs)
@@ -90,22 +105,63 @@ def acquire(self, **kwargs):
         self.etag = response.get('etag')  # type: str
 
     @distributed_trace
-    def release(self, **kwargs):
+    def renew(self, **kwargs):
         # type: (Any) -> None
-        """Releases the lease. The lease may be released if the lease ID specified on the request matches
-        that associated with the file. Releasing the lease allows another client to immediately acquire the lease
-        for the file as soon as the release is complete.
+        """Renews the share lease.
+
+        The share lease can be renewed if the lease ID specified in the
+        lease client matches that associated with the share. Note that
+        the lease may be renewed even if it has expired as long as the share
+        has not been leased again since the expiration of that lease. When you
+        renew a lease, the lease duration clock resets.
 
+        .. versionadded:: 12.6.0
+        This keyword argument was introduced in API version '2020-02-02'.
 
-        The lease may be released if the client lease id specified matches
-        that associated with the file. Releasing the lease allows another client
-        to immediately acquire the lease for the file as soon as the release is complete.
+        :keyword str etag:
+            An ETag value, or the wildcard character (*). Used to check if the resource has changed,
+            and act according to the condition specified by the `match_condition` parameter.
+        :keyword ~azure.core.MatchConditions match_condition:
+            The match condition to use upon the etag.
+        :keyword str if_tags_match_condition
+            Specify a SQL where clause on share tags to operate only on share with a matching value.
+            eg. "\"tagname\"='my tag'"
+
+            .. versionadded:: 12.4.0
+
+        :keyword int timeout:
+            The timeout parameter is expressed in seconds.
+        :return: None
+        """
+        if isinstance(self._client, FileOperations):
+            raise TypeError("Lease renewal operations are only valid for ShareClient.")
+        try:
+            response = self._client.renew_lease(
+                lease_id=self.id,
+                timeout=kwargs.pop('timeout', None),
+                sharesnapshot=self._snapshot,
+                cls=return_response_headers,
+                **kwargs)
+        except StorageErrorException as error:
+            process_storage_error(error)
+        self.etag = response.get('etag')  # type: str
+        self.id = response.get('lease_id')  # type: str
+        self.last_modified = response.get('last_modified')   # type: datetime
+
+    @distributed_trace
+    def release(self, **kwargs):
+        # type: (Any) -> None
+        """Releases the lease. The lease may be released if the lease ID specified on the request matches
+        that associated with the share or file. Releasing the lease allows another client to immediately acquire
+        the lease for the share or file as soon as the release is complete.
 
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :return: None
         """
         try:
+            if self._snapshot:
+                kwargs['sharesnapshot'] = self._snapshot
             response = self._client.release_lease(
                 lease_id=self.id,
                 timeout=kwargs.pop('timeout', None),
@@ -125,13 +181,15 @@ def change(self, proposed_lease_id, **kwargs):
 
 
         :param str proposed_lease_id:
-            Proposed lease ID, in a GUID string format. The File service returns 400
+            Proposed lease ID, in a GUID string format. The File or Share service returns 400
             (Invalid request) if the proposed lease ID is not in the correct format.
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :return: None
         """
         try:
+            if self._snapshot:
+                kwargs['sharesnapshot'] = self._snapshot
             response = self._client.change_lease(
                 lease_id=self.id,
                 proposed_lease_id=proposed_lease_id,
@@ -146,8 +204,8 @@ def change(self, proposed_lease_id, **kwargs):
 
     @distributed_trace
     def break_lease(self, **kwargs):
-        # type: (Optional[int], Any) -> int
-        """Force breaks the lease if the file has an active lease. Any authorized request can break the lease;
+        # type: (Optional[int, str], Any) -> int
+        """Force breaks the lease if the file or share has an active lease. Any authorized request can break the lease;
         the request is not required to specify a matching lease ID. An infinite lease breaks immediately.
 
         Once a lease is broken, it cannot be changed. Any authorized request can break the lease;
@@ -161,6 +219,8 @@ def break_lease(self, **kwargs):
         :rtype: int
         """
         try:
+            if self._snapshot:
+                kwargs['sharesnapshot'] = self._snapshot
             response = self._client.break_lease(
                 timeout=kwargs.pop('timeout', None),
                 cls=return_response_headers,

sdk/storage/azure-storage-file-share/azure/storage/fileshare/_models.py

@@ -304,6 +304,7 @@ def __init__(self, **kwargs):
         self.provisioned_egress_mbps = kwargs.get('x-ms-share-provisioned-egress-mbps')
         self.provisioned_ingress_mbps = kwargs.get('x-ms-share-provisioned-ingress-mbps')
         self.provisioned_iops = kwargs.get('x-ms-share-provisioned-iops')
+        self.lease = LeaseProperties(**kwargs)
 
     @classmethod
     def _from_generated(cls, generated):
@@ -322,6 +323,7 @@ def _from_generated(cls, generated):
         props.provisioned_egress_mbps = generated.properties.provisioned_egress_mbps
         props.provisioned_ingress_mbps = generated.properties.provisioned_ingress_mbps
         props.provisioned_iops = generated.properties.provisioned_iops
+        props.lease = LeaseProperties._from_generated(generated)  # pylint: disable=protected-access
         return props