feat(batch): raise exception for invalid batch event

[anafalcao]

Issue number: #2394

Summary

Changes

This PR adds fail fast error handling for unexpected batch types in the Batch Processing utility.

• Added UnexpectedBatchTypeError to handle invalid batch types in process_partial_response and async_process_partial_response
• Error messaging to indicate valid event source types:
  Unexpected batch event type. Possible values are: SQS, KinesisDataStreams, DynamoDBStreams

User experience

from aws_lambda_powertools import Logger
from aws_lambda_powertools.utilities.batch import (
    BatchProcessor, 
    EventType,
    process_partial_response,
    UnexpectedBatchTypeError
)

logger = Logger()

def record_handler(record):
    return record["body"]

def handler(event, context):
    processor = BatchProcessor(event_type=EventType.SQS)
    
    try:
        return process_partial_response(
            event=event,
            record_handler=record_handler,
            processor=processor
        )
    except UnexpectedBatchTypeError as e:
        # "Unexpected batch event type. Possible values are: SQS, KinesisDataStreams, DynamoDBStreams"
        logger.error(f"Invalid batch event structure: {e}")
        raise

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?

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.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.25%. Comparing base (6e2171b) to head (293bb2c).
Report is 6 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #6088   +/-   ##
========================================
  Coverage    96.25%   96.25%           
========================================
  Files          234      234           
  Lines        11140    11147    +7     
  Branches       822      824    +2     
========================================
+ Hits         10723    10730    +7     
  Misses         327      327           
  Partials        90       90           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[leandrodamascena]

Hey @anafalcao! Thanks for working in this PR! I just left some comments before we merge this.

Please also leave a message in the original issue saying that we will raise an exception because we want to match the TypeScript version and have the same behavior in the API.

Also, in the "User Experience" section, add a complete example of the experience, including the try/except block, so that it's easy to copy when we write the release notes.

[anafalcao]

Hi @leandrodamascena ! Thank you for the feedback. I worked on them in this last commit, and updated the User Experience section for a more complete example.
I'll leave a message in the original issue.

[leandrodamascena]

APPROVED!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud