[Storage] [Named Keywords] [File Share] _lease.pyi and aio (#41761)

Author: weirongw23-msft

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

@@ -6,21 +6,19 @@
 # pylint: disable=docstring-keyword-should-match-keyword-only
 
 import uuid
+from typing import Any, cast, Optional, Union, TYPE_CHECKING
 
-from typing import Union, Optional, Any, TYPE_CHECKING
-
-from azure.core.tracing.decorator import distributed_trace
 from azure.core.exceptions import HttpResponseError
-
-from ._shared.response_handlers import return_response_headers, process_storage_error
+from azure.core.tracing.decorator import distributed_trace
 from ._generated.operations import FileOperations, ShareOperations
+from ._shared.response_handlers import return_response_headers, process_storage_error
 
 if TYPE_CHECKING:
     from datetime import datetime
     from azure.storage.fileshare import ShareClient, ShareFileClient
 
 
-class ShareLeaseClient(object):  # pylint: disable=client-accepts-api-version-keyword
+class ShareLeaseClient:  # pylint: disable=client-accepts-api-version-keyword
     """Creates a new ShareLeaseClient.
 
     This client provides lease operations on a ShareClient or ShareFileClient.
@@ -248,4 +246,4 @@ def break_lease(self, **kwargs: Any) -> int:
                 **kwargs)
         except HttpResponseError as error:
             process_storage_error(error)
-        return response.get('lease_time')  # type: ignore
+        return cast(int, response.get('lease_time'))

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

@@ -0,0 +1,38 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+# pylint: skip-file
+
+from datetime import datetime
+from types import TracebackType
+from typing import Union, Optional, Any
+
+from typing_extensions import Self
+
+from azure.core.tracing.decorator import distributed_trace
+from ._file_client import ShareFileClient
+from ._share_client import ShareClient
+
+class ShareLeaseClient:
+    id: str
+    etag: Optional[str]
+    last_modified: Optional[datetime]
+    def __init__(self, client: Union[ShareFileClient, ShareClient], lease_id: Optional[str] = None) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self, typ: Optional[type[BaseException]], exc: Optional[BaseException], tb: Optional[TracebackType]
+    ) -> None: ...
+    @distributed_trace
+    def acquire(self, *, lease_duration: int = -1, timeout: Optional[int] = None, **kwargs: Any) -> None: ...
+    @distributed_trace
+    def renew(self, *, timeout: Optional[int] = None, **kwargs: Any) -> None: ...
+    @distributed_trace
+    def release(self, *, timeout: Optional[int] = None, **kwargs: Any) -> None: ...
+    @distributed_trace
+    def change(self, proposed_lease_id: str, *, timeout: Optional[int] = None, **kwargs: Any) -> None: ...
+    @distributed_trace
+    def break_lease(
+        self, *, lease_break_period: Optional[int] = None, timeout: Optional[int] = None, **kwargs: Any
+    ) -> int: ...

sdk/storage/azure-storage-file-share/azure/storage/fileshare/aio/_lease_async.py

@@ -6,17 +6,16 @@
 # pylint: disable=docstring-keyword-should-match-keyword-only
 
 import uuid
-
-from typing import Union, Optional, Any, TYPE_CHECKING
+from typing import Any, cast, Optional, Union, TYPE_CHECKING
 
 from azure.core.exceptions import HttpResponseError
 from azure.core.tracing.decorator_async import distributed_trace_async
-
-from .._shared.response_handlers import return_response_headers, process_storage_error
 from .._generated.aio.operations import FileOperations, ShareOperations
+from .._shared.response_handlers import return_response_headers, process_storage_error
 
 if TYPE_CHECKING:
     from azure.storage.fileshare.aio import ShareClient, ShareFileClient
+    from datetime import datetime
 
 
 class ShareLeaseClient:  # pylint: disable=client-accepts-api-version-keyword
@@ -42,17 +41,27 @@ class ShareLeaseClient:  # pylint: disable=client-accepts-api-version-keyword
         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.
     """
+
+    id: str
+    """The ID of the lease currently being maintained. This will be `None` if no
+        lease has yet been acquired."""
+    etag: Optional[str]
+    """The ETag of the lease currently being maintained. This will be `None` if no
+        lease has yet been acquired or modified."""
+    last_modified: Optional["datetime"]
+    """The last modified timestamp of the lease currently being maintained.
+        This will be `None` if no lease has yet been acquired or modified."""
+
     def __init__(  # pylint: disable=missing-client-constructor-parameter-credential, missing-client-constructor-parameter-kwargs
-        self, client: Union["ShareFileClient", "ShareClient"],
-        lease_id: Optional[str] = None
+        self, client: Union["ShareFileClient", "ShareClient"], lease_id: Optional[str] = None
     ) -> None:
         self.id = lease_id or str(uuid.uuid4())
         self.last_modified = None
         self.etag = None
-        if hasattr(client, 'file_name'):
+        if hasattr(client, "file_name"):
             self._client = client._client.file  # type: ignore
             self._snapshot = None
-        elif hasattr(client, 'share_name'):
+        elif hasattr(client, "share_name"):
             self._client = client._client.share
             self._snapshot = client.snapshot
         else:
@@ -90,20 +99,21 @@ async def acquire(self, **kwargs: Any) -> None:
         :rtype: None
         """
         try:
-            lease_duration = kwargs.pop('lease_duration', -1)
+            lease_duration = kwargs.pop("lease_duration", -1)
             if self._snapshot:
-                kwargs['sharesnapshot'] = self._snapshot
+                kwargs["sharesnapshot"] = self._snapshot
             response = await self._client.acquire_lease(
-                timeout=kwargs.pop('timeout', None),
+                timeout=kwargs.pop("timeout", None),
                 duration=lease_duration,
                 proposed_lease_id=self.id,
                 cls=return_response_headers,
-                **kwargs)
+                **kwargs
+            )
         except HttpResponseError as error:
             process_storage_error(error)
-        self.id = response.get('lease_id')
-        self.last_modified = response.get('last_modified')
-        self.etag = response.get('etag')
+        self.id = response.get("lease_id")
+        self.last_modified = response.get("last_modified")
+        self.etag = response.get("etag")
 
     @distributed_trace_async
     async def renew(self, **kwargs: Any) -> None:
@@ -130,15 +140,16 @@ async def renew(self, **kwargs: Any) -> None:
         try:
             response = await self._client.renew_lease(
                 lease_id=self.id,
-                timeout=kwargs.pop('timeout', None),
+                timeout=kwargs.pop("timeout", None),
                 sharesnapshot=self._snapshot,
                 cls=return_response_headers,
-                **kwargs)
+                **kwargs
+            )
         except HttpResponseError as error:
             process_storage_error(error)
-        self.etag = response.get('etag')
-        self.id = response.get('lease_id')
-        self.last_modified = response.get('last_modified')
+        self.etag = response.get("etag")
+        self.id = response.get("lease_id")
+        self.last_modified = response.get("last_modified")
 
     @distributed_trace_async
     async def release(self, **kwargs: Any) -> None:
@@ -156,21 +167,19 @@ async def release(self, **kwargs: Any) -> None:
         """
         try:
             if self._snapshot:
-                kwargs['sharesnapshot'] = self._snapshot
+                kwargs["sharesnapshot"] = self._snapshot
             response = await self._client.release_lease(
-                lease_id=self.id,
-                timeout=kwargs.pop('timeout', None),
-                cls=return_response_headers,
-                **kwargs)
+                lease_id=self.id, timeout=kwargs.pop("timeout", None), cls=return_response_headers, **kwargs
+            )
         except HttpResponseError as error:
             process_storage_error(error)
-        self.etag = response.get('etag')
-        self.id = response.get('lease_id')
-        self.last_modified = response.get('last_modified')
+        self.etag = response.get("etag")
+        self.id = response.get("lease_id")
+        self.last_modified = response.get("last_modified")
 
     @distributed_trace_async
     async def change(self, proposed_lease_id: str, **kwargs: Any) -> None:
-        """ Changes the lease ID of an active lease. A change must include the current lease ID in x-ms-lease-id and
+        """Changes the lease ID of an active lease. A change must include the current lease ID in x-ms-lease-id and
         a new lease ID in x-ms-proposed-lease-id.
 
         :param str proposed_lease_id:
@@ -186,18 +195,19 @@ async def change(self, proposed_lease_id: str, **kwargs: Any) -> None:
         """
         try:
             if self._snapshot:
-                kwargs['sharesnapshot'] = self._snapshot
+                kwargs["sharesnapshot"] = self._snapshot
             response = await self._client.change_lease(
                 lease_id=self.id,
                 proposed_lease_id=proposed_lease_id,
-                timeout=kwargs.pop('timeout', None),
+                timeout=kwargs.pop("timeout", None),
                 cls=return_response_headers,
-                **kwargs)
+                **kwargs
+            )
         except HttpResponseError as error:
             process_storage_error(error)
-        self.etag = response.get('etag')
-        self.id = response.get('lease_id')
-        self.last_modified = response.get('last_modified')
+        self.etag = response.get("etag")
+        self.id = response.get("lease_id")
+        self.last_modified = response.get("last_modified")
 
     @distributed_trace_async
     async def break_lease(self, **kwargs: Any) -> int:
@@ -232,18 +242,17 @@ async def break_lease(self, **kwargs: Any) -> int:
         :rtype: int
         """
         try:
-            lease_break_period = kwargs.pop('lease_break_period', None)
+            lease_break_period = kwargs.pop("lease_break_period", None)
             if self._snapshot:
-                kwargs['sharesnapshot'] = self._snapshot
+                kwargs["sharesnapshot"] = self._snapshot
             if isinstance(self._client, ShareOperations):
-                kwargs['break_period'] = lease_break_period
+                kwargs["break_period"] = lease_break_period
             if isinstance(self._client, FileOperations) and lease_break_period:
                 raise TypeError("Setting a lease break period is only applicable to Share leases.")
 
             response = await self._client.break_lease(
-                timeout=kwargs.pop('timeout', None),
-                cls=return_response_headers,
-                **kwargs)
+                timeout=kwargs.pop("timeout", None), cls=return_response_headers, **kwargs
+            )
         except HttpResponseError as error:
             process_storage_error(error)
-        return response.get('lease_time')  # type: ignore
+        return cast(int, response.get("lease_time"))

sdk/storage/azure-storage-file-share/azure/storage/fileshare/aio/_lease_async.pyi

@@ -0,0 +1,52 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+# pylint: skip-file
+
+from datetime import datetime
+from types import TracebackType
+from typing import Union, Optional, Any
+
+from typing_extensions import Self
+
+from azure.core.tracing.decorator_async import distributed_trace_async
+from ._file_client_async import ShareFileClient
+from ._share_client_async import ShareClient
+
+
+class ShareLeaseClient:
+    id: str
+    etag: Optional[str]
+    last_modified: Optional[datetime]
+    def __init__(
+        self, client: Union[ShareFileClient, ShareClient],
+        lease_id: Optional[str] = None
+    ) -> None: ...
+    async def __aenter__(self) -> Self: ...
+    async def __aexit__(
+        self, typ: Optional[type[BaseException]], exc: Optional[BaseException], tb: Optional[TracebackType]
+    ) -> None: ...
+    @distributed_trace_async
+    async def acquire(
+        self,
+        *,
+        lease_duration: int = -1,
+        timeout: Optional[int] = None,
+        **kwargs: Any
+    ) -> None: ...
+    @distributed_trace_async
+    async def renew(self, *, timeout: Optional[int] = None, **kwargs: Any) -> None: ...
+    @distributed_trace_async
+    async def release(self, *, timeout: Optional[int] = None, **kwargs: Any) -> None: ...
+    @distributed_trace_async
+    async def change(self, proposed_lease_id: str, *, timeout: Optional[int] = None, **kwargs: Any) -> None: ...
+    @distributed_trace_async
+    async def break_lease(
+        self,
+        *,
+        lease_break_period: Optional[int] = None,
+        timeout: Optional[int] = None,
+        **kwargs: Any
+    ) -> int: ...