Improving doc

Author: leandrodamascena

docs/utilities/idempotency.md

@@ -950,20 +950,32 @@ You can set up a `response_hook` in the `IdempotentConfig` class to access the r
 
 === "Using an Idempotent Response Hook"
 
-    ```python hl_lines="15 17 20 31"
+    ```python hl_lines="18 20 23 32"
     --8<-- "examples/idempotency/src/working_with_response_hook.py"
     ```
 
 === "Sample event"
 
     ```json
-    --8<-- "examples/idempotency/src/getting_started_with_idempotency_payload.json"
+    --8<-- "examples/idempotency/src/working_with_response_hook_payload.json"
     ```
 
 ???+ info "Info: Using custom de-serialization?"
 
     The response_hook is called after the custom de-serialization so the payload you process will be the de-serialized version.
 
+#### Being a good citizen
+
+Using Response hooks can add subtle improvements to manipulating returned data from idempotent operations, but also add significant complexity if you're not careful.
+
+Keep the following in mind when authoring hooks for Idempotency utility:
+
+1. **Response hook works exclusively when operations are idempotent.** Carefully consider the logic within the `Response hook` and prevent any attempt to access the key from relying exclusively on idempotent operations.
+
+2. **Catch your own exceptions.** Catch and handle known exceptions to your logic.
+
+3. **Watch out when you are decorating the Lambda Handler and using the Response hook.** If you don't catch and handle exceptions in your `Response hook`, your function might not run properly.
+
 ## Compatibility with other utilities
 
 ### Batch

examples/idempotency/src/working_with_response_hook.py

@@ -1,16 +1,20 @@
-from datetime import datetime
+import datetime
+import uuid
 from typing import Dict
 
+from aws_lambda_powertools import Logger
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
     IdempotencyConfig,
-    idempotent,
+    idempotent_function,
 )
 from aws_lambda_powertools.utilities.idempotency.persistence.base import (
     DataRecord,
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
+logger = Logger()
+
 
 def my_response_hook(response: Dict, idempotent_data: DataRecord) -> Dict:
     # Return inserted Header data into the Idempotent Response
@@ -19,18 +23,34 @@ def my_response_hook(response: Dict, idempotent_data: DataRecord) -> Dict:
     # expiry_timestamp could be None so include if set
     expiry_timestamp = idempotent_data.expiry_timestamp
     if expiry_timestamp:
-        expiry_time = datetime.fromtimestamp(int(expiry_timestamp))
+        expiry_time = datetime.datetime.fromtimestamp(int(expiry_timestamp))
         response["x-idempotent-expiration"] = expiry_time.isoformat()
 
     # Must return the response here
     return response
 
 
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
-
+dynamodb = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
 config = IdempotencyConfig(response_hook=my_response_hook)
 
 
-@idempotent(persistence_store=persistence_layer, config=config)
-def lambda_handler(event: dict, context: LambdaContext) -> dict:
-    return event
+@idempotent_function(data_keyword_argument="order", config=config, persistence_store=dynamodb)
+def process_order(order: dict) -> dict:
+    # create the order_id
+    order_id = str(uuid.uuid4())
+
+    # create your logic to save the order
+    # append the order_id created
+    order["order_id"] = order_id
+
+    # return the order
+    return {"order": order}
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    config.register_lambda_context(context)  # see Lambda timeouts section
+    try:
+        logger.info(f"Processing order id {event.get('order_id')}")
+        return process_order(order=event.get("order"))
+    except Exception as err:
+        return {"status_code": 400, "error": f"Erro processing {str(err)}"}

examples/idempotency/src/working_with_response_hook_payload.json

@@ -0,0 +1,8 @@
+{
+  "order" : {
+    "user_id": "xyz",
+    "product_id": "123456789",
+    "quantity": 2,
+    "value": 30
+  }
+}