Add with_scopes_if_required helper

google/auth/credentials.py

@@ -186,6 +186,30 @@ def has_scopes(self, scopes):
         return set(scopes).issubset(set(self._scopes or []))
 
 
+def with_scopes_if_required(credentials, scopes):
+    """Creates a copy of the credentials with scopes if scoping is required.
+
+    This helper function is useful when you do not know (or care to know) the
+    specific type of credentials you are using (such as when you use
+    :func:`google.auth.default`). This function will call
+    :meth:`Scoped.with_scopes` if the credentials are scoped credentials and if
+    the credentials require scoping. Otherwise, it will return the credentials
+    as-is.
+
+    Args:
+        credentials (Credentials): The credentials to scope if necessary.
+        scopes (Sequence[str]): The list of scopes to use.
+
+    Returns:
+        Credentials: Either a new set of scoped credentials, or the passed in
+            credentials instance if no scoping was required.
+    """
+    if isinstance(credentials, Scoped) and credentials.requires_scopes:
+        return credentials.with_scopes(scopes)
+    else:
+        return credentials
+
+
 @six.add_metaclass(abc.ABCMeta)
 class Signing(object):
     """Interface for credentials that can cryptographically sign messages."""

tests/test_credentials.py

@@ -92,3 +92,34 @@ def test_scoped_credentials_scopes():
 def test_scoped_credentials_requires_scopes():
     credentials = ScopedCredentialsImpl()
     assert not credentials.requires_scopes
+
+
+class RequiresScopedCredentialsImpl(credentials.Scoped, CredentialsImpl):
+    def __init__(self, scopes=None):
+        super(RequiresScopedCredentialsImpl, self).__init__()
+        self._scopes = scopes
+
+    @property
+    def requires_scopes(self):
+        return not self.scopes
+
+    def with_scopes(self, scopes):
+        return RequiresScopedCredentialsImpl(scopes=scopes)
+
+
+def test_create_scoped_if_required_scoped():
+    unscoped_credentials = RequiresScopedCredentialsImpl()
+    scoped_credentials = credentials.with_scopes_if_required(
+        unscoped_credentials, ['one', 'two'])
+
+    assert scoped_credentials is not unscoped_credentials
+    assert not scoped_credentials.requires_scopes
+    assert scoped_credentials.has_scopes(['one', 'two'])
+
+
+def test_create_scoped_if_required_not_scopes():
+    unscoped_credentials = CredentialsImpl()
+    scoped_credentials = credentials.with_scopes_if_required(
+        unscoped_credentials, ['one', 'two'])
+
+    assert scoped_credentials is unscoped_credentials