Refactor the AuthClient inheritance tree

- introduce AuthLoginClient and AuthServiceClient as the dividing line
  between each part of the tree
- AuthClient becomes an alias for AuthLoginClient
- the "app client" classes inherit from login client
- a new base class, AuthBaseClient, provides OIDC and JWK methods,
  base data like service name, scopes, and error class, but no other
  methods

The calls provided on AuthBaseClient are those which are simple GET
methods (and a decorated version thereof) which do not require
authentication. As such, they make sense to expose equally to all
client types.

changelog.d/20230829_122956_sirosen_loginclient.rst

@@ -0,0 +1,36 @@
+Changed
+~~~~~~~
+
+- The inheritance structure used for Globus Auth client classes has changed.
+  (:pr:`NUMBER`)
+
+  - A new class, ``AuthLoginClient``, is the base for ``NativeAppAuthClient``
+    and ``ConfidentialAppAuthClient``. These classes no longer inherit from
+    ``AuthClient``.
+
+  - ``AuthClient`` is now an alias for ``AuthServiceClient``. The new name is
+    preferred but the old name is not yet deprecated.
+
+  - ``AuthServiceClient`` is now the only class which provides functionality
+    for accessing Globus Auth APIs. Previously, some of the API accessing
+    methods were inherited by the ``AuthClient`` subclasses, but would never
+    work.
+
+  - All of these client classes descend from a common base, ``AuthBaseClient``.
+    Users should not instantiate this class directly, but it provides
+    common functionality for all clients to Globus Auth.
+
+Deprecated
+~~~~~~~~~~
+
+- Several features of Auth client classes are now deprecated. (:pr:`NUMBER`)
+
+  - Setting ``AuthServiceClient.client_id`` or accessing it as an attribute
+    is deprecated and will emit a warning. ``AuthClient`` is now an alias for
+    ``AuthServiceClient``, so this applies to both names.
+
+  - ``ConfidentialAppAuthClient.get_identities`` has been preserved as a valid
+    call, but will emit a warning. Users wishing to access this API via client
+    credentials should prefer to get an access token using a client credential
+    callout, and then use that token to call ``get_identities`` using an
+    ``AuthServiceClient``.

docs/services/auth.rst

@@ -9,11 +9,13 @@ authentication and authorization flows), in which case the
 :class:`NativeAppAuthClient` or :class:`ConfidentialAppAuthClient` classes should
 generally be used.
 
-.. autoclass:: AuthClient
+Client Classes
+--------------
+
+.. autoclass:: AuthServiceClient
    :members:
    :member-order: bysource
    :show-inheritance:
-   :exclude-members: error_class
 
 .. autoclass:: NativeAppAuthClient
    :members:
@@ -27,6 +29,24 @@ generally be used.
    :show-inheritance:
    :exclude-members: error_class
 
+Client Bases
+~~~~~~~~~~~~
+
+The common base class for all Auth Client classes is the ``AuthBaseClient``.
+
+.. autoclass:: AuthBaseClient
+   :members:
+   :member-order: bysource
+   :show-inheritance:
+   :exclude-members: error_class
+
+Clients providing login flow capabilities inherit from ``AuthLoginClient``.
+
+.. autoclass:: AuthLoginClient
+   :members:
+   :member-order: bysource
+   :show-inheritance:
+
 Helper Objects
 --------------
 

src/globus_sdk/__init__.py

@@ -52,11 +52,14 @@ def _force_eager_imports() -> None:
         "ArrayResponse",
     },
     "services.auth": {
-        "AuthAPIError",
+        "AuthBaseClient",
         "AuthClient",
+        "AuthServiceClient",
+        "AuthLoginClient",
+        "NativeAppAuthClient",
         "ConfidentialAppAuthClient",
+        "AuthAPIError",
         "IdentityMap",
-        "NativeAppAuthClient",
         "GetIdentitiesResponse",
         "OAuthDependentTokenResponse",
         "OAuthTokenResponse",
@@ -149,11 +152,14 @@ def _force_eager_imports() -> None:
     from .response import GlobusHTTPResponse
     from .response import IterableResponse
     from .response import ArrayResponse
-    from .services.auth import AuthAPIError
+    from .services.auth import AuthBaseClient
     from .services.auth import AuthClient
+    from .services.auth import AuthServiceClient
+    from .services.auth import AuthLoginClient
+    from .services.auth import NativeAppAuthClient
     from .services.auth import ConfidentialAppAuthClient
+    from .services.auth import AuthAPIError
     from .services.auth import IdentityMap
-    from .services.auth import NativeAppAuthClient
     from .services.auth import GetIdentitiesResponse
     from .services.auth import OAuthDependentTokenResponse
     from .services.auth import OAuthTokenResponse
@@ -246,7 +252,10 @@ def __getattr__(name: str) -> t.Any:
     "ActiveScaleStoragePolicies",
     "ArrayResponse",
     "AuthAPIError",
+    "AuthBaseClient",
     "AuthClient",
+    "AuthLoginClient",
+    "AuthServiceClient",
     "AzureBlobStoragePolicies",
     "BaseClient",
     "BasicAuthorizer",

src/globus_sdk/_generate_init.py

@@ -110,11 +110,18 @@ def __getattr__(name: str) -> t.Any:
     (
         "services.auth",
         (
-            "AuthAPIError",
+            # client classes
+            "AuthBaseClient",
             "AuthClient",
+            "AuthServiceClient",
+            "AuthLoginClient",
+            "NativeAppAuthClient",
             "ConfidentialAppAuthClient",
+            # errors
+            "AuthAPIError",
+            # high-level helpers
             "IdentityMap",
-            "NativeAppAuthClient",
+            # responses
             "GetIdentitiesResponse",
             "OAuthDependentTokenResponse",
             "OAuthTokenResponse",

src/globus_sdk/services/auth/__init__.py

@@ -1,4 +1,11 @@
-from .client import AuthClient, ConfidentialAppAuthClient, NativeAppAuthClient
+from .client import (
+    AuthBaseClient,
+    AuthClient,
+    AuthLoginClient,
+    AuthServiceClient,
+    ConfidentialAppAuthClient,
+    NativeAppAuthClient,
+)
 from .errors import AuthAPIError
 from .flow_managers import (
     GlobusAuthorizationCodeFlowManager,
@@ -11,15 +18,24 @@
     OAuthTokenResponse,
 )
 
-__all__ = [
+__all__ = (
+    # client classes
+    "AuthBaseClient",
     "AuthClient",
-    "AuthAPIError",
+    "AuthServiceClient",
+    "AuthLoginClient",
     "NativeAppAuthClient",
     "ConfidentialAppAuthClient",
+    "AuthClient",
+    # errors
+    "AuthAPIError",
+    # high-level helpers
     "IdentityMap",
+    # flow managers
     "GlobusNativeAppFlowManager",
     "GlobusAuthorizationCodeFlowManager",
+    # responses
     "GetIdentitiesResponse",
     "OAuthDependentTokenResponse",
     "OAuthTokenResponse",
-]
+)

src/globus_sdk/services/auth/client/__init__.py

@@ -1,5 +1,14 @@
-from .base import AuthClient
+from .base import AuthBaseClient
+from .base_login_client import AuthLoginClient
 from .confidential_client import ConfidentialAppAuthClient
 from .native_client import NativeAppAuthClient
+from .service_client import AuthClient, AuthServiceClient
 
-__all__ = ["AuthClient", "NativeAppAuthClient", "ConfidentialAppAuthClient"]
+__all__ = (
+    "AuthBaseClient",
+    "AuthClient",
+    "AuthServiceClient",
+    "AuthLoginClient",
+    "NativeAppAuthClient",
+    "ConfidentialAppAuthClient",
+)