[Key Vault] Update docstrings for next-pylint (#30699)

Author: mccoyp

Diff for: sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_access_control_client.py

@@ -53,6 +53,7 @@ def create_role_assignment(
         :keyword name: a name for the role assignment. Must be a UUID.
         :paramtype name: str or uuid.UUID or None
 
+        :returns: The created role assignment.
         :rtype: ~azure.keyvault.administration.KeyVaultRoleAssignment
         """
         name = kwargs.pop("name", None) or uuid4()
@@ -84,6 +85,7 @@ def delete_role_assignment(
         :type name: str or uuid.UUID
 
         :returns: None
+        :rtype: None
         """
         try:
             self._client.role_assignments.delete(
@@ -104,6 +106,7 @@ def get_role_assignment(
         :param name: the role assignment's name.
         :type name: str or uuid.UUID
 
+        :returns: The fetched role assignment.
         :rtype: ~azure.keyvault.administration.KeyVaultRoleAssignment
         """
         assignment = self._client.role_assignments.get(
@@ -121,6 +124,7 @@ def list_role_assignments(
             Specify a narrower scope as a string.
         :type scope: str or KeyVaultRoleScope
 
+        :returns: A paged response containing the role assignments for the specified scope.
         :rtype: ~azure.core.paging.ItemPaged[~azure.keyvault.administration.KeyVaultRoleAssignment]
         """
         return self._client.role_assignments.list_for_scope(
@@ -200,6 +204,7 @@ def get_role_definition(
         :param name: the role definition's name.
         :type name: str or uuid.UUID
 
+        :returns: The fetched role definition.
         :rtype: ~azure.keyvault.administration.KeyVaultRoleDefinition
         """
         definition = self._client.role_definitions.get(
@@ -220,6 +225,7 @@ def delete_role_definition(
         :type name: str or uuid.UUID
 
         :returns: None
+        :rtype: None
         """
         try:
             self._client.role_definitions.delete(
@@ -238,6 +244,7 @@ def list_role_definitions(
             Specify a narrower scope as a string.
         :type scope: str or KeyVaultRoleScope
 
+        :returns: A paged response containing the role definitions for the specified scope.
         :rtype: ~azure.core.paging.ItemPaged[~azure.keyvault.administration.KeyVaultRoleDefinition]
         """
         return self._client.role_definitions.list(

Diff for: sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_backup_client.py

@@ -6,16 +6,16 @@
 import functools
 import pickle
 from typing import TYPE_CHECKING
-
 from urllib.parse import urlparse
 
+from azure.core.tracing.decorator import distributed_trace
+
 from ._models import KeyVaultBackupResult
 from ._internal import KeyVaultClientBase, parse_folder_url
 from ._internal.polling import KeyVaultBackupClientPolling, KeyVaultBackupClientPollingMethod
 
 if TYPE_CHECKING:
     # pylint:disable=unused-import
-    from typing import Any
     from azure.core.polling import LROPoller
 
 
@@ -42,6 +42,7 @@ class KeyVaultBackupClient(KeyVaultClientBase):
     """
 
     # pylint:disable=protected-access
+    @distributed_trace
     def begin_backup(
         self, blob_storage_url: str, sas_token: str, **kwargs
     ) -> "LROPoller[KeyVaultBackupResult]":
@@ -98,6 +99,7 @@ def begin_backup(
             **kwargs
         )
 
+    @distributed_trace
     def begin_restore(self, folder_url: str, sas_token: str, **kwargs) -> "LROPoller":
         """Restore a Key Vault backup.
 
@@ -111,6 +113,8 @@ def begin_restore(self, folder_url: str, sas_token: str, **kwargs) -> "LROPoller
         :keyword str continuation_token: a continuation token to restart polling from a saved state
         :keyword str key_name: name of a single key in the backup. When set, only this key will be restored.
 
+        :returns: An :class:`~azure.core.polling.LROPoller` instance. Call `wait()` or `result()` on this object to wait
+            for the operation to complete (the return value is None in either case).
         :rtype: ~azure.core.polling.LROPoller
 
         Examples:

Diff for: sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_internal/__init__.py

@@ -26,8 +26,8 @@
 def parse_vault_id(url: str) -> "_VaultId":
     try:
         parsed_uri = urlparse(url)
-    except Exception:  # pylint: disable=broad-except
-        raise ValueError(f"'{url}' is not a valid url")
+    except Exception as exc:  # pylint: disable=broad-except
+        raise ValueError(f"'{url}' is not a valid url") from exc
     if not (parsed_uri.scheme and parsed_uri.hostname):
         raise ValueError(f"'{url}' is not a valid url")
 
@@ -52,14 +52,19 @@ def parse_folder_url(folder_url: str) -> "BackupLocation":
 
     For example, https://<account>.blob.core.windows.net/backup/mhsm-account-2020090117323313 parses to
     (container_url="https://<account>.blob.core.windows.net/backup", folder_name="mhsm-account-2020090117323313").
+
+    :param str folder_url: The URL to a backup's blob storage folder.
+
+    :returns: A named tuple with a `container_url` and `folder_name`, representing the location of the backup.
+    :rtype: BackupLocation
     """
 
     try:
         parsed = urlparse(folder_url)
 
         # the first segment of the path is the container name
         stripped_path = parsed.path.strip("/")
-        container = stripped_path.split("/")[0]
+        container = stripped_path.split("/", maxsplit=1)[0]
 
         # the rest of the path is the folder name
         folder_name = stripped_path[len(container) + 1 :]
@@ -68,11 +73,11 @@ def parse_folder_url(folder_url: str) -> "BackupLocation":
         container_url = f"{parsed.scheme}://{parsed.netloc}/{container}"
 
         return BackupLocation(container_url, folder_name)
-    except:  # pylint:disable=broad-except
+    except Exception as exc:  # pylint:disable=broad-except
         raise ValueError(
             '"folder_url" should be the URL of a blob holding a Key Vault backup, for example '
             '"https://<account>.blob.core.windows.net/backup/mhsm-account-2020090117323313"'
-        )
+        ) from exc
 
 
 try:

Diff for: sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_internal/async_challenge_auth_policy.py

@@ -24,19 +24,24 @@
 from .challenge_auth_policy import _enforce_tls, _update_challenge
 
 if TYPE_CHECKING:
-    from typing import Any, Optional
+    from typing import Optional
     from azure.core.credentials import AccessToken
     from azure.core.credentials_async import AsyncTokenCredential
     from azure.core.pipeline import PipelineRequest, PipelineResponse
 
 
 class AsyncChallengeAuthPolicy(AsyncBearerTokenCredentialPolicy):
-    """policy for handling HTTP authentication challenges"""
+    """Policy for handling HTTP authentication challenges.
+
+    :param credential: An object which can provide an access token for the vault, such as a credential from
+        :mod:`azure.identity.aio`
+    :type credential: :class:`~azure.core.credentials_async.AsyncTokenCredential`
+    """
 
     def __init__(self, credential: "AsyncTokenCredential", *scopes: str, **kwargs) -> None:
         super().__init__(credential, *scopes, **kwargs)
         self._credential = credential
-        self._token = None  # type: Optional[AccessToken]
+        self._token: "Optional[AccessToken]" = None
         self._verify_challenge_resource = kwargs.pop("verify_challenge_resource", True)
 
     async def on_request(self, request: "PipelineRequest") -> None:

Diff for: sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_internal/async_client_base.py

@@ -62,11 +62,11 @@ def __init__(self, vault_url: str, credential: "AsyncTokenCredential", **kwargs)
                 **kwargs
             )
             self._models = _KeyVaultClient.models(api_version=self.api_version)
-        except ValueError:
+        except ValueError as exc:
             raise NotImplementedError(
                 f"This package doesn't support API version '{self.api_version}'. "
                 + f"Supported versions: {', '.join(v.value for v in ApiVersion)}"
-            )
+            ) from exc
 
     @property
     def vault_url(self) -> str:

Diff for: sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_internal/challenge_auth_policy.py

@@ -15,6 +15,7 @@
 """
 
 import time
+from typing import TYPE_CHECKING
 from urllib.parse import urlparse
 
 from azure.core.exceptions import ServiceRequestError
@@ -24,13 +25,8 @@
 from .http_challenge import HttpChallenge
 from . import http_challenge_cache as ChallengeCache
 
-try:
-    from typing import TYPE_CHECKING
-except ImportError:
-    TYPE_CHECKING = False
-
 if TYPE_CHECKING:
-    from typing import Any, Optional
+    from typing import Optional
     from azure.core.credentials import AccessToken, TokenCredential
     from azure.core.pipeline import PipelineResponse
 
@@ -43,7 +39,16 @@ def _enforce_tls(request: PipelineRequest) -> None:
 
 
 def _update_challenge(request: PipelineRequest, challenger: "PipelineResponse") -> HttpChallenge:
-    """Parse challenge from challenger, cache it, return it"""
+    """Parse challenge from a challenge response, cache it, and return it.
+
+    :param request: The pipeline request that prompted the challenge response.
+    :type request: :class:`~azure.core.pipeline.PipelineRequest`
+    :param challenger: The pipeline response containing the authentication challenge.
+    :type challenger: :class:`~azure.core.pipeline.PipelineResponse`
+
+    :returns: An HttpChallenge object representing the authentication challenge.
+    :rtype: HttpChallenge
+    """
 
     challenge = HttpChallenge(
         request.http_request.url,
@@ -55,12 +60,17 @@ def _update_challenge(request: PipelineRequest, challenger: "PipelineResponse")
 
 
 class ChallengeAuthPolicy(BearerTokenCredentialPolicy):
-    """Policy for handling HTTP authentication challenges"""
+    """Policy for handling HTTP authentication challenges.
+
+    :param credential: An object which can provide an access token for the vault, such as a credential from
+        :mod:`azure.identity`
+    :type credential: :class:`~azure.core.credentials.TokenCredential`
+    """
 
     def __init__(self, credential: "TokenCredential", *scopes: str, **kwargs) -> None:
         super(ChallengeAuthPolicy, self).__init__(credential, *scopes, **kwargs)
         self._credential = credential
-        self._token = None  # type: Optional[AccessToken]
+        self._token: "Optional[AccessToken]" = None
         self._verify_challenge_resource = kwargs.pop("verify_challenge_resource", True)
 
     def on_request(self, request: PipelineRequest) -> None:

Diff for: sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_internal/client_base.py

@@ -39,7 +39,15 @@ class ApiVersion(str, Enum, metaclass=CaseInsensitiveEnumMeta):
 
 
 def _format_api_version(request: "HttpRequest", api_version: str) -> "HttpRequest":
-    """Returns a request copy that includes an api-version query parameter if one wasn't originally present."""
+    """Returns a request copy that includes an api-version query parameter if one wasn't originally present.
+
+    :param request: The HTTP request being sent.
+    :type request: :class:`~azure.core.rest.HttpRequest`
+    :param str api_version: The service API version that the request should include.
+
+    :returns: A copy of the request that includes an api-version query parameter.
+    :rtype: :class:`~azure.core.rest.HttpRequest`
+    """
     request_copy = deepcopy(request)
     params = {"api-version": api_version}  # By default, we want to use the client's API version
     query = urlparse(request_copy.url).query
@@ -97,11 +105,11 @@ def __init__(self, vault_url: str, credential: "TokenCredential", **kwargs) -> N
                 **kwargs
             )
             self._models = _KeyVaultClient.models(api_version=self.api_version)
-        except ValueError:
+        except ValueError as exc:
             raise NotImplementedError(
                 f"This package doesn't support API version '{self.api_version}'. "
                 + f"Supported versions: {', '.join(v.value for v in ApiVersion)}"
-            )
+            ) from exc
 
     @property
     def vault_url(self) -> str: