Added support for class specific custom conversion through to_temporal_json/from_temporal_json methods

temporalio/converter.py

@@ -489,6 +489,43 @@ class AdvancedJSONEncoder(json.JSONEncoder):
 
     This encoder supports dataclasses and all iterables as lists.
 
+    A class can implement to_json and from_json methods to support custom conversion logic.
+    Custom conversion of generic classes is supported.
+    These methods should have the following signatures:
+
+    .. code-block:: python
+
+        class MyClass:
+            ...
+
+            @classmethod
+            def from_json(cls, json: Any) -> MyClass:
+                ...
+
+            def to_json(self) -> Any:
+                ...
+
+    The to_json should return the same Python JSON types produced by JSONEncoder:
+
+    +-------------------+---------------+
+    | Python            | JSON          |
+    +===================+===============+
+    | dict              | object        |
+    +-------------------+---------------+
+    | list, tuple       | array         |
+    +-------------------+---------------+
+    | str               | string        |
+    +-------------------+---------------+
+    | int, float        | number        |
+    +-------------------+---------------+
+    | True              | true          |
+    +-------------------+---------------+
+    | False             | false         |
+    +-------------------+---------------+
+    | None              | null          |
+    +-------------------+---------------+
+
+
     It also uses Pydantic v1's "dict" methods if available on the object,
     but this is deprecated. Pydantic users should upgrade to v2 and use
     temporalio.contrib.pydantic.pydantic_data_converter.
@@ -499,6 +536,15 @@ def default(self, o: Any) -> Any:
 
         See :py:meth:`json.JSONEncoder.default`.
         """
+        # Custom encoding and decoding through to_json and from_json
+        # to_json should be an instance method with only self argument
+        to_json = "to_json"
+        if hasattr(o, to_json):
+            attr = getattr(o, to_json)
+            if not callable(attr):
+                raise TypeError(f"Type {o.__class__}: to_json must be a method")
+            return attr()
+
         # Dataclass support
         if dataclasses.is_dataclass(o):
             return dataclasses.asdict(o)
@@ -1429,6 +1475,15 @@ def value_to_type(
             raise TypeError(f"Value {value} not in literal values {type_args}")
         return value
 
+    # Has from_json class method (must have to_json as well)
+    from_json = "from_json"
+    if hasattr(hint, from_json):
+        attr = getattr(hint, from_json)
+        attr_cls = getattr(attr, "__self__")
+        if not callable(attr) or not attr_cls == origin:
+            raise TypeError(f"Type {hint}: temporal_from_json must be a class method")
+        return attr(value)
+
     is_union = origin is Union
     if sys.version_info >= (3, 10):
         is_union = is_union or isinstance(origin, UnionType)

tests/worker/test_workflow.py

@@ -2243,12 +2243,44 @@ def assert_expected(self) -> None:
         assert self.field1 == "some value"
 
 
+T = typing.TypeVar("T")
+
+
+class MyGenericClass(typing.Generic[T]):
+    """
+    Demonstrates custom conversion and that it works even with generic classes.
+    """
+
+    def __init__(self, field1: str):
+        self.field1 = field1
+        self.field2 = "foo"
+
+    @classmethod
+    def from_json(cls, json_obj: Any) -> MyGenericClass:
+        return MyGenericClass(str(json_obj) + "_from_json")
+
+    def to_json(self) -> Any:
+        return self.field1 + "_to_json"
+
+    def assert_expected(self, value: str) -> None:
+        # Part of the assertion is that this is the right type, which is
+        # confirmed just by calling the method. We also check the field.
+        assert str(self.field1) == value
+
+
 @activity.defn
 async def data_class_typed_activity(param: MyDataClass) -> MyDataClass:
     param.assert_expected()
     return param
 
 
+@activity.defn
+async def generic_class_typed_activity(
+    param: MyGenericClass[str],
+) -> MyGenericClass[str]:
+    return param
+
+
 @runtime_checkable
 @workflow.defn(name="DataClassTypedWorkflow")
 class DataClassTypedWorkflowProto(Protocol):
@@ -2306,6 +2338,24 @@ async def run(self, param: MyDataClass) -> MyDataClass:
                 start_to_close_timeout=timedelta(seconds=30),
             )
             param.assert_expected()
+            generic_param = MyGenericClass[str]("some_value2")
+            generic_param = await workflow.execute_activity(
+                generic_class_typed_activity,
+                generic_param,
+                start_to_close_timeout=timedelta(seconds=30),
+            )
+            generic_param.assert_expected(
+                "some_value2_to_json_from_json_to_json_from_json"
+            )
+            generic_param = MyGenericClass[str]("some_value2")
+            generic_param = await workflow.execute_local_activity(
+                generic_class_typed_activity,
+                generic_param,
+                start_to_close_timeout=timedelta(seconds=30),
+            )
+            generic_param.assert_expected(
+                "some_value2_to_json_from_json_to_json_from_json"
+            )
             child_handle = await workflow.start_child_workflow(
                 DataClassTypedWorkflow.run,
                 param,
@@ -2348,7 +2398,9 @@ async def test_workflow_dataclass_typed(client: Client, env: WorkflowEnvironment
             "Java test server: https://github.com/temporalio/sdk-core/issues/390"
         )
     async with new_worker(
-        client, DataClassTypedWorkflow, activities=[data_class_typed_activity]
+        client,
+        DataClassTypedWorkflow,
+        activities=[data_class_typed_activity, generic_class_typed_activity],
     ) as worker:
         val = MyDataClass(field1="some value")
         handle = await client.start_workflow(
@@ -2373,7 +2425,9 @@ async def test_workflow_separate_protocol(client: Client):
     # This test is to confirm that protocols can be used as "interfaces" for
     # when the workflow impl is absent
     async with new_worker(
-        client, DataClassTypedWorkflow, activities=[data_class_typed_activity]
+        client,
+        DataClassTypedWorkflow,
+        activities=[data_class_typed_activity, generic_class_typed_activity],
     ) as worker:
         assert isinstance(DataClassTypedWorkflow(), DataClassTypedWorkflowProto)
         val = MyDataClass(field1="some value")
@@ -2395,7 +2449,9 @@ async def test_workflow_separate_abstract(client: Client):
     # This test is to confirm that abstract classes can be used as "interfaces"
     # for when the workflow impl is absent
     async with new_worker(
-        client, DataClassTypedWorkflow, activities=[data_class_typed_activity]
+        client,
+        DataClassTypedWorkflow,
+        activities=[data_class_typed_activity, generic_class_typed_activity],
     ) as worker:
         assert issubclass(DataClassTypedWorkflow, DataClassTypedWorkflowAbstract)
         val = MyDataClass(field1="some value")