Docs: Improve guidance to developers on reflecting record failures #2848
Description
What were you searching in the docs?
I was specifically looking for guidance in the docs on what the record_handler function should return to reflect a record (batch item) could not be handled successfully.
Is this related to an existing documentation section?
https://docs.powertools.aws.dev/lambda/python/latest/utilities/batch/#partial-failure-mechanics
How can we improve?
My recommendation is to specifically state that developers should raise an Exception (in python, for example) for any record that could not be processed successfully, and explicitly state the the "partial_process_response" object will handle any exceptions thrown by the record handler.
By looking at the "sample response" section, it implies that the "batchItemFailures" dictionary is returned, but it doesn't explicitly state how that response gets generated and what is required of the developer.
Got a suggestion in mind?
Responsibility of the developer/engineer implementing the record_handler method:
- Allow Exceptions to be propagated to the partial_process_response object, and/or
- Explicitly raise an Exception in the record handler
Either way, an Exception is used to notify the partial_process_response object that record handling was not successful.
From that point forward, the partial_process_response object will take care of formatting the "batchItemFailures" dictionary back to SQS.
Acknowledgment
- I understand the final update might be different from my proposed suggestion, or refused.