[Key Vault] Arch board feedback and language alignment (Azure#23286)

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

@@ -5,6 +5,17 @@
 ### Features Added
 
 ### Breaking Changes
+> These changes do not impact the API of stable versions such as 4.4.0.
+> Only code written against a beta version such as 4.5.0b1 may be affected.
+- `KeyClient.update_key_rotation_policy` accepts a required `policy` argument
+  ([#22981](https://github.com/Azure/azure-sdk-for-python/issues/22981))
+- The optional `version` parameter in `KeyClient.release_key` is now a keyword-only argument
+  ([#22981](https://github.com/Azure/azure-sdk-for-python/issues/22981))
+- Renamed the `name` parameter in `KeyClient.get_key_rotation_policy` and
+  `KeyClient.update_key_rotation_policy` to `key_name`
+  ([#22981](https://github.com/Azure/azure-sdk-for-python/issues/22981))
+- Enum values in `azure-keyvault-keys` are now uniformly lower-cased
+  ([#22981](https://github.com/Azure/azure-sdk-for-python/issues/22981))
 
 ### Bugs Fixed
 - `KeyType` now ignores casing during declaration, which resolves a scenario where Key Vault

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/_client.py

@@ -689,18 +689,17 @@ def import_key(self, name, key, **kwargs):
         return KeyVaultKey._from_key_bundle(bundle)
 
     @distributed_trace
-    def release_key(self, name, target_attestation_token, version=None, **kwargs):
-        # type: (str, str, Optional[str], **Any) -> ReleaseKeyResult
+    def release_key(self, name, target_attestation_token, **kwargs):
+        # type: (str, str, **Any) -> ReleaseKeyResult
         """Releases a key.
 
         The release key operation is applicable to all key types. The target key must be marked
         exportable. This operation requires the keys/release permission.
 
         :param str name: The name of the key to get.
         :param str target_attestation_token: The attestation assertion for the target of the key release.
-        :param str version: (optional) A specific version of the key to release. If unspecified, the latest version is
-            released.
 
+        :keyword str version: A specific version of the key to release. If unspecified, the latest version is released.
         :keyword algorithm: The encryption algorithm to use to protect the released key material.
         :paramtype algorithm: ~azure.keyvault.keys.KeyExportEncryptionAlgorithm
         :keyword str nonce: A client-provided nonce for freshness.
@@ -709,10 +708,11 @@ def release_key(self, name, target_attestation_token, version=None, **kwargs):
         :rtype: ~azure.keyvault.keys.ReleaseKeyResult
         :raises: :class:`~azure.core.exceptions.HttpResponseError`
         """
+        version = kwargs.pop("version", "")
         result = self._client.release(
             vault_base_url=self._vault_url,
             key_name=name,
-            key_version=version or "",
+            key_version=version,
             parameters=self._models.KeyReleaseParameters(
                 target_attestation_token=target_attestation_token,
                 nonce=kwargs.pop("nonce", None),
@@ -750,17 +750,17 @@ def get_random_bytes(self, count, **kwargs):
         return result.value
 
     @distributed_trace
-    def get_key_rotation_policy(self, name, **kwargs):
+    def get_key_rotation_policy(self, key_name, **kwargs):
         # type: (str, **Any) -> KeyRotationPolicy
         """Get the rotation policy of a Key Vault key.
 
-        :param str name: The name of the key.
+        :param str key_name: The name of the key.
 
         :return: The key rotation policy.
         :rtype: ~azure.keyvault.keys.KeyRotationPolicy
         :raises: :class: `~azure.core.exceptions.HttpResponseError`
         """
-        policy = self._client.get_key_rotation_policy(vault_base_url=self._vault_url, key_name=name, **kwargs)
+        policy = self._client.get_key_rotation_policy(vault_base_url=self._vault_url, key_name=key_name, **kwargs)
         return KeyRotationPolicy._from_generated(policy)
 
     @distributed_trace
@@ -780,25 +780,29 @@ def rotate_key(self, name, **kwargs):
         return KeyVaultKey._from_key_bundle(bundle)
 
     @distributed_trace
-    def update_key_rotation_policy(self, name, **kwargs):
-        # type: (str, **Any) -> KeyRotationPolicy
+    def update_key_rotation_policy(self, key_name, policy, **kwargs):
+        # type: (str, KeyRotationPolicy, **Any) -> KeyRotationPolicy
         """Updates the rotation policy of a Key Vault key.
 
         This operation requires the keys/update permission.
 
-        :param str name: The name of the key in the given vault.
+        :param str key_name: The name of the key in the given vault.
+        :param policy: The new rotation policy for the key.
+        :type policy: ~azure.keyvault.keys.KeyRotationPolicy
 
-        :keyword lifetime_actions: Actions that will be performed by Key Vault over the lifetime of a key.
+        :keyword lifetime_actions: Actions that will be performed by Key Vault over the lifetime of a key. This will
+            override the lifetime actions of the provided ``policy``.
         :paramtype lifetime_actions: Iterable[~azure.keyvault.keys.KeyRotationLifetimeAction]
         :keyword str expires_in: The expiry time of the policy that will be applied on new key versions, defined as an
             ISO 8601 duration. For example: 90 days is "P90D", 3 months is "P3M", and 48 hours is "PT48H". See
             `Wikipedia <https://wikipedia.org/wiki/ISO_8601#Durations>`_ for more information on ISO 8601 durations.
+            This will override the expiry time of the provided ``policy``.
 
         :return: The updated rotation policy.
         :rtype: ~azure.keyvault.keys.KeyRotationPolicy
         :raises: :class:`~azure.core.exceptions.HttpResponseError`
         """
-        lifetime_actions = kwargs.pop("lifetime_actions", None)
+        lifetime_actions = kwargs.pop("lifetime_actions", policy.lifetime_actions)
         if lifetime_actions:
             lifetime_actions = [
                 self._models.LifetimeActions(
@@ -810,9 +814,9 @@ def update_key_rotation_policy(self, name, **kwargs):
                 for action in lifetime_actions
             ]
 
-        attributes = self._models.KeyRotationPolicyAttributes(expiry_time=kwargs.pop("expires_in", None))
-        policy = self._models.KeyRotationPolicy(lifetime_actions=lifetime_actions, attributes=attributes)
+        attributes = self._models.KeyRotationPolicyAttributes(expiry_time=kwargs.pop("expires_in", policy.expires_in))
+        new_policy = self._models.KeyRotationPolicy(lifetime_actions=lifetime_actions, attributes=attributes)
         result = self._client.update_key_rotation_policy(
-            vault_base_url=self._vault_url, key_name=name, key_rotation_policy=policy
+            vault_base_url=self._vault_url, key_name=key_name, key_rotation_policy=new_policy
         )
         return KeyRotationPolicy._from_generated(result)

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/_enums.py

@@ -21,9 +21,9 @@ class KeyCurveName(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
 class KeyExportEncryptionAlgorithm(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
     """Supported algorithms for protecting exported key material"""
 
-    CKM_RSA_AES_KEY_WRAP = "CKM_RSA_AES_KEY_WRAP"
-    RSA_AES_KEY_WRAP_256 = "RSA_AES_KEY_WRAP_256"
-    RSA_AES_KEY_WRAP_384 = "RSA_AES_KEY_WRAP_384"
+    ckm_rsa_aes_key_wrap = "CKM_RSA_AES_KEY_WRAP"
+    rsa_aes_key_wrap_256 = "RSA_AES_KEY_WRAP_256"
+    rsa_aes_key_wrap_384 = "RSA_AES_KEY_WRAP_384"
 
 
 class KeyOperation(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
@@ -42,8 +42,8 @@ class KeyOperation(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
 class KeyRotationPolicyAction(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):
     """The action that will be executed in a key rotation policy"""
 
-    ROTATE = "Rotate"  #: Rotate the key based on the key policy.
-    NOTIFY = "Notify"  #: Trigger Event Grid events.
+    rotate = "Rotate"  #: Rotate the key based on the key policy.
+    notify = "Notify"  #: Trigger Event Grid events.
 
 
 class KeyType(with_metaclass(CaseInsensitiveEnumMeta, str, Enum)):

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

@@ -320,18 +320,18 @@ class KeyRotationPolicy(object):
     :ivar str id: The identifier of the key rotation policy.
     :ivar lifetime_actions: Actions that will be performed by Key Vault over the lifetime of a key.
     :type lifetime_actions: list[~azure.keyvault.keys.KeyRotationLifetimeAction]
-    :ivar str expires_in: The expiry time of the policy that will be applied on new key versions, defined as an ISO
-        8601 duration. For example, 90 days is "P90D".  See `Wikipedia <https://wikipedia.org/wiki/ISO_8601#Durations>`_
-        for more information on ISO 8601 durations.
+    :ivar str expires_in: The expiry time of the policy that will be applied on new key versions, defined as an ISO 8601
+        duration. For example, 90 days is "P90D".  See `Wikipedia <https://wikipedia.org/wiki/ISO_8601#Durations>`_ for
+        more information on ISO 8601 durations.
     :ivar created_on: When the policy was created, in UTC
     :type created_on: ~datetime.datetime
     :ivar updated_on: When the policy was last updated, in UTC
     :type updated_on: ~datetime.datetime
     """
 
-    def __init__(self, policy_id, **kwargs):
-        # type: (str, **Any) -> None
-        self.id = policy_id
+    def __init__(self, **kwargs):
+        # type: (**Any) -> None
+        self.id = kwargs.get("policy_id", None)
         self.lifetime_actions = kwargs.get("lifetime_actions", None)
         self.expires_in = kwargs.get("expires_in", None)
         self.created_on = kwargs.get("created_on", None)

sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/aio/_client.py

@@ -675,19 +675,16 @@ async def import_key(self, name: str, key: JsonWebKey, **kwargs: "Any") -> KeyVa
         return KeyVaultKey._from_key_bundle(bundle)
 
     @distributed_trace_async
-    async def release_key(
-        self, name: str, target_attestation_token: str, version: "Optional[str]" = None, **kwargs: "Any"
-    ) -> ReleaseKeyResult:
+    async def release_key(self, name: str, target_attestation_token: str, **kwargs: "Any") -> ReleaseKeyResult:
         """Releases a key.
 
         The release key operation is applicable to all key types. The target key must be marked
         exportable. This operation requires the keys/release permission.
 
         :param str name: The name of the key to get.
         :param str target_attestation_token: The attestation assertion for the target of the key release.
-        :param str version: (optional) A specific version of the key to release. If unspecified, the latest version is
-            released.
 
+        :keyword str version: A specific version of the key to release. If unspecified, the latest version is released.
         :keyword algorithm: The encryption algorithm to use to protect the released key material.
         :paramtype algorithm: ~azure.keyvault.keys.KeyExportEncryptionAlgorithm
         :keyword str nonce: A client-provided nonce for freshness.
@@ -696,10 +693,11 @@ async def release_key(
         :rtype: ~azure.keyvault.keys.ReleaseKeyResult
         :raises: :class:`~azure.core.exceptions.HttpResponseError`
         """
+        version = kwargs.pop("version", "")
         result = await self._client.release(
             vault_base_url=self._vault_url,
             key_name=name,
-            key_version=version or "",
+            key_version=version,
             parameters=self._models.KeyReleaseParameters(
                 target_attestation_token=target_attestation_token,
                 nonce=kwargs.pop("nonce", None),
@@ -736,16 +734,16 @@ async def get_random_bytes(self, count: int, **kwargs: "Any") -> bytes:
         return result.value
 
     @distributed_trace_async
-    async def get_key_rotation_policy(self, name: str, **kwargs: "Any") -> "KeyRotationPolicy":
+    async def get_key_rotation_policy(self, key_name: str, **kwargs: "Any") -> "KeyRotationPolicy":
         """Get the rotation policy of a Key Vault key.
 
-        :param str name: The name of the key.
+        :param str key_name: The name of the key.
 
         :return: The key rotation policy.
         :rtype: ~azure.keyvault.keys.KeyRotationPolicy
         :raises: :class:`~azure.core.exceptions.HttpResponseError`
         """
-        policy = await self._client.get_key_rotation_policy(vault_base_url=self._vault_url, key_name=name, **kwargs)
+        policy = await self._client.get_key_rotation_policy(vault_base_url=self._vault_url, key_name=key_name, **kwargs)
         return KeyRotationPolicy._from_generated(policy)
 
     @distributed_trace_async
@@ -764,24 +762,30 @@ async def rotate_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:
         return KeyVaultKey._from_key_bundle(bundle)
 
     @distributed_trace_async
-    async def update_key_rotation_policy(self, name: str, **kwargs: "Any") -> KeyRotationPolicy:
+    async def update_key_rotation_policy(
+        self, key_name: str, policy: KeyRotationPolicy, **kwargs: "Any"
+    ) -> KeyRotationPolicy:
         """Updates the rotation policy of a Key Vault key.
 
         This operation requires the keys/update permission.
 
-        :param str name: The name of the key in the given vault.
+        :param str key_name: The name of the key in the given vault.
+        :param policy: The new rotation policy for the key.
+        :type policy: ~azure.keyvault.keys.KeyRotationPolicy
 
-        :keyword lifetime_actions: Actions that will be performed by Key Vault over the lifetime of a key.
+        :keyword lifetime_actions: Actions that will be performed by Key Vault over the lifetime of a key. This will
+            override the lifetime actions of the provided ``policy``.
         :paramtype lifetime_actions: Iterable[~azure.keyvault.keys.KeyRotationLifetimeAction]
         :keyword str expires_in: The expiry time of the policy that will be applied on new key versions, defined as an
             ISO 8601 duration. For example: 90 days is "P90D", 3 months is "P3M", and 48 hours is "PT48H". See
             `Wikipedia <https://wikipedia.org/wiki/ISO_8601#Durations>`_ for more information on ISO 8601 durations.
+            This will override the expiry time of the provided ``policy``.
 
         :return: The updated rotation policy.
         :rtype: ~azure.keyvault.keys.KeyRotationPolicy
         :raises: :class:`~azure.core.exceptions.HttpResponseError`
         """
-        lifetime_actions = kwargs.pop("lifetime_actions", None)
+        lifetime_actions = kwargs.pop("lifetime_actions", policy.lifetime_actions)
         if lifetime_actions:
             lifetime_actions = [
                 self._models.LifetimeActions(
@@ -793,9 +797,9 @@ async def update_key_rotation_policy(self, name: str, **kwargs: "Any") -> KeyRot
                 for action in lifetime_actions
             ]
 
-        attributes = self._models.KeyRotationPolicyAttributes(expiry_time=kwargs.pop("expires_in", None))
-        policy = self._models.KeyRotationPolicy(lifetime_actions=lifetime_actions, attributes=attributes)
+        attributes = self._models.KeyRotationPolicyAttributes(expiry_time=kwargs.pop("expires_in", policy.expires_in))
+        new_policy = self._models.KeyRotationPolicy(lifetime_actions=lifetime_actions, attributes=attributes)
         result = await self._client.update_key_rotation_policy(
-            vault_base_url=self._vault_url, key_name=name, key_rotation_policy=policy
+            vault_base_url=self._vault_url, key_name=key_name, key_rotation_policy=new_policy
         )
         return KeyRotationPolicy._from_generated(result)