fix: parse Tableau Cloud's inlined subscription <schedule> (#1627)

Tableau Server references a schedule by id inside a <subscription>:

    <schedule id="cfb2..." name="Weekday mornings"/>

Tableau Cloud inlines the schedule instead -- no id attribute, but
a `frequency`, `nextRunAt` and a nested `<frequencyDetails>`:

    <schedule frequency="Daily" nextRunAt="2026-08-29T16:55:00-0700">
      <frequencyDetails start="16:55:00" end="16:55:00">
        <intervals>
          <interval hours="24"/>
          <interval weekDay="Saturday"/>
        </intervals>
      </frequencyDetails>
    </schedule>

Previously `SubscriptionItem` only pulled `id`/`name` off `<schedule>`,
so on Cloud every subscription came back with `schedule_id == None`
and no structured way to see what the API sent. Client code filtering
`[s for s in subs if s.schedule_id == target]` silently returned `[]`
on Cloud. This is the bug described in issue #1627.

Model changes:

* `SubscriptionItem` now populates a `schedule: ScheduleItem` attribute
  for both shapes. On Server, `schedule.id`/`.name` are set (and
  `schedule_id` remains populated for back-compat). On Cloud,
  `schedule.frequency`, `schedule.next_run_at`, and
  `schedule.interval_item` are set. `schedule_id` is `None` on Cloud --
  the API does not send one, unavoidable. Docstring calls out the
  Cloud-vs-Server discriminator and warns callers who filter by
  `schedule_id`. Fixes a latent bug where the previous Cloud branch
  assigned a list (return of `ScheduleItem.from_element`) to
  `sub.schedule` instead of a single item.
* `ScheduleItem` gains a `frequency` property. The XML attribute was
  already being read to select the interval type but was discarded;
  now it's exposed so callers can distinguish the Cloud shape without
  reaching into the interval object. The class `Attributes` docstring
  is rewritten to cover every public property and to note that only
  `frequency` / `next_run_at` / `interval_item` are populated when the
  item comes from an inlined Cloud subscription schedule.
* `_parse_interval_item` is defensive against malformed Cloud data:
  a `<frequencyDetails>` without a `start` attribute no longer crashes
  on `strptime(None, ...)`, and an out-of-range `<interval hours="3"/>`
  (or unknown weekDay / monthDay) no longer raises `ValueError` out of
  `IntervalItem` and poisons sibling schedules in the same page. Bad
  data degrades to `interval_item = None` with a warning log.

Datetime plumbing:

* `parse_datetime` learns the Tableau Cloud `%Y-%m-%dT%H:%M:%S%z` form
  (e.g. `2026-08-29T16:55:00-0700`) in addition to the Server `...Z`
  form. Unparseable input still returns `None` on the read path
  (preserving the pre-change contract that a malformed server-side
  date cannot crash a page-through of unrelated data).
* `property_is_datetime` now raises `ValueError` when `parse_datetime`
  returns `None` for a non-empty str value. Bad *user* input is
  surfaced at the assignment site instead of silently nulling the
  attribute.
* `TABLEAU_CLOUD_DATE_FORMAT` is public, matching the existing
  `TABLEAU_DATE_FORMAT`.

Tests:

* New `test/assets/subscription_get_cloud.xml` mirroring the shape
  observed on `stage-dp1` (API 3.29) and matching parse tests for
  both Cloud and Server shapes.
* Three edge-case Cloud fixtures + tests: no `<frequencyDetails>`,
  empty `<intervals/>`, out-of-set `<interval hours="3"/>`.
* Existing subscription tests extended to cover sub 2 and
  `get_subscription_by_id`.
* New `test/test_datetime_helpers.py` with direct coverage of
  `parse_datetime` (None / "" / garbage / Server / Cloud / colon-offset
  / microseconds) and `property_is_datetime` (valid / bad / non-str).
* `test/test_schedule.py::test_get` asserts the new
  `ScheduleItem.frequency` property on the standard /schedules endpoint.

Refs: #1627

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

Author: jacalata

tableauserverclient/datetime_helpers.py

@@ -26,15 +26,30 @@ def dst(self, dt):
 
 utc = UTC()
 TABLEAU_DATE_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+# Tableau Cloud emits some datetimes with a numeric UTC offset instead of the trailing "Z"
+# used by Tableau Server -- e.g. the ``nextRunAt`` attribute inlined into a subscription's
+# ``<schedule>`` element on Cloud looks like ``2026-08-29T16:55:00-0700``. Accept both.
+TABLEAU_CLOUD_DATE_FORMAT = "%Y-%m-%dT%H:%M:%S%z"
 
 
 def parse_datetime(date):
-    """Parse a Tableau API datetime string into a UTC-aware datetime, or None if absent or unparseable."""
+    """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
+    :func:`tableauserverclient.models.property_decorators.property_is_datetime`).
+    """
     if date is None:
         return None
-
     try:
         return datetime.datetime.strptime(date, TABLEAU_DATE_FORMAT).replace(tzinfo=utc)
+    except ValueError:
+        pass
+    try:
+        return datetime.datetime.strptime(date, TABLEAU_CLOUD_DATE_FORMAT)
     except ValueError:
         return None
 

tableauserverclient/models/property_decorators.py

@@ -126,6 +126,11 @@ def property_is_datetime(func):
 
     Because we return everything with Z as the timezone, we assume everything is in UTC and create
     a timezone aware datetime.
+
+    Setter-side strictness lives here: ``parse_datetime`` is deliberately lenient
+    on the server-response side (unparseable -> ``None``), so bad user input would
+    otherwise silently clear the attribute. We reject it here instead so misuse
+    surfaces at the assignment site with the offending value in the message.
     """
 
     @wraps(func)
@@ -138,6 +143,11 @@ def wrapper(self, value):
             )
 
         dt = parse_datetime(value)
+        if dt is None:
+            # ``value`` is a str (checked above) so a ``None`` result here can only
+            # mean "neither format matched" -- i.e. a genuine parse failure. Bubble
+            # it up so callers don't silently null out the attribute.
+            raise ValueError(f"Cannot parse {value!r} as a datetime, cannot update {func.__name__}")
         return func(self, dt)
 
     return wrapper

tableauserverclient/models/schedule_item.py

@@ -5,6 +5,7 @@
 from defusedxml.ElementTree import fromstring
 
 from tableauserverclient.datetime_helpers import parse_datetime
+from tableauserverclient.helpers.logging import logger
 from .interval_item import (
     IntervalItem,
     HourlyInterval,
@@ -65,20 +66,58 @@ class ScheduleItem:
 
     Attributes
     ----------
-    created_at : datetime
+    When a ``ScheduleItem`` is returned from the ``/schedules`` endpoint every
+    field below is populated. When it is materialised out of the inlined
+    ``<schedule>`` element of a Tableau **Cloud** subscription response,
+    only ``frequency``, ``next_run_at`` and ``interval_item`` are populated --
+    ``id``, ``name``, ``state``, ``created_at``, ``updated_at``, ``priority``,
+    ``execution_order`` and ``schedule_type`` will all be ``None`` on that path.
+
+    created_at : datetime | None
         The date and time the schedule was created.
 
-    end_schedule_at : datetime
+    end_schedule_at : datetime | None
         The date and time the schedule ends.
 
-    id : str
-        The unique identifier for the schedule.
-
-    next_run_at : datetime
+    execution_order : str | None
+        How the scheduled tasks run -- ``Parallel`` (uses all available background
+        processes) or ``Serial`` (limits the schedule to one background process).
+        See :class:`ScheduleItem.ExecutionOrder`.
+
+    frequency : str | None
+        One of ``Hourly`` / ``Daily`` / ``Weekly`` / ``Monthly`` when known.
+        Populated wherever the API returns ``<schedule frequency=...>`` --
+        notably by Tableau Cloud when a schedule is inlined into a
+        ``<subscription>`` response, and by the standard ``/schedules`` endpoint.
+
+    id : str | None
+        The unique identifier for the schedule. ``None`` for schedules inlined
+        into a Tableau Cloud subscription (the API does not send one).
+
+    interval_item : Interval | None
+        The parsed frequency detail as an :class:`IntervalItem` subclass
+        (``DailyInterval`` / ``WeeklyInterval`` / ``MonthlyInterval`` /
+        ``HourlyInterval``). ``None`` if the response omitted
+        ``<frequencyDetails>`` or if the intervals were malformed enough that
+        this client couldn't construct a strict-validated interval.
+
+    next_run_at : datetime | None
         The date and time the schedule is next run.
 
-    state : str
-        The state of the schedule. See ScheduleItem.State for the possible values.
+    priority : int | None
+        The priority of the schedule. Lower values represent higher priority,
+        with ``0`` indicating the highest priority.
+
+    schedule_type : str | None
+        The type of task schedule. See :class:`ScheduleItem.Type` for the
+        possible values (``Extract``, ``Flow``, ``Subscription``, ...).
+
+    state : str | None
+        The state of the schedule. See :class:`ScheduleItem.State` for the
+        possible values (``Active`` / ``Suspended``).
+
+    updated_at : datetime | None
+        The date and time the schedule was last updated.
     """
 
     class Type:
@@ -100,6 +139,7 @@ class State:
     def __init__(self, name: str, priority: int, schedule_type: str, execution_order: str, interval_item: Interval):
         self._created_at: datetime | None = None
         self._end_schedule_at: datetime | None = None
+        self._frequency: str | None = None
         self._id: str | None = None
         self._next_run_at: datetime | None = None
         self._state: str | None = None
@@ -133,6 +173,15 @@ def execution_order(self) -> str:
     def execution_order(self, value: str):
         self._execution_order = value
 
+    @property
+    def frequency(self) -> str | None:
+        """One of ``Hourly``, ``Daily``, ``Weekly``, ``Monthly`` when known.
+
+        Populated when the API returns ``<schedule frequency=...>`` -- notably by
+        Tableau Cloud when a schedule is inlined into a ``<subscription>`` response.
+        """
+        return self._frequency
+
     @property
     def id(self) -> str | None:
         return self._id
@@ -194,6 +243,7 @@ def _parse_common_tags(self, schedule_xml, ns):
                 _,
                 updated_at,
                 _,
+                _,
                 next_run_at,
                 end_schedule_at,
                 execution_order,
@@ -231,6 +281,7 @@ def _set_values(
         priority,
         interval_item,
         warnings=None,
+        frequency=None,
     ):
         if id_ is not None:
             self._id = id_
@@ -256,6 +307,8 @@ def _set_values(
             self._interval_item = interval_item
         if warnings:
             self._warnings = warnings
+        if frequency:
+            self._frequency = frequency
 
     @classmethod
     def from_response(cls, resp, ns):
@@ -276,6 +329,7 @@ def from_element(cls, parsed_response, ns):
                 created_at,
                 updated_at,
                 schedule_type,
+                frequency,
                 next_run_at,
                 end_schedule_at,
                 execution_order,
@@ -298,15 +352,19 @@ def from_element(cls, parsed_response, ns):
                 priority=None,
                 interval_item=None,
                 warnings=warnings,
+                frequency=frequency,
             )
 
             all_schedule_items.append(schedule_item)
         return all_schedule_items
 
     @staticmethod
     def _parse_interval_item(parsed_response, frequency, ns):
+        # Cloud <frequencyDetails> can omit ``start`` -- guard so we don't crash
+        # the whole subscriptions.get() page on ``datetime.strptime(None, ...)``.
         start_time = parsed_response.get("start", None)
-        start_time = datetime.strptime(start_time, "%H:%M:%S").time()
+        if start_time is not None:
+            start_time = datetime.strptime(start_time, "%H:%M:%S").time()
         end_time = parsed_response.get("end", None)
         if end_time is not None:
             end_time = datetime.strptime(end_time, "%H:%M:%S").time()
@@ -315,44 +373,63 @@ def _parse_interval_item(parsed_response, frequency, ns):
         for interval_elem in interval_elems:
             interval.extend(interval_elem.attrib.items())
 
-        if frequency == IntervalItem.Frequency.Daily:
-            converted_intervals = []
-
-            for i in interval:
-                # We use fractional hours for the two minute-based intervals.
-                # Need to convert to hours from minutes here
-                if i[0] == IntervalItem.Occurrence.Minutes:
-                    converted_intervals.append(float(i[1]) / 60)
-                elif i[0] == IntervalItem.Occurrence.Hours:
-                    converted_intervals.append(float(i[1]))
-                else:
-                    converted_intervals.append(i[1])
-
-            return DailyInterval(start_time, *converted_intervals)
-
-        if frequency == IntervalItem.Frequency.Hourly:
-            converted_intervals = []
-
-            for i in interval:
-                # We use fractional hours for the two minute-based intervals.
-                # Need to convert to hours from minutes here
-                if i[0] == IntervalItem.Occurrence.Minutes:
-                    converted_intervals.append(float(i[1]) / 60)
-                elif i[0] == IntervalItem.Occurrence.Hours:
-                    converted_intervals.append(i[1])
-                else:
-                    converted_intervals.append(i[1])
-
-            return HourlyInterval(start_time, end_time, tuple(converted_intervals))
-
-        if frequency == IntervalItem.Frequency.Weekly:
-            interval_values = [i[1] for i in interval]
-            return WeeklyInterval(start_time, *interval_values)
-
-        if frequency == IntervalItem.Frequency.Monthly:
-            interval_values = [i[1] for i in interval]
+        # IntervalItem constructors validate against a fixed VALID_INTERVALS set
+        # (e.g. ``{0.25, 0.5, 1, 2, 4, 6, 8, 12, 24}`` for hours) and raise
+        # ``ValueError`` on anything outside it. On Cloud we've seen values like
+        # ``hours="3"`` that Server never emits; letting that propagate would kill
+        # the whole subscription list. Degrade the single malformed schedule to
+        # ``interval_item = None`` so its siblings still parse.
+        try:
+            if frequency == IntervalItem.Frequency.Daily:
+                converted_intervals = []
+
+                for i in interval:
+                    # We use fractional hours for the two minute-based intervals.
+                    # Need to convert to hours from minutes here
+                    if i[0] == IntervalItem.Occurrence.Minutes:
+                        converted_intervals.append(float(i[1]) / 60)
+                    elif i[0] == IntervalItem.Occurrence.Hours:
+                        converted_intervals.append(float(i[1]))
+                    else:
+                        converted_intervals.append(i[1])
+
+                return DailyInterval(start_time, *converted_intervals)
+
+            if frequency == IntervalItem.Frequency.Hourly:
+                converted_intervals = []
+
+                for i in interval:
+                    # We use fractional hours for the two minute-based intervals.
+                    # Need to convert to hours from minutes here
+                    if i[0] == IntervalItem.Occurrence.Minutes:
+                        converted_intervals.append(float(i[1]) / 60)
+                    elif i[0] == IntervalItem.Occurrence.Hours:
+                        converted_intervals.append(i[1])
+                    else:
+                        converted_intervals.append(i[1])
+
+                return HourlyInterval(start_time, end_time, tuple(converted_intervals))
+
+            if frequency == IntervalItem.Frequency.Weekly:
+                interval_values = [i[1] for i in interval]
+                return WeeklyInterval(start_time, *interval_values)
+
+            if frequency == IntervalItem.Frequency.Monthly:
+                interval_values = [i[1] for i in interval]
+
+                return MonthlyInterval(start_time, tuple(interval_values))
+        except ValueError as exc:
+            logger.warning(
+                "Skipping malformed <frequencyDetails> " "(frequency=%s, start=%s, end=%s, intervals=%s): %s",
+                frequency,
+                start_time,
+                end_time,
+                interval,
+                exc,
+            )
+            return None
 
-            return MonthlyInterval(start_time, tuple(interval_values))
+        return None
 
     @staticmethod
     def _parse_element(schedule_xml, ns):
@@ -383,6 +460,7 @@ def _parse_element(schedule_xml, ns):
             created_at,
             updated_at,
             schedule_type,
+            frequency,
             next_run_at,
             end_schedule_at,
             execution_order,