Normalize Cloud <schedule nextRunAt=...> to UTC on parse

Previously parse_datetime returned Cloud datetimes with the wire's offset
attached (e.g. tzinfo == timezone(-7:00)), so the same field had different
tzinfo depending on cell type. Callers using .strftime("...Z") got wrong
output on Cloud; callers comparing to a UTC constant with == got False even
on the same instant.

Convert the Cloud branch's strptime result via .astimezone(utc), so every
next_run_at returned from TSC is uniformly tzinfo == utc regardless of
whether the wire used trailing Z or an explicit numeric offset. Callers
who want the site's local zone can inspect the wire elsewhere (schedule
name, admin API); nobody was relying on the offset today.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jacalata

tableauserverclient/datetime_helpers.py

@@ -35,11 +35,16 @@ def dst(self, dt):
 def parse_datetime(date):
     """Parse a Tableau API datetime string into a timezone-aware datetime, or ``None``.
 
-    Handles both the Server ``...Z`` form and the Cloud ``...+/-HHMM`` form. Returns
-    ``None`` for both absent input (``None``) and unparseable non-empty input --
-    matching the pre-Cloud lenient contract so a malformed server response cannot
-    crash a page-through of unrelated data. User-supplied setter values are
-    validated at the property-decorator boundary (see
+    Accepts both the Server ``...Z`` form and the Cloud ``...+/-HHMM`` form on
+    the wire. The returned ``datetime`` is **always tz-aware and always UTC**
+    (``tzinfo == utc``) regardless of which wire form was parsed -- the Cloud
+    branch converts the wire's numeric offset to UTC via ``astimezone`` so
+    callers see a single uniform tzinfo across Server and Cloud responses.
+
+    Returns ``None`` for both absent input (``None``) and unparseable non-empty
+    input -- matching the pre-Cloud lenient contract so a malformed server
+    response cannot crash a page-through of unrelated data. User-supplied
+    setter values are validated at the property-decorator boundary (see
     :func:`tableauserverclient.models.property_decorators.property_is_datetime`).
     """
     if date is None:
@@ -49,7 +54,9 @@ def parse_datetime(date):
     except ValueError:
         pass
     try:
-        return datetime.datetime.strptime(date, TABLEAU_CLOUD_DATE_FORMAT)
+        # strptime %z produces a datetime with the wire's offset; convert to UTC so
+        # callers get a single uniform tzinfo across Server (already UTC) and Cloud.
+        return datetime.datetime.strptime(date, TABLEAU_CLOUD_DATE_FORMAT).astimezone(utc)
     except ValueError:
         return None
 

tableauserverclient/models/property_decorators.py

@@ -128,9 +128,10 @@ def property_is_datetime(func):
     * explicit ``%z`` offset, e.g. ``2026-09-01T10:00:00-0700`` (produced by
       Tableau Cloud's inlined ``<schedule nextRunAt=...>``)
 
-    The returned ``datetime`` preserves the offset that was on the wire; it is
-    always offset-aware but is only guaranteed to be UTC when the input used
-    the trailing-``Z`` form.
+    Regardless of which wire form was accepted, the resulting ``datetime`` is
+    always tz-aware with ``tzinfo == utc`` -- the Cloud branch converts the
+    wire's numeric offset to UTC on parse so downstream callers see one
+    uniform tzinfo across Server and Cloud responses.
 
     Setter-side strictness lives here: ``parse_datetime`` is deliberately
     lenient on the server-response side (unparseable -> ``None``). This

test/test_datetime_helpers.py

@@ -9,8 +9,9 @@
 
 * Absent input (``None``) -> ``None``.
 * Well-formed Server form -> UTC-aware ``datetime``.
-* Well-formed Cloud form -> aware ``datetime`` with the on-the-wire offset
-  preserved (**not** normalised to UTC).
+* Well-formed Cloud form -> UTC-aware ``datetime``; the wire's numeric offset
+  is converted to UTC on parse so every returned ``datetime`` carries the same
+  ``tzinfo`` regardless of which wire form arrived.
 * Unparseable non-empty input -> ``None``. A malformed server response should
   not crash a page-through of unrelated data. This matches the pre-Cloud
   behaviour.
@@ -60,14 +61,21 @@ def test_parse_datetime_server_z_form():
     assert timedelta(0) == result.utcoffset()
 
 
-def test_parse_datetime_cloud_offset_form_preserved():
+def test_parse_datetime_cloud_offset_form_normalised_to_utc():
     result = parse_datetime("2026-08-29T16:55:00-0700")
     assert result is not None
-    # Cloud offsets are deliberately kept -- a future .replace(tzinfo=utc)
-    # after strptime would silently shift the instant. Lock that in.
-    assert timedelta(hours=-7) == result.utcoffset()
+    # The Cloud branch normalises to UTC via astimezone(utc) so every parsed
+    # datetime carries the same tzinfo regardless of wire form. A future
+    # regression that drops the astimezone would leave tzinfo == timezone(-7:00)
+    # and break callers doing .strftime("...Z") or == against a UTC constant.
+    assert timedelta(0) == result.utcoffset()
+    assert result.tzinfo is utc
+    # 16:55 -07:00 == 23:55 UTC on the same wall date.
     assert 2026 == result.year
-    assert 16 == result.hour
+    assert 8 == result.month
+    assert 29 == result.day
+    assert 23 == result.hour
+    assert 55 == result.minute
 
 
 def test_parse_datetime_cloud_offset_with_colon():
@@ -129,7 +137,10 @@ def test_property_is_datetime_accepts_valid_cloud_string():
     holder = _DateHolder()
     holder.created_at = "2026-08-29T16:55:00-0700"
     assert holder._value is not None
-    assert timedelta(hours=-7) == holder._value.utcoffset()
+    # parse_datetime normalises Cloud offsets to UTC on the read side, and the
+    # property decorator funnels through parse_datetime for string input.
+    assert timedelta(0) == holder._value.utcoffset()
+    assert holder._value.tzinfo is utc
 
 
 def test_property_is_datetime_accepts_datetime_instance():

test/test_subscription.py

@@ -157,13 +157,16 @@ def test_get_subscriptions_cloud_inline_schedule(server: TSC.Server) -> None:
     assert subscription.schedule.next_run_at is not None
     assert 2026 == subscription.schedule.next_run_at.year
     assert 8 == subscription.schedule.next_run_at.month
+    # 16:55 -07:00 on the wire -> 23:55 UTC after normalisation; wall date is unchanged.
     assert 29 == subscription.schedule.next_run_at.day
-
-    # The Cloud path deliberately preserves the ``-0700`` offset that came off
-    # the wire rather than normalising to UTC. A future regression to
-    # ``.replace(tzinfo=utc)`` after ``strptime`` would silently shift the
-    # instant by seven hours -- lock the non-UTC offset in here.
-    assert timedelta(hours=-7) == subscription.schedule.next_run_at.utcoffset()
+    assert 23 == subscription.schedule.next_run_at.hour
+    assert 55 == subscription.schedule.next_run_at.minute
+
+    # parse_datetime normalises Cloud's numeric wire offset to UTC so callers
+    # see a single uniform tzinfo across Server (already ``Z``) and Cloud
+    # (converted from ``-0700``). Locking that in guards against a future
+    # regression that would drop the ``astimezone(utc)`` on the Cloud branch.
+    assert timedelta(0) == subscription.schedule.next_run_at.utcoffset()
 
     # <frequencyDetails> nested <intervals> parsed into a DailyInterval carrying
     # the (hours, weekDay) pairs from the XML.