Update example and docs for type-directed deserialization

Author: andystaples

docs/supported-patterns.md

@@ -68,7 +68,8 @@ def purchase_order_workflow(ctx: task.OrchestrationContext, order: Order):
     yield ctx.call_activity(send_approval_request, input=order)
 
     # Approvals must be received within 24 hours or they will be cancelled.
-    approval_event = ctx.wait_for_external_event("approval_received")
+    # Passing ``data_type`` reconstructs the event payload as an ``Approval``.
+    approval_event = ctx.wait_for_external_event("approval_received", data_type=Approval)
     timeout_event = ctx.create_timer(timedelta(hours=24))
     winner = yield task.when_any([approval_event, timeout_event])
     if winner == timeout_event:
@@ -81,9 +82,11 @@ def purchase_order_workflow(ctx: task.OrchestrationContext, order: Order):
 ```
 
 As an aside, you'll also notice that the example orchestration above works with custom business
-objects. Support for custom business objects includes support for custom classes, custom data
-classes, and named tuples. Serialization and deserialization of these objects is handled
-automatically by the SDK.
+objects. Custom classes, data classes, and named tuples are serialized to plain JSON automatically.
+To reconstruct the original type on the receiving side, supply the type — for example via the
+`data_type` argument to `wait_for_external_event` (shown above), the `return_type` argument to
+`call_activity` / `call_sub_orchestrator` / `call_entity`, or by annotating the consuming function's
+input parameter. Without a type, the payload is returned as plain JSON (a `dict` or `list`).
 
 See the full [human interaction sample](../examples/human_interaction.py).
 

examples/in_memory_backend_example/src/workflows.py

@@ -9,11 +9,12 @@
 
 Note on serialization
 ---------------------
-The Durable Task SDK serializes dataclass and namedtuple inputs to JSON.
-When deserialized on the receiving side, top-level objects become
-``SimpleNamespace`` instances while nested objects become plain ``dict``s.
-Activities that receive complex inputs should therefore use dict-style
-access (``item["quantity"]``) for nested data.
+The Durable Task SDK serializes dataclass inputs to JSON. Annotating an
+orchestrator's or activity's input parameter with its dataclass type lets the
+SDK reconstruct that type on the receiving side (including nested dataclass
+fields), so the functions below use attribute access (``order.items``,
+``item.quantity``). Without a type annotation, payloads arrive as plain
+``dict`` / ``list`` values and would need dict-style access instead.
 """
 
 from dataclasses import dataclass
@@ -25,22 +26,22 @@
 # ---------------------------------------------------------------------------
 # Data models
 # ---------------------------------------------------------------------------
-# These dataclasses document the expected shape of the data. At runtime,
-# they are serialized to JSON and arrive in activities as SimpleNamespace
-# (top-level) or dict (nested) objects.
+# These dataclasses describe the shape of the data. Because the orchestrators
+# and activities annotate their inputs with these types, the SDK reconstructs
+# them (including the nested ``OrderItem`` list) on the receiving side.
 
 
 @dataclass
 class OrderItem:
-    """A single item in an order (arrives as a ``dict`` inside activities)."""
+    """A single item in an order."""
     name: str
     quantity: int
     unit_price: float
 
 
 @dataclass
 class Order:
-    """An order containing one or more items (arrives as ``SimpleNamespace``)."""
+    """An order containing one or more items."""
     customer: str
     items: list[OrderItem]
 
@@ -50,25 +51,25 @@ class Order:
 # ---------------------------------------------------------------------------
 
 
-def validate_order(ctx: task.ActivityContext, order) -> None:
+def validate_order(ctx: task.ActivityContext, order: Order) -> None:
     """Validate that the order has items and all quantities/prices are valid.
 
     Raises ``ValueError`` on invalid input.
     """
     if not order.items:
         raise ValueError("Order must contain at least one item")
     for item in order.items:
-        if item["quantity"] <= 0:
+        if item.quantity <= 0:
             raise ValueError(
-                f"Invalid quantity for '{item['name']}': {item['quantity']}")
-        if item["unit_price"] < 0:
+                f"Invalid quantity for '{item.name}': {item.quantity}")
+        if item.unit_price < 0:
             raise ValueError(
-                f"Invalid price for '{item['name']}': {item['unit_price']}")
+                f"Invalid price for '{item.name}': {item.unit_price}")
 
 
-def calculate_total(ctx: task.ActivityContext, items: list) -> float:
-    """Return the total cost for a list of item dicts."""
-    return sum(item["quantity"] * item["unit_price"] for item in items)
+def calculate_total(ctx: task.ActivityContext, items: list[OrderItem]) -> float:
+    """Return the total cost for a list of order items."""
+    return sum(item.quantity * item.unit_price for item in items)
 
 
 def process_payment(ctx: task.ActivityContext, amount: float) -> str:
@@ -95,7 +96,7 @@ def ship_item(ctx: task.ActivityContext, item_name: str) -> str:
 # ---------------------------------------------------------------------------
 
 
-def process_order(ctx: task.OrchestrationContext, order):
+def process_order(ctx: task.OrchestrationContext, order: Order):
     """Process a complete order: validate, pay, ship items in parallel, confirm.
 
     Demonstrates:
@@ -115,7 +116,7 @@ def process_order(ctx: task.OrchestrationContext, order):
 
     # 4. Ship all items in parallel (fan-out / fan-in)
     ship_tasks: list[task.Task[str]] = [
-        ctx.call_activity(ship_item, input=item["name"])
+        ctx.call_activity(ship_item, input=item.name)
         for item in order.items
     ]
     tracking_ids: list[str] = yield task.when_all(ship_tasks)
@@ -135,7 +136,7 @@ def process_order(ctx: task.OrchestrationContext, order):
     }
 
 
-def order_with_approval(ctx: task.OrchestrationContext, order):
+def order_with_approval(ctx: task.OrchestrationContext, order: Order):
     """Order workflow that requires manager approval for high-value orders.
 
     Demonstrates: