[Key Vault] Respond to review feedback for 7.6 support packages (#41541)

Author: mccoyp

sdk/keyvault/azure-keyvault-administration/CHANGELOG.md

@@ -15,6 +15,13 @@
 - Key Vault API version `7.6` is now the default
 - (From 4.6.0b1) Updated minimum `typing-extensions` version to 4.6.0
 
+### Breaking Changes
+
+> These changes do not impact the API of stable versions such as 4.5.0. Only code written against a beta version such as 4.6.0b1 may be affected.
+
+- Changed the return types of `KeyVaultBackupClient.begin_pre_backup` and `KeyVaultBackupClient.begin_pre_restore` to be
+  pollers returning `None`
+
 ## 4.6.0b1 (2025-03-20)
 
 ### Features Added

sdk/keyvault/azure-keyvault-administration/README.md

@@ -24,7 +24,7 @@ create, manage, and deploy public and private SSL/TLS certificates
 ## _Disclaimer_
 
 _Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691._
-_Python 3.8 or later is required to use this package. For more details, please refer to [Azure SDK for Python version support policy](https://github.com/Azure/azure-sdk-for-python/wiki/Azure-SDKs-Python-version-support-policy)._
+_Python 3.9 or later is required to use this package. For more details, please refer to [Azure SDK for Python version support policy](https://github.com/Azure/azure-sdk-for-python/wiki/Azure-SDKs-Python-version-support-policy)._
 
 ## Getting started
 ### Install packages
@@ -38,7 +38,7 @@ authentication as demonstrated below.
 
 ### Prerequisites
 * An [Azure subscription][azure_sub]
-* Python 3.8 or later
+* Python 3.9 or later
 * An existing [Key Vault Managed HSM][managed_hsm]. If you need to create one, you can do so using the Azure CLI by following the steps in [this document][managed_hsm_cli].
 
 ### Authenticate the client
@@ -303,17 +303,16 @@ to the library's [credential documentation][sas_docs]. Alternatively, it is poss
 ```python
 CONTAINER_URL = os.environ["CONTAINER_URL"]
 
-check_result: KeyVaultBackupOperation = client.begin_pre_backup(CONTAINER_URL, use_managed_identity=True).result()
+try:
+    client.begin_pre_backup(CONTAINER_URL, use_managed_identity=True).wait()
+except HttpResponseError as e:
+    print(f"A backup cannot be performed: {str(e)}")
 
-if check_result.error:
-    print(f"Reason the backup cannot be performed: {check_result.error}")
-else:
-    print("A full key backup can be successfully performed.")
+print("A full key backup can be successfully performed.")
 ```
 
-Note that the `begin_pre_backup` method returns a poller. Calling `result()` on this poller returns a
-`KeyVaultBackupOperation` -- this object will  have a string `error` attribute if the check failed, and otherwise the
-check will have succeeded.
+Note that the `begin_pre_backup` method returns a poller. Calling `wait()` on this poller waits for the check to
+complete. An error will raise if the check failed; otherwise the check will have succeeded.
 
 ### Perform a full key backup
 To actually perform the key backup, you can use `KeyVaultBackupClient.begin_backup`.
@@ -350,19 +349,16 @@ to the library's [credential documentation][sas_docs]. Alternatively, it is poss
 [generate a SAS token in Storage Explorer][storage_explorer].
 
 ```python
-check_result: KeyVaultRestoreOperation = client.begin_pre_restore(
-    backup_result.folder_url, use_managed_identity=True
-).result()
-
-if check_result.error:
-    print(f"Reason the backup cannot be performed: {check_result.error}")
-else:
-    print("A full key restore can be successfully performed.")
+try:
+    client.begin_pre_restore(backup_result.folder_url, use_managed_identity=True).wait()
+except HttpResponseError as e:
+    print(f"A full restore cannot be performed: {str(e)}")
+
+print("A full key restore can be successfully performed.")
 ```
 
-Note that the `begin_pre_restore` method returns a poller. Calling `result()` on this poller returns a
-`KeyVaultRestoreOperation` -- this object will have a string `error` attribute if the check failed, and otherwise the
-`error` will be None if the check succeeded.
+Note that the `begin_pre_restore` method returns a poller. Calling `wait()` on this poller waits for the check to
+complete. An error will raise if the check failed; otherwise the check will have succeeded.
 
 ### Perform a full key restore
 To actually restore your entire collection of keys, you can use `KeyVaultBackupClient.begin_restore`.

sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/__init__.py

@@ -7,10 +7,8 @@
 from ._enums import KeyVaultRoleScope, KeyVaultDataAction, KeyVaultSettingType
 from ._internal.client_base import ApiVersion
 from ._models import (
-    KeyVaultBackupOperation,
     KeyVaultBackupResult,
     KeyVaultPermission,
-    KeyVaultRestoreOperation,
     KeyVaultRoleAssignment,
     KeyVaultRoleAssignmentProperties,
     KeyVaultRoleDefinition,
@@ -21,13 +19,11 @@
 
 __all__ = [
     "ApiVersion",
-    "KeyVaultBackupOperation",
     "KeyVaultBackupResult",
     "KeyVaultAccessControlClient",
     "KeyVaultBackupClient",
     "KeyVaultDataAction",
     "KeyVaultPermission",
-    "KeyVaultRestoreOperation",
     "KeyVaultRoleAssignment",
     "KeyVaultRoleAssignmentProperties",
     "KeyVaultRoleDefinition",

sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_backup_client.py

@@ -14,7 +14,7 @@
 from azure.core.tracing.decorator import distributed_trace
 
 from ._generated.models import PreBackupOperationParameters, PreRestoreOperationParameters, SASTokenParameter
-from ._models import KeyVaultBackupOperation, KeyVaultBackupResult, KeyVaultRestoreOperation
+from ._models import KeyVaultBackupResult
 from ._internal import KeyVaultClientBase, parse_folder_url
 from ._internal.polling import KeyVaultBackupClientPolling, KeyVaultBackupClientPollingMethod
 
@@ -250,7 +250,7 @@ def begin_pre_backup(
         use_managed_identity: Literal[True],
         continuation_token: Optional[str] = None,
         **kwargs: Any,
-    ) -> LROPoller[KeyVaultBackupOperation]:
+    ) -> LROPoller[None]:
         ...
 
     @overload
@@ -261,19 +261,17 @@ def begin_pre_backup(
         sas_token: str,
         continuation_token: Optional[str] = None,
         **kwargs: Any,
-    ) -> LROPoller[KeyVaultBackupOperation]:
+    ) -> LROPoller[None]:
         ...
 
     @distributed_trace
     def begin_pre_backup(  # pylint: disable=docstring-keyword-should-match-keyword-only
         self, blob_storage_url: str, **kwargs: Any
-    ) -> LROPoller[KeyVaultBackupOperation]:
+    ) -> LROPoller[None]:
         """Initiates a pre-backup check of whether a full Key Vault backup can be performed.
 
-        A :class:`KeyVaultBackupOperation` instance will be returned by the poller's `result()` method. If the
-        pre-backup check is successful, the object will have a string `folder_url` attribute, pointing to the blob
-        storage container where the backup will be stored. If the check fails, the object will have a string `error`
-        attribute.
+        If the pre-backup check fails, calling `wait()` on the returned poller will raise an error. Otherwise, a full
+        backup can be performed.
 
         :param str blob_storage_url: URL of the blob storage container in which the backup will be stored, for example
             https://<account>.blob.core.windows.net/backup.
@@ -286,11 +284,9 @@ def begin_pre_backup(  # pylint: disable=docstring-keyword-should-match-keyword-
         :paramtype use_managed_identity: bool
         :keyword str continuation_token: A continuation token to restart polling from a saved state.
 
-        :returns: An :class:`~azure.core.polling.LROPoller` instance. Call `result()` on this object to wait for the
-            operation to complete and get a :class:`KeyVaultBackupOperation`. If the pre-backup check is successful, the
-            object will have a string `folder_url` attribute, pointing to the blob storage container where the backup
-            will be stored. If the check fails, the object will have a string `error` attribute.
-        :rtype: ~azure.core.polling.LROPoller[~azure.keyvault.administration.KeyVaultBackupOperation]
+        :returns: An :class:`~azure.core.polling.LROPoller` instance. Call `wait()` on this object to wait for the
+            operation to complete. If the check fails, an error will be raised.
+        :rtype: ~azure.core.polling.LROPoller[None]
         """
         polling_interval: int = kwargs.pop("_polling_interval", 5)
         continuation_token: Optional[str] = kwargs.pop("continuation_token", None)
@@ -306,7 +302,7 @@ def begin_pre_backup(  # pylint: disable=docstring-keyword-should-match-keyword-
 
         return self._client.begin_pre_full_backup(
             pre_backup_operation_parameters=parameters,
-            cls=KeyVaultBackupOperation._from_generated,  # pylint: disable=protected-access
+            cls=lambda *_: None,  # poller.result() returns None
             polling=KeyVaultBackupClientPollingMethod(
                 lro_algorithms=[KeyVaultBackupClientPolling()], timeout=polling_interval, **kwargs
             ),
@@ -322,7 +318,7 @@ def begin_pre_restore(
         use_managed_identity: Literal[True],
         continuation_token: Optional[str] = None,
         **kwargs: Any,
-    ) -> LROPoller[KeyVaultRestoreOperation]:
+    ) -> LROPoller[None]:
         ...
 
     @overload
@@ -333,17 +329,17 @@ def begin_pre_restore(
         sas_token: str,
         continuation_token: Optional[str] = None,
         **kwargs: Any,
-    ) -> LROPoller[KeyVaultRestoreOperation]:
+    ) -> LROPoller[None]:
         ...
 
     @distributed_trace
     def begin_pre_restore(  # pylint: disable=docstring-keyword-should-match-keyword-only
         self, folder_url: str, **kwargs: Any
-    ) -> LROPoller[KeyVaultRestoreOperation]:
+    ) -> LROPoller[None]:
         """Initiates a pre-restore check of whether a full Key Vault restore can be performed.
 
-        A :class:`KeyVaultRestoreOperation` instance will be returned by the poller's `result()` method. If the
-        pre-restore check fails, the object will have a string `error` attribute.
+        If the pre-restore check fails, calling `wait()` on the returned poller will raise an error. Otherwise, a full
+        restore can be performed.
 
         :param str folder_url: URL of the blob holding the backup. This would be the `folder_url` of a
             :class:`KeyVaultBackupResult` returned by :func:`begin_backup`, for example
@@ -357,10 +353,9 @@ def begin_pre_restore(  # pylint: disable=docstring-keyword-should-match-keyword
         :paramtype use_managed_identity: bool
         :keyword str continuation_token: A continuation token to restart polling from a saved state.
 
-        :returns: An :class:`~azure.core.polling.LROPoller` instance. Call `result()` on this object to wait for the
-            operation to complete and get a :class:`KeyVaultRestoreOperation`. If the pre-restore check fails, the
-            object will have a string `error` attribute.
-        :rtype: ~azure.core.polling.LROPoller[~azure.keyvault.administration.KeyVaultRestoreOperation]
+        :returns: An :class:`~azure.core.polling.LROPoller` instance. Call `wait()` on this object to wait for the
+            operation to complete. If the check fails, an error will be raised.
+        :rtype: ~azure.core.polling.LROPoller[None]
         """
         polling_interval: int = kwargs.pop("_polling_interval", 5)
         continuation_token: Optional[str] = kwargs.pop("continuation_token", None)
@@ -380,7 +375,7 @@ def begin_pre_restore(  # pylint: disable=docstring-keyword-should-match-keyword
 
         return self._client.begin_pre_full_restore_operation(
             pre_restore_operation_parameters=parameters,
-            cls=KeyVaultRestoreOperation._from_generated,  # pylint: disable=protected-access
+            cls=lambda *_: None,  # poller.result() returns None
             polling=KeyVaultBackupClientPollingMethod(
                 lro_algorithms=[KeyVaultBackupClientPolling()], timeout=polling_interval, **kwargs
             ),

sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_models.py

@@ -2,7 +2,6 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
-from datetime import datetime
 from typing import Any, Dict, Optional, Union
 
 from azure.core.rest import HttpResponse
@@ -11,7 +10,6 @@
 from ._generated.models import (
     FullBackupOperation,
     Permission,
-    RestoreOperation,
     RoleAssignment,
     RoleAssignmentProperties,
     RoleAssignmentPropertiesWithScope,
@@ -155,50 +153,6 @@ def _from_generated(cls, definition: RoleDefinition) -> "KeyVaultRoleDefinition"
         )
 
 
-class KeyVaultBackupOperation:
-    """The details of a Key Vault backup operation.
-
-    :ivar str status: The status of the backup operation.
-    :ivar str status_details: The status details of the backup operation.
-    :ivar str error: The error details of the backup operation.
-    :ivar start_time: The start time of the backup operation in UTC.
-    :vartype start_time: ~datetime.datetime or None
-    :ivar end_time: The end time of the backup operation in UTC.
-    :vartype end_time: ~datetime.datetime or None
-    :ivar str job_id: The job identifier of the backup operation.
-    :ivar str folder_url: The URL of the Azure Blob Storage container where the backup is stored.
-    """
-
-    # pylint:disable=unused-argument
-
-    def __init__(self, **kwargs: Any) -> None:
-        self.status: Optional[str] = kwargs.get("status")
-        self.status_details: Optional[str] = kwargs.get("status_details")
-        self.error: Optional[str] = kwargs.get("error")
-        self.start_time: Optional[datetime] = kwargs.get("start_time")
-        self.end_time: Optional[datetime] = kwargs.get("end_time")
-        self.job_id: Optional[str] = kwargs.get("job_id")
-        self.folder_url: Optional[str] = kwargs.get("folder_url")
-
-    @classmethod
-    def _from_generated(
-        cls, response: HttpResponse, deserialized_operation: FullBackupOperation, response_headers: Dict
-    ) -> "KeyVaultBackupOperation":
-        error = deserialized_operation.error
-        error_message: Optional[str] = None
-        if error and error.message:
-            error_message = f"{error.code}: {error.message}"
-        return cls(
-            status=deserialized_operation.status,
-            status_details=deserialized_operation.status_details,
-            error=error_message,
-            start_time=deserialized_operation.start_time,
-            end_time=deserialized_operation.end_time,
-            job_id=deserialized_operation.job_id,
-            folder_url=deserialized_operation.azure_storage_blob_container_uri,
-        )
-
-
 class KeyVaultBackupResult(object):
     """A Key Vault full backup operation result
 
@@ -217,47 +171,6 @@ def _from_generated(
         return cls(folder_url=deserialized_operation.azure_storage_blob_container_uri)
 
 
-class KeyVaultRestoreOperation:
-    """The details of a Key Vault restore operation.
-
-    :ivar str status: The status of the restore operation.
-    :ivar str status_details: The status details of the restore operation.
-    :ivar str error: The error details of the restore operation.
-    :ivar start_time: The start time of the restore operation in UTC.
-    :vartype start_time: ~datetime.datetime or None
-    :ivar end_time: The end time of the restore operation in UTC.
-    :vartype end_time: ~datetime.datetime or None
-    :ivar str job_id: The job identifier of the restore operation.
-    """
-
-    # pylint:disable=unused-argument
-
-    def __init__(self, **kwargs: Any) -> None:
-        self.status: Optional[str] = kwargs.get("status")
-        self.status_details: Optional[str] = kwargs.get("status_details")
-        self.error: Optional[str] = kwargs.get("error")
-        self.start_time: Optional[datetime] = kwargs.get("start_time")
-        self.end_time: Optional[datetime] = kwargs.get("end_time")
-        self.job_id: Optional[str] = kwargs.get("job_id")
-
-    @classmethod
-    def _from_generated(
-        cls, response: HttpResponse, deserialized_operation: RestoreOperation, response_headers: Dict
-    ) -> "KeyVaultRestoreOperation":
-        error = deserialized_operation.error
-        error_message: Optional[str] = None
-        if error and error.message:
-            error_message = f"{error.code}: {error.message}"
-        return cls(
-            status=deserialized_operation.status,
-            status_details=deserialized_operation.status_details,
-            error=error_message,
-            start_time=deserialized_operation.start_time,
-            end_time=deserialized_operation.end_time,
-            job_id=deserialized_operation.job_id,
-        )
-
-
 class KeyVaultSetting(object):
     """A Key Vault setting.