Add BaseAuthClient to separate methods

Introduce a new base class for the Auth client hierarchy in order to
split the developer API methods from the previously existing "base"
methods. The important exception is `get_identities`, which supports
client credentials authorization and therefore needs to stay on the
base.

The changelog explains this change without drawing undue attention to
the ways in which it could, in theory, be compatibility breaking for
users relying on the inheritance relationship (e.g. via `isinstance`
or type annotations).

No new tests are added and no tests are broken by this change.

changelog.d/20230718_140424_sirosen_separate_auth_base.rst

@@ -0,0 +1,14 @@
+Changed
+~~~~~~~
+
+- The inheritance hierarchy for Globus Auth client classes has changed. (:pr:`NUMBER`)
+
+  - A new class, ``BaseAuthClient`` is used as the base for the other three
+    existing Globus Auth clients
+
+  - ``NativeAppAuthClient`` and ``ConfidentialAppAuthClient`` inherit from
+    ``BaseAuthClient``, not ``AuthClient``
+
+  - ``NativeAppAuthClient`` and ``ConfidentialAppAuthClient`` have lost methods
+    which would never work in practice for these client types, e.g.
+    ``create_project``

docs/services/auth.rst

@@ -4,10 +4,23 @@ Globus Auth
 .. currentmodule:: globus_sdk
 
 There are several types of client object for communicating with the Globus Auth
-service. A client object may represent your application (as the driver of
-authentication and authorization flows), in which case the
-:class:`NativeAppAuthClient` or :class:`ConfidentialAppAuthClient` classes should
-generally be used.
+service.
+
+A client object may represent an application (as the driver of authentication and
+authorization flows), in which case the :class:`NativeAppAuthClient` or
+:class:`ConfidentialAppAuthClient` classes should generally be used.
+
+For authentication using token auth, generally the appropriate choice is
+:class:`AuthClient`.
+
+:class:`BaseAuthClient` defines shared interfaces for the other three but is
+generally not recommended for direct instantiation.
+
+.. autoclass:: BaseAuthClient
+   :members:
+   :member-order: bysource
+   :show-inheritance:
+   :exclude-members: error_class
 
 .. autoclass:: AuthClient
    :members:

src/globus_sdk/__init__.py

@@ -53,6 +53,7 @@ def _force_eager_imports() -> None:
     },
     "services.auth": {
         "AuthAPIError",
+        "BaseAuthClient",
         "AuthClient",
         "ConfidentialAppAuthClient",
         "IdentityMap",
@@ -150,6 +151,7 @@ def _force_eager_imports() -> None:
     from .response import IterableResponse
     from .response import ArrayResponse
     from .services.auth import AuthAPIError
+    from .services.auth import BaseAuthClient
     from .services.auth import AuthClient
     from .services.auth import ConfidentialAppAuthClient
     from .services.auth import IdentityMap
@@ -248,6 +250,7 @@ def __getattr__(name: str) -> t.Any:
     "AuthAPIError",
     "AuthClient",
     "AzureBlobStoragePolicies",
+    "BaseAuthClient",
     "BaseClient",
     "BasicAuthorizer",
     "BatchMembershipActions",

src/globus_sdk/_generate_init.py

@@ -111,6 +111,7 @@ def __getattr__(name: str) -> t.Any:
         "services.auth",
         (
             "AuthAPIError",
+            "BaseAuthClient",
             "AuthClient",
             "ConfidentialAppAuthClient",
             "IdentityMap",

src/globus_sdk/services/auth/__init__.py

@@ -1,4 +1,9 @@
-from .client import AuthClient, ConfidentialAppAuthClient, NativeAppAuthClient
+from .client import (
+    AuthClient,
+    BaseAuthClient,
+    ConfidentialAppAuthClient,
+    NativeAppAuthClient,
+)
 from .errors import AuthAPIError
 from .flow_managers import (
     GlobusAuthorizationCodeFlowManager,
@@ -12,6 +17,7 @@
 )
 
 __all__ = [
+    "BaseAuthClient",
     "AuthClient",
     "AuthAPIError",
     "NativeAppAuthClient",

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

@@ -1,5 +1,10 @@
-from .base import AuthClient
+from .base import AuthClient, BaseAuthClient
 from .confidential_client import ConfidentialAppAuthClient
 from .native_client import NativeAppAuthClient
 
-__all__ = ["AuthClient", "NativeAppAuthClient", "ConfidentialAppAuthClient"]
+__all__ = [
+    "BaseAuthClient",
+    "AuthClient",
+    "NativeAppAuthClient",
+    "ConfidentialAppAuthClient",
+]