feat(event_handler): add File parameter support for multipart/form-data uploads in OpenAPI utility

[oyiz-michael]

Issue number: #7124

closes #7124

Summary

This PR adds comprehensive File parameter support for handling file uploads in multipart/form-data requests within the AWS Lambda Powertools Python Event Handler with OpenAPI validation.

Changes

• Added File class in aws_lambda_powertools/event_handler/openapi/params.py

  • New parameter type specifically for file uploads
  • Inherits from Form with format: binary in OpenAPI schema
  • Supports validation constraints (max_length, etc.)

• Enhanced multipart parsing in aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

  • Added _parse_multipart_data method for parsing multipart/form-data
  • WebKit boundary support for Safari/Chrome compatibility
  • Base64 decoding support for Lambda event handling
  • Distinguishes between file fields and form fields

• Comprehensive test suite with 13 test scenarios covering:

  • Basic file uploads and multiple file handling
  • File + form data combinations
  • WebKit boundary parsing and base64 encoded content
  • Validation constraints and error handling
  • Optional file parameters

• Complete usage example in examples/event_handler_rest/src/file_parameter_example.py

User experience

Before: Users could not handle file uploads in multipart/form-data requests with OpenAPI validation. They had to manually parse request bodies or disable validation entirely.

After: Users can now use type-annotated File parameters that automatically:

• Parse multipart/form-data file uploads
• Generate proper OpenAPI schema with format: binary
• Apply validation constraints
• Work seamlessly with existing form parameters

from typing import Annotated
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.params import File, Form

app = APIGatewayRestResolver(enable_validation=True)

@app.post("/upload")
def upload_file(
    file: Annotated[bytes, File(description="File to upload", max_length=1000000)],
    title: Annotated[str, Form(description="File title")]
):
    return {"file_size": len(file), "title": title, "status": "uploaded"}

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: N/A

This is not a breaking change - it's a new feature addition that doesn't modify existing functionality.

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.

[leandrodamascena]

Hi @oyiz-michael, I see you are working on this PR and please let me know when you need a first round of review or any help.

[codecov]

Codecov Report

❌ Patch coverage is 96.96970% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.53%. Comparing base (60043ca) to head (35edb78).
⚠️ Report is 3 commits behind head on develop.

Files with missing lines	Patch %	Lines
...ls/event_handler/middlewares/openapi_validation.py	95.86%	3 Missing and 2 partials ⚠️
..._lambda_powertools/event_handler/openapi/params.py	96.36%	1 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##           develop    #7132    +/-   ##
=========================================
  Coverage    96.52%   96.53%            
=========================================
  Files          275      275            
  Lines        13117    13377   +260     
  Branches       986     1036    +50     
=========================================
+ Hits         12661    12913   +252     
- Misses         353      356     +3     
- Partials       103      108     +5     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[oyiz-michael]

Hi @oyiz-michael, I see you are working on this PR and please let me know when you need a first round of review or any help.

@leandrodamascena fixing some failing test and should be ready for a review and feed back

[leandrodamascena]

Hi @oyiz-michael, a quick tip: run make pr in your local environment and then you can catch errors before committing and pushing the files.

[leandrodamascena]

Hi @oyiz-michael! After merging the PRs I mentioned in the previous comment, I see we have some merge conflicts here. Can you fix them before we move forward?

Thanks

[tonnico]

Would it make sense to rely on python-multipart here instead of implementing custom parsing logic?
That library is already used by Starlette and FastAPI, handles boundary quirks and large uploads reliably, and would likely reduce maintenance and edge-case handling on our side. Using it as an optional dependency might be a cleaner long-term approach.

[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

[powertools-for-aws-oss-automation]

Not all issues are linked correctly.

Please link each issue to the PR either manually or using a closing keyword in the format fixes #<issue-number> format.

If mentioning more than one issue, separate them with commas: i.e. fixes #<issue-number-1>, closes #<issue-number-2>.

[leandrodamascena]

I'm reviewing this PR this week.