Rename

Author: dandavison

temporalio/contrib/pydantic/converter.py temporalio/contrib/pydantic.pytemporalio/contrib/pydantic/converter.py renamed to temporalio/contrib/pydantic.py

@@ -1,3 +1,16 @@
+"""A data converter for Pydantic models
+
+To use, pass ``pydantic_data_converter`` as the ``data_converter`` argument to
+:py:class:`temporalio.client.Client`:
+
+.. code-block:: python
+
+    client = Client(
+        data_converter=pydantic_data_converter,
+        ...
+    )
+"""
+
 import inspect
 import json
 from typing import (
@@ -21,34 +34,7 @@
 from temporalio.worker.workflow_sandbox._restrictions import RestrictionContext
 
 
-class PydanticJSONPayloadConverter(JSONPlainPayloadConverter):
-    """Pydantic JSON payload converter.
-
-    Extends :py:class:`JSONPlainPayloadConverter` to override :py:meth:`to_payload` using
-    the Pydantic encoder. :py:meth:`from_payload` uses the parent implementation, with a
-    custom type converter.
-    """
-
-    def __init__(self) -> None:
-        super().__init__(custom_type_converters=[PydanticModelTypeConverter()])
-
-    def to_payload(self, value: Any) -> Optional[Payload]:
-        """Convert all values with Pydantic encoder or fail.
-
-        Like the base class, we fail if we cannot convert. This payload
-        converter is expected to be the last in the chain, so it can fail if
-        unable to convert.
-        """
-        # Let JSON conversion errors be thrown to caller
-        return Payload(
-            metadata={"encoding": self.encoding.encode()},
-            data=json.dumps(
-                value, separators=(",", ":"), sort_keys=True, default=pydantic_encoder
-            ).encode(),
-        )
-
-
-class PydanticModelTypeConverter(JSONTypeConverter):
+class _PydanticModelTypeConverter(JSONTypeConverter):
     def to_typed_value(self, hint: Type, value: Any) -> Any:
         if not inspect.isclass(hint) or not issubclass(hint, pydantic.BaseModel):
             return JSONTypeConverter.Unhandled
@@ -77,13 +63,47 @@ def to_typed_value(self, hint: Type, value: Any) -> Any:
             )
 
 
-class PydanticPayloadConverter(CompositePayloadConverter):
-    """Payload converter that replaces Temporal JSON conversion with Pydantic
+class _PydanticJSONPayloadConverter(JSONPlainPayloadConverter):
+    """Pydantic JSON payload converter.
+
+    Conversion to JSON is implemented by overriding :py:meth:`to_payload` to use the
+    Pydantic encoder.
+
+    Conversion from JSON uses the parent implementation of :py:meth:`from_payload`, with a
+    custom type converter. The parent implementation of :py:meth:`from_payload` traverses
+    the JSON document according to the structure specified by the type annotation; the
+    custom type converter ensures that, during this traversal, Pydantic model instances
+    will be created as specified by the type annotation.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(custom_type_converters=[_PydanticModelTypeConverter()])
+
+    def to_payload(self, value: Any) -> Optional[Payload]:
+        """Convert all values with Pydantic encoder or fail.
+
+        Like the base class, we fail if we cannot convert. This payload
+        converter is expected to be the last in the chain, so it can fail if
+        unable to convert.
+        """
+        # Let JSON conversion errors be thrown to caller
+        return Payload(
+            metadata={"encoding": self.encoding.encode()},
+            data=json.dumps(
+                value, separators=(",", ":"), sort_keys=True, default=pydantic_encoder
+            ).encode(),
+        )
+
+
+class _PydanticPayloadConverter(CompositePayloadConverter):
+    """Pydantic payload converter.
+
+    Payload converter that replaces the default JSON conversion with Pydantic
     JSON conversion.
     """
 
     def __init__(self) -> None:
-        json_payload_converter = PydanticJSONPayloadConverter()
+        json_payload_converter = _PydanticJSONPayloadConverter()
         super().__init__(
             *(
                 c
@@ -95,6 +115,9 @@ def __init__(self) -> None:
 
 
 pydantic_data_converter = DataConverter(
-    payload_converter_class=PydanticPayloadConverter
+    payload_converter_class=_PydanticPayloadConverter
 )
-"""Data converter using Pydantic JSON conversion."""
+"""Data converter for Pydantic models.
+
+To use, pass this as the ``data_converter`` argument to :py:class:`temporalio.client.Client`
+"""

tests/contrib/test_pydantic.py

@@ -8,7 +8,7 @@
 
 from temporalio import activity, workflow
 from temporalio.client import Client
-from temporalio.contrib.pydantic.converter import pydantic_data_converter
+from temporalio.contrib.pydantic import pydantic_data_converter
 from temporalio.worker import Worker
 
 SequenceType = TypeVar("SequenceType", bound=Sequence[Any])