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 97.57785% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.40%. Comparing base (4a0269e) to head (1b307f8).
⚠️ Report is 11 commits behind head on develop.

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

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #7132      +/-   ##
===========================================
+ Coverage    96.37%   96.40%   +0.02%     
===========================================
  Files          275      276       +1     
  Lines        13048    13295     +247     
  Branches       974     1019      +45     
===========================================
+ Hits         12575    12817     +242     
- Misses         366      368       +2     
- Partials       107      110       +3     

☔ 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! Thank you so much for all your hard work on this. I've been testing this code extensively, and it seems to be working as expected, but I have a few comments that might be helpful for you when iterating with the GenAI tool.

1/ The code is missing a docstring in general. You've created new methods that are somewhat difficult to read and understand without proper comments/docstring. Can you improve this?

2/ I left a comment about the upload_file_fix.py file.

3/ The tests are very verbose and duplicated. Can you iterate to improve this?

Really thanks for all the effort, I'm super excited to merge this when we address all the things.

[oyiz-michael]

Hi @leandrodamascena I have addressed feedback about verbose and duplicated tests, coverage of the missing lines identified by codecov.
All tests passing with Improved code quality with better organization and clarity.

I really appreciate your patience and effort !

[leandrodamascena]

Hey @oyiz-michael the CI is failing with some problem in format. Please make sure to add in your workflow make format and make pr before pushing a new commit, in this way you can catch early bugs.

Thanks

[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>.

[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

[leandrodamascena]

Hi @oyiz-michael, a quick update here.

We have several PRs making changes that directly affect the OpenAPI and the event handler, two critical utilities we have, and we can't merge all the code at once because if there's a regression, we can easily roll it back. Our coverage is good, we have e2e tests, but we never know all the edge cases.

So, the order in which I'll be merging the PRs is:

1/ Today I merged this PR #7227 - and it will be included in the next release on September 25th.

2/ I'll work to merge this PR #7253 sometime after the 25th and include it in the release on October 7th.

3/ After October 7th, I will work to merge this PR and include it in the release on October 21st.

Thank you very much for your work and patience. I know as a OpenSource contributor sometimes we want to have the code in production, but we care a lot do not to introduce breaking changes to our customers, and this PR of yours is a bit more complex than the others.