Feature request: Simplify experience in discovering how much time left before Idempotency record expiration

[heitorlessa]

Use case

Provide a method to return a datetime object to make it easier to manipulate for customers building APIs, webhooks, and observable systems.

Docs

As of now, this is what we are expecting customers to do which is error prone for the non-initiated.

...

    # expiry_timestamp could be None so include if set
    expiry_timestamp = idempotent_data.expiry_timestamp
    if expiry_timestamp:
        expiry_time = datetime.datetime.fromtimestamp(int(expiry_timestamp))
        response["x-idempotent-expiration"] = expiry_time.isoformat()

    # Must return the response here
    return response

Solution/User Experience

    # this solution is not correct for edge cases, mostly for illustration
    def get_expiration_datetime(self) -> datetime | None:
        if self.expiry_timestamp:
            return datetime.datetime.fromtimestamp(int(self.expiry_timestamp))
        return None

Alternative solutions

Customers use the `expiry_timestamp` which they need to convert and manipulate from scratch.

https://docs.powertools.aws.dev/lambda/python/latest/utilities/idempotency/#manipulating-the-idempotent-response

Acknowledgment

• [X] This feature request meets Powertools for AWS Lambda (Python) Tenets
• [X] Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET