fix: reject naive datetimes and document Filter.__str__ format (#1025)

Naive datetime objects passed to Filter now raise ValueError with a
clear message instead of silently converting using the local system
timezone, which would produce wrong UTC values on any non-UTC machine.
Also adds a docstring to Filter.__str__ documenting the serialization
rules for all supported value types.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jacalata

tableauserverclient/server/filter.py

@@ -12,7 +12,26 @@ def __init__(self, field, operator, value):
         self.value = value
 
     def __str__(self):
+        """Return the filter as a Tableau REST API filter string.
+
+        Format: ``<field>:<operator>:<value>``
+
+        Value serialization rules:
+        - datetime: ISO-8601 UTC, e.g. ``2023-01-01T00:00:00Z``.
+          Naive datetimes (no tzinfo) are rejected with ValueError; always
+          pass timezone-aware datetime objects.
+        - bool: lowercase ``true`` or ``false`` as required by the REST API.
+        - list: bracket-enclosed comma-separated values, e.g. ``[a,b,c]``.
+          Only valid with the ``in`` operator.
+        - All other types: ``str()`` of the value.
+        """
         if isinstance(self._value, datetime.datetime):
+            if self._value.tzinfo is None:
+                raise ValueError(
+                    "Naive datetime passed to Filter; Tableau Server requires UTC. "
+                    "Use a timezone-aware datetime, e.g. "
+                    "datetime.datetime(..., tzinfo=datetime.timezone.utc)."
+                )
             return f"{self.field}:{self.operator}:{format_datetime(self._value)}"
         if isinstance(self._value, bool):
             # Tableau REST API requires lowercase 'true'/'false', not Python's 'True'/'False'

test/test_filter.py

@@ -107,6 +107,16 @@ def test_filter_bool_has_extracts():
     assert str(filter) == "hasExtracts:eq:true"
 
 
+def test_filter_date_naive_raises():
+    """A naive datetime (no tzinfo) raises ValueError with a helpful message."""
+    import pytest
+
+    naive_dt = datetime.datetime(2023, 1, 1, 12, 0, 0)  # no tzinfo
+    f = TSC.Filter(TSC.RequestOptions.Field.CreatedAt, TSC.RequestOptions.Operator.Equals, naive_dt)
+    with pytest.raises(ValueError, match="Naive datetime"):
+        str(f)
+
+
 def test_filter_list_rejects_non_in_operator():
     """A list value with a non-In operator raises ValueError."""
     import pytest