docs(idempotency): improve navigation, wording, and new section on guarantees

examples/idempotency/src/customize_persistence_layer.py

@@ -1,11 +1,14 @@
+import os
+
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
     idempotent,
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
+table = os.getenv("IDEMPOTENCY_TABLE", "")
 persistence_layer = DynamoDBPersistenceLayer(
-    table_name="IdempotencyTable",
+    table_name=table,
     key_attr="idempotency_key",
     expiry_attr="expires_at",
     in_progress_expiry_attr="in_progress_expires_at",

examples/idempotency/src/customize_persistence_layer_redis.py

@@ -1,3 +1,5 @@
+import os
+
 from aws_lambda_powertools.utilities.idempotency import (
     idempotent,
 )
@@ -6,8 +8,9 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
+redis_endpoint = os.getenv("REDIS_CLUSTER_ENDPOINT", "localhost")
 persistence_layer = RedisCachePersistenceLayer(
-    host="localhost",
+    host=redis_endpoint,
     port=6379,
     in_progress_expiry_attr="in_progress_expiration",
     status_attr="status",

examples/idempotency/src/getting_started_with_idempotency.py

@@ -1,3 +1,4 @@
+import os
 from dataclasses import dataclass, field
 from uuid import uuid4
 
@@ -7,7 +8,8 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table)
 
 
 @dataclass
@@ -17,8 +19,7 @@ class Payment:
     payment_id: str = field(default_factory=lambda: f"{uuid4()}")
 
 
-class PaymentError(Exception):
-    ...
+class PaymentError(Exception): ...
 
 
 @idempotent(persistence_store=persistence_layer)

examples/idempotency/src/getting_started_with_idempotency_redis_client.py

@@ -1,3 +1,4 @@
+import os
 from dataclasses import dataclass, field
 from uuid import uuid4
 
@@ -11,8 +12,9 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
+redis_endpoint = os.getenv("REDIS_CLUSTER_ENDPOINT", "localhost")
 client = Redis(
-    host="localhost",
+    host=redis_endpoint,
     port=6379,
     socket_connect_timeout=5,
     socket_timeout=5,
@@ -29,8 +31,7 @@ class Payment:
     payment_id: str = field(default_factory=lambda: f"{uuid4()}")
 
 
-class PaymentError(Exception):
-    ...
+class PaymentError(Exception): ...
 
 
 @idempotent(persistence_store=persistence_layer)

examples/idempotency/src/getting_started_with_idempotency_redis_config.py

@@ -1,3 +1,4 @@
+import os
 from dataclasses import dataclass, field
 from uuid import uuid4
 
@@ -9,7 +10,8 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-persistence_layer = RedisCachePersistenceLayer(host="localhost", port=6379)
+redis_endpoint = os.getenv("REDIS_CLUSTER_ENDPOINT", "localhost")
+persistence_layer = RedisCachePersistenceLayer(host=redis_endpoint, port=6379)
 
 
 @dataclass
@@ -19,8 +21,7 @@ class Payment:
     payment_id: str = field(default_factory=lambda: f"{uuid4()}")
 
 
-class PaymentError(Exception):
-    ...
+class PaymentError(Exception): ...
 
 
 @idempotent(persistence_store=persistence_layer)

examples/idempotency/src/integrate_idempotency_with_batch_processor.py

@@ -1,5 +1,7 @@
-from aws_lambda_powertools import Logger
-from aws_lambda_powertools.utilities.batch import BatchProcessor, EventType
+import os
+from typing import Any, Dict
+
+from aws_lambda_powertools.utilities.batch import BatchProcessor, EventType, process_partial_response
 from aws_lambda_powertools.utilities.data_classes.sqs_event import SQSRecord
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
@@ -8,30 +10,24 @@
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-logger = Logger()
 processor = BatchProcessor(event_type=EventType.SQS)
 
-dynamodb = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
-config = IdempotencyConfig(
-    event_key_jmespath="messageId",  # see Choosing a payload subset section
-)
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+dynamodb = DynamoDBPersistenceLayer(table_name=table)
+config = IdempotencyConfig(event_key_jmespath="messageId")
 
 
 @idempotent_function(data_keyword_argument="record", config=config, persistence_store=dynamodb)
 def record_handler(record: SQSRecord):
     return {"message": record.body}
 
 
-def lambda_handler(event: SQSRecord, context: LambdaContext):
+def lambda_handler(event: Dict[str, Any], context: LambdaContext):
     config.register_lambda_context(context)  # see Lambda timeouts section
 
-    # with Lambda context registered for Idempotency
-    # we can now kick in the Bach processing logic
-    batch = event["Records"]
-    with processor(records=batch, handler=record_handler):
-        # in case you want to access each record processed by your record_handler
-        # otherwise ignore the result variable assignment
-        processed_messages = processor.process()
-        logger.info(processed_messages)
-
-    return processor.response()
+    return process_partial_response(
+        event=event,
+        context=context,
+        processor=processor,
+        record_handler=record_handler,
+    )

examples/idempotency/src/integrate_idempotency_with_validator.py

@@ -1,3 +1,5 @@
+import os
+
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
     IdempotencyConfig,
@@ -6,8 +8,9 @@
 from aws_lambda_powertools.utilities.typing import LambdaContext
 from aws_lambda_powertools.utilities.validation import envelopes, validator
 
+table = os.getenv("IDEMPOTENCY_TABLE", "")
 config = IdempotencyConfig(event_key_jmespath='["message", "username"]')
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table)
 
 
 @validator(envelope=envelopes.API_GATEWAY_HTTP)

examples/idempotency/src/using_redis_client_with_aws_secrets.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import Any
 
 from redis import Redis
@@ -8,11 +10,11 @@
     RedisCachePersistenceLayer,
 )
 
-redis_values: Any = parameters.get_secret("redis_info", transform="json")  # (1)!
+redis_values: dict[str, Any] = parameters.get_secret("redis_info", transform="json")  # (1)!
 
 redis_client = Redis(
-    host=redis_values.get("REDIS_HOST"),
-    port=redis_values.get("REDIS_PORT"),
+    host=redis_values.get("REDIS_HOST", "localhost"),
+    port=redis_values.get("REDIS_PORT", 6379),
     password=redis_values.get("REDIS_PASSWORD"),
     decode_responses=True,
     socket_timeout=10.0,

examples/idempotency/src/using_redis_client_with_local_certs.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import Any
 
 from redis import Redis
@@ -9,12 +11,12 @@
     RedisCachePersistenceLayer,
 )
 
-redis_values: Any = parameters.get_secret("redis_info", transform="json")  # (1)!
+redis_values: dict[str, Any] = parameters.get_secret("redis_info", transform="json")  # (1)!
 
 
 redis_client = Redis(
-    host=redis_values.get("REDIS_HOST"),
-    port=redis_values.get("REDIS_PORT"),
+    host=redis_values.get("REDIS_HOST", "localhost"),
+    port=redis_values.get("REDIS_PORT", 6379),
     password=redis_values.get("REDIS_PASSWORD"),
     decode_responses=True,
     socket_timeout=10.0,

examples/idempotency/src/working_with_composite_key.py

@@ -1,10 +1,13 @@
+import os
+
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
     idempotent,
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable", sort_key_attr="sort_key")
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table, sort_key_attr="sort_key")
 
 
 @idempotent(persistence_store=persistence_layer)

examples/idempotency/src/working_with_custom_config.py

@@ -1,3 +1,5 @@
+import os
+
 from botocore.config import Config
 
 from aws_lambda_powertools.utilities.idempotency import (
@@ -10,7 +12,8 @@
 # See: https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore-config
 boto_config = Config()
 
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable", boto_config=boto_config)
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table, boto_config=boto_config)
 
 config = IdempotencyConfig(event_key_jmespath="body")
 

examples/idempotency/src/working_with_custom_session.py

@@ -1,3 +1,5 @@
+import os
+
 import boto3
 
 from aws_lambda_powertools.utilities.idempotency import (
@@ -10,7 +12,8 @@
 # See: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html#module-boto3.session
 boto3_session = boto3.session.Session()
 
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable", boto3_session=boto3_session)
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table, boto3_session=boto3_session)
 
 config = IdempotencyConfig(event_key_jmespath="body")
 

examples/idempotency/src/working_with_dataclass_deduced_output_serializer.py

@@ -1,3 +1,4 @@
+import os
 from dataclasses import dataclass
 
 from aws_lambda_powertools.utilities.idempotency import (
@@ -8,7 +9,8 @@
 from aws_lambda_powertools.utilities.idempotency.serialization.dataclass import DataclassSerializer
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-dynamodb = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+dynamodb = DynamoDBPersistenceLayer(table_name=table)
 config = IdempotencyConfig(event_key_jmespath="order_id")  # see Choosing a payload subset section
 
 

examples/idempotency/src/working_with_dataclass_explicitly_output_serializer.py

@@ -1,3 +1,4 @@
+import os
 from dataclasses import dataclass
 
 from aws_lambda_powertools.utilities.idempotency import (
@@ -8,7 +9,8 @@
 from aws_lambda_powertools.utilities.idempotency.serialization.dataclass import DataclassSerializer
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-dynamodb = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+dynamodb = DynamoDBPersistenceLayer(table_name=table)
 config = IdempotencyConfig(event_key_jmespath="order_id")  # see Choosing a payload subset section
 
 

examples/idempotency/src/working_with_exceptions.py

@@ -1,37 +1,38 @@
+import os
+
 import requests
 
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
     IdempotencyConfig,
     idempotent_function,
 )
+from aws_lambda_powertools.utilities.idempotency.exceptions import IdempotencyPersistenceLayerError
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table)
 
 config = IdempotencyConfig()
 
 
-def lambda_handler(event: dict, context: LambdaContext):
-    # If an exception is raised here, no idempotent record will ever get created as the
-    # idempotent function does not get called
-    try:
-        endpoint = "https://jsonplaceholder.typicode.com/comments/"  # change this endpoint to force an exception
-        requests.get(endpoint)
-    except Exception as exc:
-        return str(exc)
-
-    call_external_service(data={"user": "user1", "id": 5})
-
-    # This exception will not cause the idempotent record to be deleted, since it
-    # happens after the decorated function has been successfully called
-    raise Exception
-
-
 @idempotent_function(data_keyword_argument="data", config=config, persistence_store=persistence_layer)
 def call_external_service(data: dict):
+    # Any exception raised will lead to idempotency record to be deleted
     result: requests.Response = requests.post(
         "https://jsonplaceholder.typicode.com/comments/",
-        json={"user": data["user"], "transaction_id": data["id"]},
+        json=data,
     )
     return result.json()
+
+
+def lambda_handler(event: dict, context: LambdaContext):
+    try:
+        call_external_service(data=event)
+    except IdempotencyPersistenceLayerError as e:
+        # No idempotency, but you can decide to error differently.
+        raise RuntimeError(f"Oops, can't talk to persistence layer. Permissions? error: {e}")
+
+    # This exception will not impact the idempotency of 'call_external_service'
+    # because it happens in isolation, or outside their scope.
+    raise SyntaxError("Oops, this shouldn't be here.")

examples/idempotency/src/working_with_idempotency_key_required.py

@@ -1,11 +1,14 @@
+import os
+
 from aws_lambda_powertools.utilities.idempotency import (
     DynamoDBPersistenceLayer,
     IdempotencyConfig,
     idempotent,
 )
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-persistence_layer = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+persistence_layer = DynamoDBPersistenceLayer(table_name=table)
 config = IdempotencyConfig(
     event_key_jmespath='["user.uid", "order_id"]',
     raise_on_no_idempotency_key=True,

examples/idempotency/src/working_with_idempotent_function_custom_output_serializer.py

@@ -1,3 +1,4 @@
+import os
 from typing import Dict, Type
 
 from aws_lambda_powertools.utilities.idempotency import (
@@ -8,7 +9,8 @@
 from aws_lambda_powertools.utilities.idempotency.serialization.custom_dict import CustomDictSerializer
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-dynamodb = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+table = os.getenv("IDEMPOTENCY_TABLE", "")
+dynamodb = DynamoDBPersistenceLayer(table_name=table)
 config = IdempotencyConfig(event_key_jmespath="order_id")  # see Choosing a payload subset section