feat: require timezone-aware datetime for first_run_at

Change from warning to error when first_run_at is timezone-naive.
This prevents bugs from Python's datetime.timestamp() treating naive
datetimes as local time instead of UTC.

- Require explicit timezone on first_run_at datetime
- Remove warning, raise ValueError instead
- Update tests to match new behavior
- Aligns with Python best practices and Temporal SDK approach

Signed-off-by: Tim Li <ltim@uber.com>

Author: timl3136

cadence/client.py

@@ -1,7 +1,6 @@
 import os
 import socket
 import uuid
-import warnings
 from datetime import datetime, timedelta
 from typing import TypedDict, Unpack, Any, cast, Union
 
@@ -59,14 +58,14 @@ def _validate_and_apply_defaults(options: StartWorkflowOptions) -> StartWorkflow
     elif task_timeout <= timedelta(0):
         raise ValueError("task_start_to_close_timeout must be greater than 0")
 
-    # Warn if first_run_at is timezone-naive, and validate it's not before Unix epoch
+    # Validate first_run_at (must be timezone-aware and not before Unix epoch)
     first_run_at = options.get("first_run_at")
     if first_run_at is not None:
+        # Require timezone-aware datetime to prevent ambiguity
         if first_run_at.tzinfo is None:
-            warnings.warn(
-                "first_run_at is timezone-naive; it will be treated as UTC",
-                UserWarning,
-                stacklevel=3,
+            raise ValueError(
+                "first_run_at must be timezone-aware. "
+                "Use datetime.now(timezone.utc) or datetime(..., tzinfo=timezone.utc)"
             )
         # Validate timestamp is not before Unix epoch (matching Go client behavior)
         if first_run_at.timestamp() < 0:

tests/cadence/test_client_workflow.py

@@ -1,6 +1,5 @@
 import pytest
 import uuid
-import warnings
 from datetime import timedelta, datetime, timezone
 from unittest.mock import AsyncMock, Mock, PropertyMock
 
@@ -266,50 +265,28 @@ async def test_build_request_with_first_run_at_timezone_aware(self, mock_client)
             tzinfo=None
         )  # ToDatetime returns naive UTC
 
-    @pytest.mark.asyncio
-    async def test_build_request_with_first_run_at_naive(self, mock_client):
-        """Test building request with timezone-naive first_run_at."""
-        client = Client(domain="test-domain", target="localhost:7933")
-
-        first_run = datetime(2024, 6, 1, 12, 0, 0)  # Naive datetime
-
-        options = StartWorkflowOptions(
-            task_list="test-task-list",
-            execution_start_to_close_timeout=timedelta(minutes=10),
-            task_start_to_close_timeout=timedelta(seconds=30),
-            first_run_at=first_run,
-        )
-
-        request = client._build_start_workflow_request("TestWorkflow", (), options)
-
-        assert request.HasField("first_run_at")
-
-    def test_first_run_at_naive_datetime_warns(self):
-        """Test that timezone-naive first_run_at produces warning."""
+    def test_first_run_at_naive_datetime_raises_error(self):
+        """Test that timezone-naive first_run_at raises ValueError."""
         options = StartWorkflowOptions(
             task_list="test-task-list",
             execution_start_to_close_timeout=timedelta(minutes=10),
             first_run_at=datetime(2024, 1, 1, 12, 0, 0),  # Naive
         )
-        with pytest.warns(UserWarning, match="timezone-naive"):
+        with pytest.raises(ValueError, match="must be timezone-aware"):
             _validate_and_apply_defaults(options)
 
-    def test_first_run_at_aware_datetime_no_warning(self):
-        """Test that timezone-aware first_run_at produces no warning."""
+    def test_first_run_at_aware_datetime_is_valid(self):
+        """Test that timezone-aware first_run_at is valid."""
         options = StartWorkflowOptions(
             task_list="test-task-list",
             execution_start_to_close_timeout=timedelta(minutes=10),
             first_run_at=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
         )
-        # Should not warn - use warnings.catch_warnings to verify
-        with warnings.catch_warnings(record=True) as w:
-            warnings.simplefilter("always")
-            _validate_and_apply_defaults(options)
-            # Filter for our specific warning
-            relevant_warnings = [
-                warning for warning in w if "timezone-naive" in str(warning.message)
-            ]
-            assert len(relevant_warnings) == 0
+        # Should not raise
+        validated = _validate_and_apply_defaults(options)
+        assert validated["first_run_at"] == datetime(
+            2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc
+        )
 
     def test_first_run_at_before_epoch_raises_error(self):
         """Test that first_run_at before Unix epoch raises ValueError."""