azure-identity docstrings (#6004)

Author: chlowell

sdk/identity/azure-identity/azure/identity/__init__.py

@@ -2,7 +2,7 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License. See LICENSE.txt in the project root for
 # license information.
-# --------------------------------------------------------------------------
+# -------------------------------------------------------------------------
 from .credentials import (
     CertificateCredential,
     ClientSecretCredential,
@@ -13,7 +13,15 @@
 
 
 class DefaultAzureCredential(ChainedTokenCredential):
-    """default credential is environment followed by MSI/IMDS"""
+    """
+    A default credential capable of handling most Azure SDK authentication scenarios.
+
+    When environment variable configuration is present, it authenticates as a service principal
+    using :class:`identity.EnvironmentCredential`.
+
+    When environment configuration is not present, it authenticates with a managed identity
+    using :class:`identity.ManagedIdentityCredential`.
+    """
 
     def __init__(self, **kwargs):
         super(DefaultAzureCredential, self).__init__(

sdk/identity/azure-identity/azure/identity/_authn_client.py

@@ -112,7 +112,17 @@ def _prepare_request(self, method="POST", headers=None, form_data=None, params=N
 
 
 class AuthnClient(AuthnClientBase):
-    """Synchronous authentication client"""
+    """
+    Synchronous authentication client.
+
+    :param str auth_url:
+    :param config: Optional configuration for the HTTP pipeline.
+    :type config: :class:`azure.core.configuration`
+    :param policies: Optional policies for the HTTP pipeline.
+    :type policies:
+    :param transport: Optional HTTP transport.
+    :type transport:
+    """
 
     def __init__(self, auth_url, config=None, policies=None, transport=None, **kwargs):
         # type: (str, Optional[Configuration], Optional[Iterable[HTTPPolicy]], Optional[HttpTransport], Mapping[str, Any]) -> None

sdk/identity/azure-identity/azure/identity/_base.py

@@ -2,7 +2,7 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License. See LICENSE.txt in the project root for
 # license information.
-# --------------------------------------------------------------------------
+# -------------------------------------------------------------------------
 import binascii
 
 from cryptography import x509
@@ -23,6 +23,8 @@
 
 
 class ClientSecretCredentialBase(object):
+    """Sans I/O base for client secret credentials"""
+
     def __init__(self, client_id, secret, tenant_id, **kwargs):
         # type: (str, str, str, Mapping[str, Any]) -> None
         if not client_id:
@@ -38,6 +40,8 @@ def __init__(self, client_id, secret, tenant_id, **kwargs):
 
 
 class CertificateCredentialBase(object):
+    """Sans I/O base for certificate credentials"""
+
     def __init__(self, client_id, tenant_id, certificate_path, **kwargs):
         # type: (str, str, str, Mapping[str, Any]) -> None
         if not certificate_path:

sdk/identity/azure-identity/azure/identity/_internal.py

@@ -24,6 +24,8 @@
 
 
 class _ManagedIdentityBase(object):
+    """Sans I/O base for managed identity credentials"""
+
     def __init__(self, endpoint, client_cls, config=None, client_id=None, **kwargs):
         # type: (str, Type, Optional[Configuration], Optional[str], Any) -> None
         self._client_id = client_id
@@ -34,6 +36,11 @@ def __init__(self, endpoint, client_cls, config=None, client_id=None, **kwargs):
     @staticmethod
     def create_config(**kwargs):
         # type: (Mapping[str, Any]) -> Configuration
+        """
+        Build a default configuration for the credential's HTTP pipeline.
+
+        :rtype: :class:`azure.core.configuration`
+        """
         timeout = kwargs.pop("connection_timeout", 2)
         config = Configuration(connection_timeout=timeout, **kwargs)
 
@@ -61,7 +68,12 @@ def create_config(**kwargs):
 
 
 class ImdsCredential(_ManagedIdentityBase):
-    """Authenticates with a managed identity via the IMDS endpoint"""
+    """
+    Authenticates with a managed identity via the IMDS endpoint.
+
+    :param config: optional configuration for the underlying HTTP pipeline
+    :type config: :class:`azure.core.configuration`
+    """
 
     def __init__(self, config=None, **kwargs):
         # type: (Optional[Configuration], Any) -> None
@@ -70,6 +82,13 @@ def __init__(self, config=None, **kwargs):
 
     def get_token(self, *scopes):
         # type: (*str) -> AccessToken
+        """
+        Request an access token for `scopes`.
+
+        :param str scopes: desired scopes for the token
+        :rtype: :class:`azure.core.credentials.AccessToken`
+        :raises: :class:`azure.core.exceptions.ClientAuthenticationError`
+        """
         if self._endpoint_available is None:
             # Lacking another way to determine whether the IMDS endpoint is listening,
             # we send a request it would immediately reject (missing a required header),
@@ -103,7 +122,12 @@ def get_token(self, *scopes):
 
 
 class MsiCredential(_ManagedIdentityBase):
-    """Authenticates via the MSI endpoint in App Service or Cloud Shell"""
+    """
+    Authenticates via the MSI endpoint in an App Service or Cloud Shell environment.
+
+    :param config: optional configuration for the underlying HTTP pipeline
+    :type config: :class:`azure.core.configuration`
+    """
 
     def __init__(self, config=None, **kwargs):
         # type: (Optional[Configuration], Mapping[str, Any]) -> None
@@ -116,6 +140,14 @@ def __init__(self, config=None, **kwargs):
 
     def get_token(self, *scopes):
         # type: (*str) -> AccessToken
+        """
+        Request an access token for `scopes`.
+
+        :param str scopes: desired scopes for the token
+        :rtype: :class:`azure.core.credentials.AccessToken`
+        :raises: :class:`azure.core.exceptions.ClientAuthenticationError`
+        """
+
         if not self._endpoint_available:
             raise ClientAuthenticationError(message="MSI endpoint unavailable")
 

sdk/identity/azure-identity/azure/identity/aio/__init__.py

@@ -13,7 +13,15 @@
 
 
 class AsyncDefaultAzureCredential(AsyncChainedTokenCredential):
-    """default credential is environment followed by MSI/IMDS"""
+    """
+    A default credential capable of handling most Azure SDK authentication scenarios.
+
+    When environment variable configuration is present, it authenticates as a service principal
+    using :class:`identity.aio.AsyncEnvironmentCredential`.
+
+    When environment configuration is not present, it authenticates with a managed identity
+    using :class:`identity.aio.AsyncManagedIdentityCredential`.
+    """
 
     def __init__(self, **kwargs):
         super().__init__(AsyncEnvironmentCredential(**kwargs), AsyncManagedIdentityCredential(**kwargs))

sdk/identity/azure-identity/azure/identity/aio/_internal.py

@@ -22,15 +22,34 @@ def __init__(self, endpoint: str, config: Optional[Configuration] = None, **kwar
 
     @staticmethod
     def create_config(**kwargs: Any) -> Configuration:  # type: ignore
+        """
+        Build a default configuration for the credential's HTTP pipeline.
+
+        :rtype: :class:`azure.core.configuration`
+        """
         return _ManagedIdentityBase.create_config(retry_policy=AsyncRetryPolicy, **kwargs)
 
 
 class AsyncImdsCredential(_AsyncManagedIdentityBase):
+    """
+    Asynchronously authenticates with a managed identity via the IMDS endpoint.
+
+    :param config: optional configuration for the underlying HTTP pipeline
+    :type config: :class:`azure.core.configuration`
+    """
+
     def __init__(self, config: Optional[Configuration] = None, **kwargs: Any) -> None:
         super().__init__(endpoint=Endpoints.IMDS, config=config, **kwargs)
         self._endpoint_available = None  # type: Optional[bool]
 
     async def get_token(self, *scopes: str) -> AccessToken:
+        """
+        Asynchronously request an access token for `scopes`.
+
+        :param str scopes: desired scopes for the token
+        :rtype: :class:`azure.core.credentials.AccessToken`
+        :raises: :class:`azure.core.exceptions.ClientAuthenticationError`
+        """
         if self._endpoint_available is None:
             # Lacking another way to determine whether the IMDS endpoint is listening,
             # we send a request it would immediately reject (missing a required header),
@@ -65,13 +84,27 @@ async def get_token(self, *scopes: str) -> AccessToken:
 
 
 class AsyncMsiCredential(_AsyncManagedIdentityBase):
+    """
+    Authenticates via the MSI endpoint in an App Service or Cloud Shell environment.
+
+    :param config: optional configuration for the underlying HTTP pipeline
+    :type config: :class:`azure.core.configuration`
+    """
+
     def __init__(self, config: Optional[Configuration] = None, **kwargs: Any) -> None:
         endpoint = os.environ.get(EnvironmentVariables.MSI_ENDPOINT)
         self._endpoint_available = endpoint is not None
         if self._endpoint_available:
             super().__init__(endpoint=endpoint, config=config, **kwargs)  # type: ignore
 
     async def get_token(self, *scopes: str) -> AccessToken:
+        """
+        Asynchronously request an access token for `scopes`.
+
+        :param str scopes: desired scopes for the token
+        :rtype: :class:`azure.core.credentials.AccessToken`
+        :raises: :class:`azure.core.exceptions.ClientAuthenticationError`
+        """
         if not self._endpoint_available:
             raise ClientAuthenticationError(message="MSI endpoint unavailable")