_ modules to clean up docs, fix some docstrings

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

@@ -2,7 +2,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
-from .browser_auth import InteractiveBrowserCredential
+from ._browser_auth import InteractiveBrowserCredential
 from .credentials import (
     CertificateCredential,
     ChainedTokenCredential,
@@ -19,10 +19,10 @@ class DefaultAzureCredential(ChainedTokenCredential):
     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`.
+    using :class:`azure.identity.EnvironmentCredential`.
 
     When environment configuration is not present, it authenticates with a managed identity
-    using :class:`identity.ManagedIdentityCredential`.
+    using :class:`azure.identity.ManagedIdentityCredential`.
     """
 
     def __init__(self, **kwargs):

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

@@ -9,7 +9,7 @@
 from cryptography.hazmat.backends import default_backend
 from msal.oauth2cli import JwtSigner
 
-from .constants import Endpoints
+from ._constants import Endpoints
 
 try:
     from typing import TYPE_CHECKING

sdk/identity/azure-identity/azure/identity/browser_auth.py → sdk/identity/azure-identity/azure/identity/_browser_auth.py

@@ -30,13 +30,13 @@ class InteractiveBrowserCredential(ConfidentialClientCredential):
     https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code
 
     :param str client_id: the application's client ID
-    :param str secret: one of the application's client secrets
+    :param str client_secret: one of the application's client secrets
 
-    **Keyword arguments:**
+    Keyword arguments
+        - *tenant (str)*: a tenant ID or a domain associated with a tenant. Defaults to the 'organizations' tenant,
+          which can authenticate work or school accounts.
+        - *timeout (int)*: seconds to wait for the user to complete authentication. Defaults to 300 (5 minutes).
 
-    *tenant (str)* - a tenant ID or a domain associated with a tenant. If not provided, the credential defaults to the
-        'organizations' tenant, which can authenticate work or school accounts.
-    *timeout (str)* - seconds to wait for the user to complete authentication. Defaults to 300 (5 minutes).
     """
 
     def __init__(self, client_id, client_secret, **kwargs):

sdk/identity/azure-identity/azure/identity/_managed_identity.py

@@ -19,7 +19,7 @@
 from azure.core.pipeline.policies import ContentDecodePolicy, HeadersPolicy, NetworkTraceLoggingPolicy, RetryPolicy
 
 from ._authn_client import AuthnClient
-from .constants import Endpoints, EnvironmentVariables
+from ._constants import Endpoints, EnvironmentVariables
 
 
 class _ManagedIdentityBase(object):

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

@@ -16,10 +16,10 @@ class DefaultAzureCredential(ChainedTokenCredential):
     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.EnvironmentCredential`.
+    using :class:`azure.identity.aio.EnvironmentCredential`.
 
     When environment configuration is not present, it authenticates with a managed identity
-    using :class:`identity.aio.ManagedIdentityCredential`.
+    using :class:`azure.identity.aio.ManagedIdentityCredential`.
     """
 
     def __init__(self, **kwargs):

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

@@ -11,7 +11,7 @@
 from azure.core.pipeline.policies import ContentDecodePolicy, HeadersPolicy, NetworkTraceLoggingPolicy, AsyncRetryPolicy
 
 from ._authn_client import AsyncAuthnClient
-from ..constants import Endpoints, EnvironmentVariables
+from .._constants import Endpoints, EnvironmentVariables
 from .._managed_identity import _ManagedIdentityBase
 
 

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

@@ -16,7 +16,7 @@
 from ._authn_client import AsyncAuthnClient
 from ._managed_identity import ImdsCredential, MsiCredential
 from .._base import ClientSecretCredentialBase, CertificateCredentialBase
-from ..constants import Endpoints, EnvironmentVariables
+from .._constants import Endpoints, EnvironmentVariables
 from ..credentials import ChainedTokenCredential as SyncChainedTokenCredential
 
 # pylint:disable=too-few-public-methods
@@ -80,18 +80,24 @@ async def get_token(self, *scopes: str) -> AccessToken:
 
 class EnvironmentCredential:
     """
-    Authenticates as a service principal using a client ID/secret pair or a certificate,
-    depending on environment variable settings.
-
-    These environment variables are required:
+    Authenticates as a service principal using a client secret or a certificate, or as a user with a username and
+    password, depending on environment variable settings. Configuration is attempted in this order, using these
+    environment variables:
 
+    Service principal with secret:
       - **AZURE_CLIENT_ID**: the service principal's client ID
+      - **AZURE_CLIENT_SECRET**: one of the service principal's client secrets
       - **AZURE_TENANT_ID**: ID of the service principal's tenant. Also called its 'directory' ID.
 
-    Additionally, set **one** of these to configure client secret or certificate authentication:
-
-      - **AZURE_CLIENT_SECRET**: one of the service principal's client secrets
+    Service principal with certificate:
+      - **AZURE_CLIENT_ID**: the service principal's client ID
       - **AZURE_CLIENT_CERTIFICATE_PATH**: path to a PEM-encoded certificate file including the private key
+      - **AZURE_TENANT_ID**: ID of the service principal's tenant. Also called its 'directory' ID.
+
+    User with username and password:
+      - **AZURE_CLIENT_ID**: the application's client ID
+      - **AZURE_USERNAME**: a username (usually an email address)
+      - **AZURE_PASSWORD**: that user's password
     """
 
     def __init__(self, **kwargs: Mapping[str, Any]) -> None:
@@ -175,7 +181,7 @@ async def get_token(self, *scopes: str) -> AccessToken:
         :raises: :class:`azure.core.exceptions.ClientAuthenticationError`
         """
         history = []
-        for credential in self._credentials:
+        for credential in self.credentials:
             try:
                 return await credential.get_token(*scopes)
             except ClientAuthenticationError as ex:

sdk/identity/azure-identity/azure/identity/credentials.py

@@ -14,10 +14,11 @@
 from azure.core.pipeline.policies import ContentDecodePolicy, HeadersPolicy, NetworkTraceLoggingPolicy, RetryPolicy
 
 from ._authn_client import AuthnClient
+from ._browser_auth import InteractiveBrowserCredential
 from ._base import ClientSecretCredentialBase, CertificateCredentialBase
 from ._internal import PublicClientCredential, wrap_exceptions
 from ._managed_identity import ImdsCredential, MsiCredential
-from .constants import Endpoints, EnvironmentVariables
+from ._constants import Endpoints, EnvironmentVariables
 
 try:
     from typing import TYPE_CHECKING
@@ -200,7 +201,7 @@ def __init__(self, *credentials):
         # type: (*TokenCredential) -> None
         if not credentials:
             raise ValueError("at least one credential is required")
-        self._credentials = credentials
+        self.credentials = credentials
 
     def get_token(self, *scopes):
         # type (*str) -> AccessToken
@@ -213,7 +214,7 @@ def get_token(self, *scopes):
         :raises: :class:`azure.core.exceptions.ClientAuthenticationError`
         """
         history = []
-        for credential in self._credentials:
+        for credential in self.credentials:
             try:
                 return credential.get_token(*scopes)
             except ClientAuthenticationError as ex:
@@ -238,28 +239,28 @@ class DeviceCodeCredential(PublicClientCredential):
     """
     Authenticates users through the device code flow. When ``get_token`` is called, this credential acquires a
     verification URL and code from Azure Active Directory. A user must browse to the URL, enter the code, and
-    authenticate with Directory. If the user authenticates successfully, the credential receives an access token.
+    authenticate with Azure Active Directory. If the user authenticates successfully, the credential receives
+    an access token.
 
     This credential doesn't cache tokens--each ``get_token`` call begins a new authentication flow.
 
     For more information about the device code flow, see Azure Active Directory documentation:
     https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code
 
     :param str client_id: the application's ID
-    :param prompt_callback: (optional) A callback enabling control of how authentication instructions are presented.
+    :param prompt_callback:
+        (optional) A callback enabling control of how authentication instructions are presented.
+        Must accept arguments (``verification_uri``, ``user_code``, ``expires_in``):
+            - ``verification_uri`` (str) the URL the user must visit
+            - ``user_code`` (str) the code the user must enter there
+            - ``expires_in`` (int) the number of seconds the code will be valid
         If not provided, the credential will print instructions to stdout.
-    :type prompt_callback: A callable accepting arguments (``verification_uri``, ``user_code``, ``expires_in``):
-        - ``verification_uri`` (str) the URL the user must visit
-        - ``user_code`` (str) the code the user must enter there
-        - ``expires_in`` (int) the number of seconds the code will be valid
 
-    **Keyword arguments:**
-
-    - *tenant (str)* - tenant ID or a domain associated with a tenant. If not provided, the credential defaults to the
-      'organizations' tenant, which supports only Azure Active Directory work or school accounts.
-
-    - *timeout (int)* - seconds to wait for the user to authenticate. Defaults to the validity period of the device code
-      as set by Azure Active Directory, which also prevails when ``timeout`` is longer.
+    Keyword arguments
+        - *tenant (str)* - tenant ID or a domain associated with a tenant. If not provided, defaults to the
+          'organizations' tenant, which supports only Azure Active Directory work or school accounts.
+        - *timeout (int)* - seconds to wait for the user to authenticate. Defaults to the validity period of the device
+          code as set by Azure Active Directory, which also prevails when ``timeout`` is longer.
 
     """
 
@@ -330,10 +331,9 @@ class UsernamePasswordCredential(PublicClientCredential):
     :param str username: the user's username (usually an email address)
     :param str password: the user's password
 
-    **Keyword arguments:**
-
-    - **tenant (str)** - a tenant ID or a domain associated with a tenant. If not provided, defaults to the
-      'organizations' tenant.
+    Keyword arguments
+        - *tenant (str)* - tenant ID or a domain associated with a tenant. If not provided, defaults to the
+          'organizations' tenant, which supports only Azure Active Directory work or school accounts.
 
     """
 

sdk/identity/azure-identity/conftest.py

@@ -6,7 +6,7 @@
 import sys
 
 import pytest
-from azure.identity.constants import EnvironmentVariables
+from azure.identity._constants import EnvironmentVariables
 
 # IMDS tests must be run explicitly
 collect_ignore_glob = ["*imds*"]  # pylint:disable=invalid-name

sdk/identity/azure-identity/tests/test_identity.py

@@ -26,7 +26,7 @@
     UsernamePasswordCredential,
 )
 from azure.identity._managed_identity import ImdsCredential
-from azure.identity.constants import EnvironmentVariables
+from azure.identity._constants import EnvironmentVariables
 import pytest
 
 from helpers import mock_response, Request, validating_transport
@@ -299,7 +299,7 @@ def test_device_code_credential_timeout():
     assert "timed out" in ex.value.message.lower()
 
 
-@patch("azure.identity.browser_auth.webbrowser.open", lambda _: None)  # prevent the credential opening a browser
+@patch("azure.identity._browser_auth.webbrowser.open", lambda _: None)  # prevent the credential opening a browser
 def test_interactive_credential():
     oauth_state = "state"
     expected_token = "access-token"
@@ -333,12 +333,12 @@ def test_interactive_credential():
     )
 
     # ensure the request beginning the flow has a known state value
-    with patch("azure.identity.browser_auth.uuid.uuid4", lambda: oauth_state):
+    with patch("azure.identity._browser_auth.uuid.uuid4", lambda: oauth_state):
         token = credential.get_token("scope")
     assert token.token == expected_token
 
 
-@patch("azure.identity.browser_auth.webbrowser.open", lambda _: None)  # prevent the credential opening a browser
+@patch("azure.identity._browser_auth.webbrowser.open", lambda _: None)  # prevent the credential opening a browser
 def test_interactive_credential_timeout():
     # mock transport handles MSAL's tenant discovery
     transport = Mock(

sdk/identity/azure-identity/tests/test_identity_async.py

@@ -20,7 +20,7 @@
     ManagedIdentityCredential,
 )
 from azure.identity.aio._managed_identity import ImdsCredential
-from azure.identity.constants import EnvironmentVariables
+from azure.identity._constants import EnvironmentVariables
 
 from helpers import mock_response, Request, async_validating_transport
 

sdk/identity/azure-identity/tests/test_live_async.py

@@ -10,7 +10,6 @@
     import mock  # type: ignore
 
 from azure.identity.aio import DefaultAzureCredential, CertificateCredential, ClientSecretCredential
-from azure.identity.constants import EnvironmentVariables
 import pytest
 
 ARM_SCOPE = "https://management.azure.com/.default"

sdk/identity/azure-identity/tests/test_managed_identity.py

@@ -11,7 +11,7 @@
 
 from azure.core.credentials import AccessToken
 from azure.identity import ManagedIdentityCredential
-from azure.identity.constants import Endpoints, EnvironmentVariables
+from azure.identity._constants import Endpoints, EnvironmentVariables
 
 
 from helpers import validating_transport, mock_response, Request

sdk/identity/azure-identity/tests/test_managed_identity_async.py

@@ -7,7 +7,7 @@
 
 from azure.core.credentials import AccessToken
 from azure.identity.aio import ManagedIdentityCredential
-from azure.identity.constants import Endpoints, EnvironmentVariables
+from azure.identity._constants import Endpoints, EnvironmentVariables
 import pytest
 
 from helpers import async_validating_transport, mock_response, Request