feat: implement base classes for credentials and request sessions

google/auth/_credentials_base.py

@@ -0,0 +1,73 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Interface for base credentials."""
+
+import abc
+
+from google.auth import _helpers
+
+
+class _BaseCredentials(metaclass=abc.ABCMeta):
+    """Base class for all credentials.
+
+    All credentials have a :attr:`token` that is used for authentication and
+    may also optionally set an :attr:`expiry` to indicate when the token will
+    no longer be valid.
+
+    Most credentials will be :attr:`invalid` until :meth:`refresh` is called.
+    Credentials can do this automatically before the first HTTP request in
+    :meth:`before_request`.
+
+    Although the token and expiration will change as the credentials are
+    :meth:`refreshed <refresh>` and used, credentials should be considered
+    immutable. Various credentials will accept configuration such as private
+    keys, scopes, and other options. These options are not changeable after
+    construction. Some classes will provide mechanisms to copy the credentials
+    with modifications such as :meth:`ScopedCredentials.with_scopes`.
+    """
+
+    def __init__(self):
+        self.token = None
+        """str: The bearer token that can be used in HTTP headers to make
+        authenticated requests."""
+
+    @abc.abstractmethod
+    def refresh(self, request):
+        """Refreshes the access token.
+
+        Args:
+            request (google.auth.transport.Request): The object used to make
+                HTTP requests.
+
+        Raises:
+            google.auth.exceptions.RefreshError: If the credentials could
+                not be refreshed.
+        """
+        # pylint: disable=missing-raises-doc
+        # (pylint doesn't recognize that this is abstract)
+        raise NotImplementedError("Refresh must be implemented")
+
+    def _apply(self, headers, token=None):
+        """Apply the token to the authentication header.
+
+        Args:
+            headers (Mapping): The HTTP request headers.
+            token (Optional[str]): If specified, overrides the current access
+                token.
+        """
+        headers["authorization"] = "Bearer {}".format(
+            _helpers.from_bytes(token or self.token)
+        )

google/auth/credentials.py

@@ -1,4 +1,4 @@
-# Copyright 2016 Google LLC
+# Copyright 2024 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -23,11 +23,12 @@
 from google.auth import exceptions
 from google.auth import metrics
 from google.auth._refresh_worker import RefreshThreadManager
+from google.auth._credentials_base import _BaseCredentials
 
 DEFAULT_UNIVERSE_DOMAIN = "googleapis.com"
 
 
-class Credentials(metaclass=abc.ABCMeta):
+class Credentials(_BaseCredentials):
     """Base class for all credentials.
 
     All credentials have a :attr:`token` that is used for authentication and
@@ -47,9 +48,8 @@ class Credentials(metaclass=abc.ABCMeta):
     """
 
     def __init__(self):
-        self.token = None
-        """str: The bearer token that can be used in HTTP headers to make
-        authenticated requests."""
+        super(Credentials, self).__init__()
+
         self.expiry = None
         """Optional[datetime]: When the token expires and is no longer valid.
         If this is None, the token is assumed to never expire."""
@@ -167,9 +167,7 @@ def apply(self, headers, token=None):
             token (Optional[str]): If specified, overrides the current access
                 token.
         """
-        headers["authorization"] = "Bearer {}".format(
-            _helpers.from_bytes(token or self.token)
-        )
+        self._apply(headers, token=token)
         """Trust boundary value will be a cached value from global lookup.
 
         The response of trust boundary will be a list of regions and a hex

google/auth/transport/_requests_base.py

@@ -0,0 +1,52 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Transport adapter for Base Requests."""
+
+
+import abc
+
+
+_DEFAULT_TIMEOUT = 120  # in second
+
+
+class _BaseAuthorizedSession(metaclass=abc.ABCMeta):
+    """Base class for a Request Session with credentials. This class is intended to capture
+    the common logic between synchronous and asynchronous request sessions and is not intended to
+    be instantiated directly.
+
+    Args:
+        credentials (google.auth._credentials_base.BaseCredentials): The credentials to
+            add to the request.
+    """
+
+    def __init__(self, credentials):
+        self.credentials = credentials
+
+    @abc.abstractmethod
+    def request(
+        self,
+        method,
+        url,
+        data=None,
+        headers=None,
+        max_allowed_time=None,
+        timeout=_DEFAULT_TIMEOUT,
+        **kwargs
+    ):
+        raise NotImplementedError("Request must be implemented")
+
+    @abc.abstractmethod
+    def close(self):
+        raise NotImplementedError("Close must be implemented")

google/auth/transport/requests.py

@@ -1,4 +1,4 @@
-# Copyright 2016 Google LLC
+# Copyright 2024 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -37,6 +37,7 @@
 from google.auth import environment_vars
 from google.auth import exceptions
 from google.auth import transport
+from google.auth.transport._requests_base import _BaseAuthorizedSession
 import google.auth.transport._mtls_helper
 from google.oauth2 import service_account
 
@@ -292,7 +293,7 @@ def proxy_manager_for(self, *args, **kwargs):
         return super(_MutualTlsOffloadAdapter, self).proxy_manager_for(*args, **kwargs)
 
 
-class AuthorizedSession(requests.Session):
+class AuthorizedSession(requests.Session, _BaseAuthorizedSession):
     """A Requests Session class with credentials.
 
     This class is used to perform requests to API endpoints that require
@@ -389,7 +390,7 @@ def __init__(
         default_host=None,
     ):
         super(AuthorizedSession, self).__init__()
-        self.credentials = credentials
+        _BaseAuthorizedSession.__init__(self, credentials)
         self._refresh_status_codes = refresh_status_codes
         self._max_refresh_attempts = max_refresh_attempts
         self._refresh_timeout = refresh_timeout