Add support for datetime destinations with tzinfo=datetime.UTC (#502)

lawrence-law · web-flow · commit f48ff0a7c7fa · 2025-08-13T11:38:52.000+01:00
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -11,6 +11,10 @@ Unreleased
 
   Thanks to Javier Buzzi in `PR #531 <https://github.com/adamchainz/time-machine/pull/531>`__.
 
+* Add support to ``travel()`` for ``datetime`` destinations with ``tzinfo`` set to ``datetime.UTC`` (``datetime.timezone.utc``).
+
+  Thanks to Lawrence Law in `PR #502 <https://github.com/adamchainz/time-machine/pull/502>`__.
+
 * Prevent segmentation faults in unlikely scenarios, such as if the ``time_machine`` module cannot be imported.
 
 2.17.0 (2025-08-05)
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -28,7 +28,7 @@ It may be:
 
 * A ``datetime.datetime``.
   If it is naive, it will be assumed to have the UTC timezone.
-  If it has ``tzinfo`` set to a |zoneinfo-instance|_, the current timezone will also be mocked.
+  If it has ``tzinfo`` set to a |zoneinfo-instance|_ or |datetime.UTC|_, the current timezone will also be mocked.
 * A ``datetime.date``.
   This will be converted to a UTC datetime with the time 00:00:00.
 * A ``datetime.timedelta``.
@@ -40,6 +40,8 @@ It may be:
 
 .. |zoneinfo-instance| replace:: ``zoneinfo.ZoneInfo`` instance
 .. _zoneinfo-instance: https://docs.python.org/3/library/zoneinfo.html#zoneinfo.ZoneInfo
+.. |datetime.UTC| replace:: ``datetime.UTC`` (``datetime.timezone.utc``)
+.. _datetime.UTC: https://docs.python.org/3/library/datetime.html#datetime.UTC
 
 Additionally, you can provide some more complex types:
 
diff --git a/src/time_machine/__init__.py b/src/time_machine/__init__.py
@@ -102,7 +102,9 @@ def extract_timestamp_tzname(
     elif isinstance(dest, dt.datetime):
         if isinstance(dest.tzinfo, ZoneInfo):
             tzname = dest.tzinfo.key
-        if dest.tzinfo is None:
+        elif dest.tzinfo == dt.timezone.utc:
+            tzname = "UTC"
+        elif dest.tzinfo is None:
             dest = dest.replace(tzinfo=dt.timezone.utc)
         timestamp = dest.timestamp()
     elif isinstance(dest, dt.timedelta):
diff --git a/tests/test_time_machine.py b/tests/test_time_machine.py
@@ -434,6 +434,42 @@ def test_destination_datetime_tzinfo_zoneinfo_no_orig_tz():
         assert time.tzname == orig_tzname
 
 
+def test_destination_datetime_tzinfo_zoneinfo_utc_no_orig_tz():
+    with change_local_timezone(None):
+        orig_tzname = time.tzname
+        dest = LIBRARY_EPOCH_DATETIME.replace(tzinfo=ZoneInfo("UTC"))
+
+        with time_machine.travel(dest):
+            assert time.tzname == ("UTC", "UTC")
+
+        assert time.tzname == orig_tzname
+
+
+def test_destination_datetime_tzinfo_datetime_timezone_utc_no_orig_tz():
+    with change_local_timezone(None):
+        orig_tzname = time.tzname
+        dest = LIBRARY_EPOCH_DATETIME.replace(tzinfo=dt.timezone.utc)
+
+        with time_machine.travel(dest):
+            assert time.tzname == ("UTC", "UTC")
+
+        assert time.tzname == orig_tzname
+
+
+@pytest.mark.skipif(
+    sys.version_info < (3, 11), reason="datetime.UTC was introduced in Python 3.11"
+)
+def test_destination_datetime_tzinfo_datetime_utc_no_orig_tz():
+    with change_local_timezone(None):
+        orig_tzname = time.tzname
+        dest = LIBRARY_EPOCH_DATETIME.replace(tzinfo=dt.UTC)
+
+        with time_machine.travel(dest):
+            assert time.tzname == ("UTC", "UTC")
+
+        assert time.tzname == orig_tzname
+
+
 def test_destination_datetime_tzinfo_zoneinfo_windows():
     orig_timezone = time.timezone
 
