Add handling for datetimes to the default Json Converter (#872)

* Add a new converter to the default DataConverter for datetimes

* Move conversion into the json converter to allow nested datetimes

* Add timezone test

* Format and readme update

Author: tconley1428

README.md

@@ -316,10 +316,11 @@ The default data converter supports converting multiple types including:
   * Iterables including ones JSON dump may not support by default, e.g. `set`
   * [IntEnum, StrEnum](https://docs.python.org/3/library/enum.html) based enumerates
   * [UUID](https://docs.python.org/3/library/uuid.html)
+  * `datetime.datetime`
 
 To use pydantic model instances, see [Pydantic Support](#pydantic-support).
 
-`datetime.date`, `datetime.time`, and `datetime.datetime` can only be used with the Pydantic data converter.
+`datetime.date` and `datetime.time` can only be used with the Pydantic data converter.
 
 Although workflows, updates, signals, and queries can all be defined with multiple input parameters, users are strongly
 encouraged to use a single `dataclass` or Pydantic model parameter, so that fields with defaults can be easily added

temporalio/converter.py

@@ -500,6 +500,9 @@ def default(self, o: Any) -> Any:
 
         See :py:meth:`json.JSONEncoder.default`.
         """
+        # Datetime support
+        if isinstance(o, datetime):
+            return o.isoformat()
         # Dataclass support
         if dataclasses.is_dataclass(o):
             return dataclasses.asdict(o)
@@ -1132,7 +1135,7 @@ async def decode_failure(
     BinaryPlainPayloadConverter(),
     JSONProtoPayloadConverter(),
     BinaryProtoPayloadConverter(),
-    JSONPlainPayloadConverter(),
+    JSONPlainPayloadConverter(),  # JSON Plain needs to remain in last because it throws on unknown types
 )
 
 DataConverter.default = DataConverter()
@@ -1399,6 +1402,15 @@ def value_to_type(
     # Any or primitives
     if hint is Any:
         return value
+    elif hint is datetime:
+        if isinstance(value, str):
+            try:
+                return _get_iso_datetime_parser()(value)
+            except ValueError as err:
+                raise TypeError(f"Failed parsing datetime string: {value}") from err
+        elif isinstance(value, datetime):
+            return value
+        raise TypeError(f"Expected datetime or ISO8601 string, got {type(value)}")
     elif hint is int or hint is float:
         if not isinstance(value, (int, float)):
             raise TypeError(f"Expected value to be int|float, was {type(value)}")

tests/test_converter.py

@@ -8,7 +8,7 @@
 import traceback
 from collections import deque
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from enum import Enum, IntEnum
 from typing import (
     Any,
@@ -86,6 +86,11 @@ class MyDataClass:
     baz: SerializableEnum
 
 
+@dataclass
+class DatetimeClass:
+    datetime: datetime
+
+
 async def test_converter_default():
     async def assert_payload(
         input,
@@ -178,6 +183,38 @@ async def assert_payload(
         type_hint=RawValue,
     )
 
+    # Without type hint, it is deserialized as a str
+    await assert_payload(
+        datetime(2020, 1, 1, 1, 1, 1),
+        "json/plain",
+        '"2020-01-01T01:01:01"',
+        expected_decoded_input="2020-01-01T01:01:01",
+    )
+
+    # With type hint, it is deserialized as a datetime
+    await assert_payload(
+        datetime(2020, 1, 1, 1, 1, 1, 1),
+        "json/plain",
+        '"2020-01-01T01:01:01.000001"',
+        type_hint=datetime,
+    )
+
+    # Timezones work
+    await assert_payload(
+        datetime(2020, 1, 1, 1, 1, 1, tzinfo=timezone(timedelta(hours=5))),
+        "json/plain",
+        '"2020-01-01T01:01:01+05:00"',
+        type_hint=datetime,
+    )
+
+    # Data class with datetime
+    await assert_payload(
+        DatetimeClass(datetime=datetime(2020, 1, 1, 1, 1, 1)),
+        "json/plain",
+        '{"datetime":"2020-01-01T01:01:01"}',
+        type_hint=DatetimeClass,
+    )
+
 
 def test_binary_proto():
     # We have to test this separately because by default it never encodes