docs(batch): explain record type discrepancy in failure and success handler

[duc00]

Issue number: #2816

Summary

This PR adds details to the Batch Processor / Extending BatchProcessor section of the docs.

Changes

• misc rewording for more clarity
• add warning about type discrepancy of record passed arg to success_handler and failure_handler
• complete example with a success_handler override case

User experience

Please share what the user experience looks like before and after this change

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change? No

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[heitorlessa]

Awesome recommendations 🚀 Loved the attention to detail in improving the code example and its name.

Requested minor changes and we can merge right afterwards.

[duc00]

@heitorlessa, thanks. Changes addressed. I also removed the reference to [Accessing processed messages] since every needed explanation is now in the warning.

[heitorlessa]

last brush up after I visualized locally; I'm accepting them and merging before I head for the weekend ;)

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[heitorlessa]

Merging. I've changed warning to note to make it less triggering for some audience, and remove the Example call out so we only have one where they'd pay attention to.

[boring-cyborg]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!

[duc00]

Great, thanks @heitorlessa. Enjoy the weekend