PR Feedback addressed.

mfateev · mfateev · commit 981878bc82ce · 2025-04-19T12:19:32.000-07:00
diff --git a/README.md b/README.md
@@ -446,6 +446,52 @@ my_data_converter = dataclasses.replace(
 
 Now `IPv4Address` can be used in type hints including collections, optionals, etc.
 
+When the `JSONPlainPayloadConverter` is used a class can implement `to_temporal_json` and `from_temporal_json` methods to 
+support custom conversion logic. Custom conversion of generic classes is supported.
+These methods should have the following signatures:
+
+```
+        class MyClass:
+            ...
+```
+`from_temporal_json` be either classmethod:
+```
+            @classmethod
+            def from_temporal_json(cls, json: Any) -> MyClass:
+                ...
+```
+ or static method:
+ ```           
+            @staticmethod
+            def from_temporal_json(json: Any) -> MyClass:
+                ...
+```
+`to_temporal_json` is always an instance method:
+```
+            def to_temporal_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          |
+    +-------------------+---------------+
+```
+
 ### Workers
 
 Workers host workflows and/or activities. Here's how to run a worker:
diff --git a/temporalio/converter.py b/temporalio/converter.py
@@ -489,43 +489,6 @@ 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.
@@ -538,11 +501,11 @@ def default(self, o: Any) -> Any:
         """
         # 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"
+        to_json = "to_temporal_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")
+                raise TypeError(f"Type {o.__class__}: {to_json} must be a method")
             return attr()
 
         # Dataclass support
@@ -570,6 +533,44 @@ class JSONPlainPayloadConverter(EncodingPayloadConverter):
 
     For decoding, this uses type hints to attempt to rebuild the type from the
     type hint.
+
+    A class can implement to_json and from_temporal_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_temporal_json(cls, json: Any) -> MyClass:
+                ...
+
+            def to_temporal_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          |
+    +-------------------+---------------+
+
+
     """
 
     _encoder: Optional[Type[json.JSONEncoder]]
@@ -1476,12 +1477,14 @@ def value_to_type(
         return value
 
     # Has from_json class method (must have to_json as well)
-    from_json = "from_json"
+    from_json = "from_temporal_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")
+        attr_cls = getattr(attr, "__self__", None)
+        if not callable(attr) or (attr_cls is not None and attr_cls is not origin):
+            raise TypeError(
+                f"Type {hint}: {from_json} must be a staticmethod or classmethod"
+            )
         return attr(value)
 
     is_union = origin is Union
diff --git a/tests/worker/test_workflow.py b/tests/worker/test_workflow.py
@@ -2256,10 +2256,32 @@ def __init__(self, field1: str):
         self.field2 = "foo"
 
     @classmethod
-    def from_json(cls, json_obj: Any) -> MyGenericClass:
+    def from_temporal_json(cls, json_obj: Any) -> MyGenericClass:
         return MyGenericClass(str(json_obj) + "_from_json")
 
-    def to_json(self) -> Any:
+    def to_temporal_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
+
+
+class MyGenericClassWithStatic(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"
+
+    @staticmethod
+    def from_temporal_json(json_obj: Any) -> MyGenericClass:
+        return MyGenericClass(str(json_obj) + "_from_json")
+
+    def to_temporal_json(self) -> Any:
         return self.field1 + "_to_json"
 
     def assert_expected(self, value: str) -> None:
@@ -2281,6 +2303,13 @@ async def generic_class_typed_activity(
     return param
 
 
+@activity.defn
+async def generic_class_typed_activity_with_static(
+    param: MyGenericClassWithStatic[str],
+) -> MyGenericClassWithStatic[str]:
+    return param
+
+
 @runtime_checkable
 @workflow.defn(name="DataClassTypedWorkflow")
 class DataClassTypedWorkflowProto(Protocol):
@@ -2347,13 +2376,13 @@ async def run(self, param: MyDataClass) -> MyDataClass:
             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,
+            generic_param_s = MyGenericClassWithStatic[str]("some_value2")
+            generic_param_s = await workflow.execute_local_activity(
+                generic_class_typed_activity_with_static,
+                generic_param_s,
                 start_to_close_timeout=timedelta(seconds=30),
             )
-            generic_param.assert_expected(
+            generic_param_s.assert_expected(
                 "some_value2_to_json_from_json_to_json_from_json"
             )
             child_handle = await workflow.start_child_workflow(
@@ -2400,7 +2429,11 @@ async def test_workflow_dataclass_typed(client: Client, env: WorkflowEnvironment
     async with new_worker(
         client,
         DataClassTypedWorkflow,
-        activities=[data_class_typed_activity, generic_class_typed_activity],
+        activities=[
+            data_class_typed_activity,
+            generic_class_typed_activity,
+            generic_class_typed_activity_with_static,
+        ],
     ) as worker:
         val = MyDataClass(field1="some value")
         handle = await client.start_workflow(
@@ -2427,7 +2460,11 @@ async def test_workflow_separate_protocol(client: Client):
     async with new_worker(
         client,
         DataClassTypedWorkflow,
-        activities=[data_class_typed_activity, generic_class_typed_activity],
+        activities=[
+            data_class_typed_activity,
+            generic_class_typed_activity,
+            generic_class_typed_activity_with_static,
+        ],
     ) as worker:
         assert isinstance(DataClassTypedWorkflow(), DataClassTypedWorkflowProto)
         val = MyDataClass(field1="some value")
@@ -2451,7 +2488,11 @@ async def test_workflow_separate_abstract(client: Client):
     async with new_worker(
         client,
         DataClassTypedWorkflow,
-        activities=[data_class_typed_activity, generic_class_typed_activity],
+        activities=[
+            data_class_typed_activity,
+            generic_class_typed_activity,
+            generic_class_typed_activity_with_static,
+        ],
     ) as worker:
         assert issubclass(DataClassTypedWorkflow, DataClassTypedWorkflowAbstract)
         val = MyDataClass(field1="some value")
