add more docs and examples

Author: aradyaron

docs/utilities/idempotency.md

@@ -156,16 +156,30 @@ When using `idempotent_function`, you must tell us which keyword parameter in yo
 
 By supplying an output serializer, you can control the return type of the function, allowing cleaner integration with the rest of your code base.
 
-=== "Using A Custom Type (Dataclasses)"
+=== "Using Pydantic"
+Explicitly passing the model type
+    ```python hl_lines="3-8 24-25 32-35 55"
+    --8<-- "examples/idempotency/src/working_with_idempotent_function_pydantic_output_serializer.py"
+    ```
+Deducing the model type from the return type annotation
+    ```python hl_lines="3-8 24-25 42-46 55"
+    --8<-- "examples/idempotency/src/working_with_idempotent_function_pydantic_output_serializer.py"
+    ```
 
-    ```python hl_lines="3-8 26-28 32-44 51"
-    --8<-- "examples/idempotency/src/working_with_idempotent_function_custom_output_serializer.py"
+=== "Using Dataclasses"
+Explicitly passing the model type
+    ```python hl_lines="1 5-8 27-29 36-39 59"
+    --8<-- "examples/idempotency/src/working_with_idempotent_function_dataclass_output_serializer.py"
+    ```
+Deducing the model type from the return type annotation
+    ```python hl_lines="1 5-8 27-29 46-50 60"
+    --8<-- "examples/idempotency/src/working_with_idempotent_function_dataclass_output_serializer.py"
     ```
 
-=== "Using Pydantic"
+=== "Using A Custom Type (Dataclasses)"
 
-    ```python hl_lines="3-8 23-24 32 35"
-    --8<-- "examples/idempotency/src/working_with_idempotent_function_pydantic_output_serializer.py"
+    ```python hl_lines="3-8 26-28 32-44 51"
+    --8<-- "examples/idempotency/src/working_with_idempotent_function_custom_output_serializer.py"
     ```
 
 #### Batch integration

examples/idempotency/src/working_with_idempotent_function_dataclass_output_serializer.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass
+
+from aws_lambda_powertools.utilities.idempotency import (
+    DynamoDBPersistenceLayer,
+    IdempotencyConfig,
+    idempotent_function,
+)
+from aws_lambda_powertools.utilities.idempotency.serialization.dataclass import DataclassSerializer
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+dynamodb = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+config = IdempotencyConfig(event_key_jmespath="order_id")  # see Choosing a payload subset section
+
+
+@dataclass
+class OrderItem:
+    sku: str
+    description: str
+
+
+@dataclass
+class Order:
+    item: OrderItem
+    order_id: int
+
+
+@dataclass
+class OrderOutput:
+    order_id: int
+
+
+@idempotent_function(
+    data_keyword_argument="order",
+    config=config,
+    persistence_store=dynamodb,
+    output_serializer=DataclassSerializer(model=OrderOutput),
+)
+def explicit_order_output_serializer(order: Order):
+    return OrderOutput(order_id=order.order_id)
+
+
+@idempotent_function(
+    data_keyword_argument="order",
+    config=config,
+    persistence_store=dynamodb,
+    output_serializer=DataclassSerializer,
+)
+# order output is deduced from return type
+def deduced_order_output_serializer(order: Order) -> OrderOutput:
+    return OrderOutput(order_id=order.order_id)
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    config.register_lambda_context(context)  # see Lambda timeouts section
+    order_item = OrderItem(sku="fake", description="sample")
+    order = Order(item=order_item, order_id=1)
+
+    # `order` parameter must be called as a keyword argument to work
+    explicit_order_output_serializer(order=order)
+    deduced_order_output_serializer(order=order)

examples/idempotency/src/working_with_idempotent_function_pydantic_output_serializer.py

@@ -31,7 +31,18 @@ class OrderOutput(BaseModel):
     persistence_store=dynamodb,
     output_serializer=PydanticSerializer(model=OrderOutput),
 )
-def process_order(order: Order) -> OrderOutput:
+def explicit_order_output_serializer(order: Order):
+    return OrderOutput(order_id=order.order_id)
+
+
+@idempotent_function(
+    data_keyword_argument="order",
+    config=config,
+    persistence_store=dynamodb,
+    output_serializer=PydanticSerializer,
+)
+# order output is deduced from return type
+def deduced_order_output_serializer(order: Order) -> OrderOutput:
     return OrderOutput(order_id=order.order_id)
 
 
@@ -41,4 +52,5 @@ def lambda_handler(event: dict, context: LambdaContext):
     order = Order(item=order_item, order_id=1)
 
     # `order` parameter must be called as a keyword argument to work
-    process_order(order=order)
+    explicit_order_output_serializer(order=order)
+    deduced_order_output_serializer(order=order)