Address type-hint and docstring feedback on Cloud schedule parsing

- Widen SubscriptionItem.__init__.schedule_id to Optional[str]; Cloud
  inline <schedule> elements have no id and _parse_element passes None
- Rewrite property_is_datetime docstring: parse_datetime accepts both
  trailing-Z and explicit-offset forms; setter now raises ValueError on
  unparseable strings
- Correct the SubscriptionItem docstring's Cloud-vs-Server discriminator:
  the reliable check is (schedule is not None and schedule.id is None),
  not (interval_item is not None) - Cloud can omit <frequencyDetails>

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

Author: jacalata

tableauserverclient/models/property_decorators.py

@@ -120,17 +120,24 @@ def validate_regex_decorator(self, value):
 
 
 def property_is_datetime(func):
-    """Takes the following datetime format and turns it into a datetime object:
+    """Coerces the incoming value into a timezone-aware ``datetime`` object.
 
-    2016-08-18T18:25:36Z
+    ``parse_datetime`` (used on the read side) accepts two wire formats:
 
-    Because we return everything with Z as the timezone, we assume everything is in UTC and create
-    a timezone aware datetime.
+    * trailing-``Z`` UTC, e.g. ``2016-08-18T18:25:36Z``
+    * explicit ``%z`` offset, e.g. ``2026-09-01T10:00:00-0700`` (produced by
+      Tableau Cloud's inlined ``<schedule nextRunAt=...>``)
 
-    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.
+    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.
+
+    Setter-side strictness lives here: ``parse_datetime`` is deliberately
+    lenient on the server-response side (unparseable -> ``None``). This
+    decorator instead raises ``ValueError`` when the input is a string that
+    matches neither format, so bad user input surfaces at the assignment site
+    with the offending value in the message rather than silently clearing the
+    attribute.
     """
 
     @wraps(func)

tableauserverclient/models/subscription_item.py

@@ -34,10 +34,12 @@ class SubscriptionItem:
         </schedule>
 
     The reliable Cloud-vs-Server discriminator on a parsed ``SubscriptionItem``
-    is ``schedule.interval_item is not None`` (Cloud inlines the interval
-    detail; Server only sends an ``id``/``name`` reference and this field will
-    always be ``None`` there). ``schedule.id is None`` also identifies Cloud
-    but only in combination with ``schedule is not None`` -- see below.
+    is ``schedule is not None and schedule.id is None``. Cloud inlines the
+    ``<schedule>`` element **without** an ``id`` attribute; Server always sends
+    an ``id``/``name`` reference. ``schedule.interval_item`` is **not** a safe
+    discriminator: Cloud responses may omit ``<frequencyDetails>`` entirely
+    (leaving ``interval_item`` as ``None``), and malformed intervals are
+    intentionally downgraded to ``None`` during parsing.
 
     Attributes
     ----------
@@ -58,7 +60,7 @@ class SubscriptionItem:
         child at all -- always guard before dereferencing.
     """
 
-    def __init__(self, subject: str, schedule_id: str, user_id: str, target: "Target") -> None:
+    def __init__(self, subject: str, schedule_id: Optional[str], user_id: str, target: "Target") -> None:
         self._id = None
         self.attach_image = True
         self.attach_pdf = False

tableauserverclient/server/request_factory.py

@@ -1342,7 +1342,11 @@ def create_req(self, xml_request: ET.Element, subscription_item: "SubscriptionIt
         if subscription_item.send_if_view_empty is not None:
             content_element.attrib["sendIfViewEmpty"] = str(subscription_item.send_if_view_empty).lower()
 
-        # Schedule element
+        # Schedule element -- create_req is the Server workflow (Cloud
+        # subscriptions come with an inlined schedule and no id, and are not
+        # created via this path), so schedule_id is required here.
+        if subscription_item.schedule_id is None:
+            raise ValueError("schedule_id is required to create a subscription")
         schedule_element = ET.SubElement(subscription_element, "schedule")
         schedule_element.attrib["id"] = subscription_item.schedule_id