fix: replace deprecated utcfromtimestamp (#1799)

addresses #1781 

* Moves away from using `utcfromtimestamp()` in the `datetime` library
due to deprecation.
* Adds a new helper function to manage internal handling of timezone
aware versus timezone naive timestamps.

```
DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC).
```

---------

Co-authored-by: Kevin Zheng <147537668+gkevinzheng@users.noreply.github.com>
Co-authored-by: Chalmer Lowe <chalmerlowe@google.com>

Author: 3 people

packages/google-auth/google/auth/_helpers.py

@@ -124,6 +124,26 @@ def utcnow():
     return now
 
 
+def utcfromtimestamp(timestamp):
+    """Returns the UTC datetime from a timestamp.
+
+    Args:
+        timestamp (float): The timestamp to convert.
+
+    Returns:
+        datetime: The time in UTC.
+    """
+    # We used datetime.utcfromtimestamp() before, since it's deprecated from
+    # python 3.12, we are using datetime.fromtimestamp(timestamp, timezone.utc)
+    # now. "utcfromtimestamp()" is offset-native (no timezone info), but
+    # "fromtimestamp(timestamp, timezone.utc)" is offset-aware (with timezone
+    # info). This will cause datetime comparison problem. For backward
+    # compatibility, we need to remove the timezone info.
+    dt = datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)
+    dt = dt.replace(tzinfo=None)
+    return dt
+
+
 def datetime_to_secs(value):
     """Convert a datetime object to the number of seconds since the UNIX epoch.
 

packages/google-auth/google/auth/app_engine.py

@@ -22,7 +22,6 @@
     https://cloud.google.com/appengine/docs/python/appidentity/
 """
 
-import datetime
 
 from google.auth import _helpers
 from google.auth import credentials
@@ -128,7 +127,7 @@ def refresh(self, request):
         scopes = self._scopes if self._scopes is not None else self._default_scopes
         # pylint: disable=unused-argument
         token, ttl = app_identity.get_access_token(scopes, self._service_account_id)
-        expiry = datetime.datetime.utcfromtimestamp(ttl)
+        expiry = _helpers.utcfromtimestamp(ttl)
 
         self.token, self.expiry = token, expiry
 

packages/google-auth/google/auth/compute_engine/credentials.py

@@ -498,7 +498,7 @@ def _call_metadata_identity_endpoint(self, request):
             raise new_exc from caught_exc
 
         _, payload, _, _ = jwt._unverified_decode(id_token)
-        return id_token, datetime.datetime.utcfromtimestamp(payload["exp"])
+        return id_token, _helpers.utcfromtimestamp(payload["exp"])
 
     def refresh(self, request):
         """Refreshes the ID token.

packages/google-auth/google/auth/impersonated_credentials.py

@@ -649,7 +649,7 @@ def refresh(self, request):
             raise new_exc from caught_exc
 
         self.token = id_token
-        self.expiry = datetime.utcfromtimestamp(
+        self.expiry = _helpers.utcfromtimestamp(
             jwt.decode(id_token, verify=False)["exp"]
         )
 

packages/google-auth/google/oauth2/_client.py

@@ -368,7 +368,7 @@ def call_iam_generate_id_token_endpoint(
         raise new_exc from caught_exc
 
     payload = jwt.decode(id_token, verify=False)
-    expiry = datetime.datetime.utcfromtimestamp(payload["exp"])
+    expiry = _helpers.utcfromtimestamp(payload["exp"])
 
     return id_token, expiry
 
@@ -420,7 +420,7 @@ def id_token_jwt_grant(request, token_uri, assertion, can_retry=True):
         raise new_exc from caught_exc
 
     payload = jwt.decode(id_token, verify=False)
-    expiry = datetime.datetime.utcfromtimestamp(payload["exp"])
+    expiry = _helpers.utcfromtimestamp(payload["exp"])
 
     return id_token, expiry, response_data
 

packages/google-auth/google/oauth2/_client_async.py

@@ -23,12 +23,12 @@
 .. _Section 3.1 of rfc6749: https://tools.ietf.org/html/rfc6749#section-3.2
 """
 
-import datetime
 import http.client as http_client
 import json
 import urllib
 
 from google.auth import _exponential_backoff
+from google.auth import _helpers
 from google.auth import exceptions
 from google.auth import jwt
 from google.oauth2 import _client as client
@@ -227,7 +227,7 @@ async def id_token_jwt_grant(request, token_uri, assertion, can_retry=True):
         raise new_exc from caught_exc
 
     payload = jwt.decode(id_token, verify=False)
-    expiry = datetime.datetime.utcfromtimestamp(payload["exp"])
+    expiry = _helpers.utcfromtimestamp(payload["exp"])
 
     return id_token, expiry, response_data
 

packages/google-auth/tests/compute_engine/test_credentials.py

@@ -758,7 +758,7 @@ def test_default_state(self, get):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -791,7 +791,7 @@ def test_make_authorization_grant_assertion(self, sign, get, utcnow):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -823,7 +823,7 @@ def test_with_service_account(self, sign, get, utcnow):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -879,7 +879,7 @@ def test_token_uri(self):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -1001,7 +1001,7 @@ def test_with_target_audience_integration(self):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -1040,7 +1040,7 @@ def test_with_quota_project(self, sign, get, utcnow):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -1062,7 +1062,7 @@ def test_with_token_uri(self, sign, get, utcnow):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -1170,7 +1170,7 @@ def test_with_quota_project_integration(self):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -1181,7 +1181,11 @@ def test_refresh_success(self, id_token_jwt_grant, sign, get, utcnow):
         ]
         sign.side_effect = [b"signature"]
         id_token_jwt_grant.side_effect = [
-            ("idtoken", datetime.datetime.utcfromtimestamp(3600), {})
+            (
+                "idtoken",
+                _helpers.utcfromtimestamp(3600),
+                {},
+            )
         ]
 
         request = mock.create_autospec(transport.Request, instance=True)
@@ -1194,7 +1198,7 @@ def test_refresh_success(self, id_token_jwt_grant, sign, get, utcnow):
 
         # Check that the credentials have the token and proper expiration
         assert self.credentials.token == "idtoken"
-        assert self.credentials.expiry == (datetime.datetime.utcfromtimestamp(3600))
+        assert self.credentials.expiry == _helpers.utcfromtimestamp(3600)
 
         # Check the credential info
         assert self.credentials.service_account_email == "service-account@example.com"
@@ -1205,7 +1209,7 @@ def test_refresh_success(self, id_token_jwt_grant, sign, get, utcnow):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -1232,7 +1236,7 @@ def test_refresh_error(self, sign, get, utcnow):
 
     @mock.patch(
         "google.auth._helpers.utcnow",
-        return_value=datetime.datetime.utcfromtimestamp(0),
+        return_value=_helpers.utcfromtimestamp(0),
     )
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     @mock.patch("google.auth.iam.Signer.sign", autospec=True)
@@ -1243,7 +1247,11 @@ def test_before_request_refreshes(self, id_token_jwt_grant, sign, get, utcnow):
         ]
         sign.side_effect = [b"signature"]
         id_token_jwt_grant.side_effect = [
-            ("idtoken", datetime.datetime.utcfromtimestamp(3600), {})
+            (
+                "idtoken",
+                _helpers.utcfromtimestamp(3600),
+                {},
+            )
         ]
 
         request = mock.create_autospec(transport.Request, instance=True)
@@ -1312,7 +1320,7 @@ def test_get_id_token_from_metadata(
         }
 
         assert cred.token == SAMPLE_ID_TOKEN
-        assert cred.expiry == datetime.datetime.utcfromtimestamp(SAMPLE_ID_TOKEN_EXP)
+        assert cred.expiry == _helpers.utcfromtimestamp(SAMPLE_ID_TOKEN_EXP)
         assert cred._use_metadata_identity_endpoint
         assert cred._signer is None
         assert cred._token_uri is None

packages/google-auth/tests/test__helpers.py

@@ -677,3 +677,50 @@ def test_parse_response_no_json_method():
 
 def test_parse_response_none():
     assert _helpers._parse_response(None) is None
+
+
+class TestUtcFromTimestamp:
+    """Tests for the utcfromtimestamp utility function."""
+
+    @pytest.mark.parametrize(
+        "ts, expected",
+        [
+            (1704067200.0, datetime.datetime(2024, 1, 1, 0, 0, 0)),
+            (0.0, datetime.datetime(1970, 1, 1, 0, 0, 0)),
+            (1704067200.500123, datetime.datetime(2024, 1, 1, 0, 0, 0, 500123)),
+            (-31536000.0, datetime.datetime(1969, 1, 1, 0, 0, 0)),
+            (1000000000.0, datetime.datetime(2001, 9, 9, 1, 46, 40)),
+        ],
+        ids=[
+            "standard_timestamp",
+            "unix_epoch",
+            "subsecond_precision",
+            "negative_timestamp",
+            "timezone_independence",
+        ],
+    )
+    def test_success_cases(self, ts, expected):
+        """Verify correct UTC conversion and that the result is offset-naive."""
+        result = _helpers.utcfromtimestamp(ts)
+
+        # 1. Check the datetime value is correct
+        assert result == expected
+
+        # 2. Check it is naive (tzinfo is None) for backward compatibility
+        assert result.tzinfo is None
+
+    @pytest.mark.parametrize(
+        "invalid_input",
+        ["string", None, [123]],
+        ids=["type_string", "type_none", "type_list"],
+    )
+    def test_invalid_types(self, invalid_input):
+        """Verify that passing invalid types raises a TypeError."""
+        with pytest.raises(TypeError):
+            _helpers.utcfromtimestamp(invalid_input)
+
+    def test_out_of_range(self):
+        """Test very large timestamps that exceed platform limits."""
+        with pytest.raises((OverflowError, OSError, ValueError)):
+            # Large enough to fail on most systems (Year 300,000+)
+            _helpers.utcfromtimestamp(9999999999999)

packages/google-auth/tests/test_impersonated_credentials.py

@@ -1047,7 +1047,8 @@ def test_id_token_success(
         id_creds.refresh(request)
 
         assert id_creds.token == ID_TOKEN_DATA
-        assert id_creds.expiry == datetime.datetime.utcfromtimestamp(ID_TOKEN_EXPIRY)
+        expected_expiry = _helpers.utcfromtimestamp(ID_TOKEN_EXPIRY)
+        assert id_creds.expiry == expected_expiry
 
     def test_id_token_metrics(self, mock_donor_credentials):
         credentials = self.make_credentials(lifetime=None)
@@ -1071,9 +1072,8 @@ def test_id_token_metrics(self, mock_donor_credentials):
                 id_creds.refresh(None)
 
                 assert id_creds.token == ID_TOKEN_DATA
-                assert id_creds.expiry == datetime.datetime.utcfromtimestamp(
-                    ID_TOKEN_EXPIRY
-                )
+                expected_expiry = _helpers.utcfromtimestamp(ID_TOKEN_EXPIRY)
+                assert id_creds.expiry == expected_expiry
                 assert (
                     mock_post.call_args.kwargs["headers"]["x-goog-api-client"]
                     == ID_TOKEN_REQUEST_METRICS_HEADER_VALUE
@@ -1181,7 +1181,8 @@ def test_id_token_with_target_audience(
         id_creds.refresh(request)
 
         assert id_creds.token == ID_TOKEN_DATA
-        assert id_creds.expiry == datetime.datetime.utcfromtimestamp(ID_TOKEN_EXPIRY)
+        expected_expiry = _helpers.utcfromtimestamp(ID_TOKEN_EXPIRY)
+        assert id_creds.expiry == expected_expiry
         assert id_creds._include_email is True
 
     def test_id_token_invalid_cred(