feat: Add File parameter support for multipart/form-data file uploads

- Add File parameter class in openapi/params.py with binary format schema
- Implement comprehensive multipart/form-data parsing in openapi_validation.py
  * Support for WebKit and standard boundary formats
  * Base64-encoded request handling for AWS Lambda
  * Mixed file and form data parsing
- Update dependant.py to handle File parameters in body field resolution
- Add comprehensive test suite (13 tests) covering:
  * Basic file upload parsing and validation
  * WebKit boundary format support
  * Base64-encoded multipart data
  * Multiple file uploads
  * File size constraints validation
  * Optional file parameters
  * Error handling for invalid boundaries and missing files
- Add file_parameter_example.py demonstrating various File parameter use cases
- Clean up unnecessary imports and pragma comments

Resolves file upload functionality with full OpenAPI schema generation and validation support.

Author: oyiz-michael

aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

@@ -3,6 +3,7 @@
 import dataclasses
 import json
 import logging
+import re
 from copy import deepcopy
 from typing import TYPE_CHECKING, Any, Callable, Mapping, MutableMapping, Sequence
 from urllib.parse import parse_qs
@@ -177,7 +178,6 @@ def _parse_form_data(self, app: EventHandlerInstance) -> dict[str, Any]:
     def _parse_multipart_data(self, app: EventHandlerInstance, content_type: str) -> dict[str, Any]:
         """Parse multipart/form-data."""
         import base64
-        import re
 
         try:
             # Get the raw body - it might be base64 encoded

aws_lambda_powertools/event_handler/openapi/dependant.py

@@ -20,7 +20,6 @@
     Param,
     ParamTypes,
     Query,
-    _File,
     analyze_param,
     create_response_field,
     get_flat_dependant,

aws_lambda_powertools/event_handler/openapi/params.py

@@ -811,7 +811,7 @@ def __init__(
         )
 
 
-class _File(Form):
+class File(Form):
     """
     A class used to represent a file parameter in a path operation.
     """
@@ -851,12 +851,11 @@ def __init__(
         **extra: Any,
     ):
         # For file uploads, ensure the OpenAPI schema has the correct format
-        # Also we can't test it
-        file_schema_extra = {"format": "binary"}  # pragma: no cover
-        if json_schema_extra:  # pragma: no cover
-            json_schema_extra.update(file_schema_extra)  # pragma: no cover
-        else:  # pragma: no cover
-            json_schema_extra = file_schema_extra  # pragma: no cover
+        file_schema_extra = {"format": "binary"}
+        if json_schema_extra:
+            json_schema_extra.update(file_schema_extra)
+        else:
+            json_schema_extra = file_schema_extra
 
         super().__init__(
             default=default,
@@ -890,29 +889,6 @@ def __init__(
         )
 
 
-class File(_File):
-    """
-    Defines a file parameter that should be extracted from multipart form data.
-
-    This parameter type is used for file uploads in multipart/form-data requests
-    and integrates with OpenAPI schema generation.
-
-    Example:
-    -------
-    ```python
-    from typing import Annotated
-    from aws_lambda_powertools.event_handler import APIGatewayRestResolver
-    from aws_lambda_powertools.event_handler.openapi.params import File
-
-    app = APIGatewayRestResolver(enable_validation=True)
-
-    @app.post("/upload")
-    def upload_file(file: Annotated[bytes, File(description="File to upload")]):
-        return {"file_size": len(file)}
-    ```
-    """
-
-
 def get_flat_dependant(
     dependant: Dependant,
     visited: list[CacheKey] | None = None,

examples/event_handler_rest/src/file_parameter_example.py

@@ -0,0 +1,94 @@
+"""
+Example demonstrating File parameter usage in AWS Lambda Powertools Python Event Handler.
+
+This example shows how to use the File parameter for handling multipart/form-data file uploads
+with OpenAPI validation and automatic schema generation.
+"""
+
+from typing import Annotated
+
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.event_handler.openapi.params import File, Form
+
+
+# Initialize resolver with OpenAPI validation enabled
+app = APIGatewayRestResolver(enable_validation=True)
+
+
+@app.post("/upload")
+def upload_single_file(file: Annotated[bytes, File(description="File to upload")]):
+    """Upload a single file."""
+    return {"status": "uploaded", "file_size": len(file), "message": "File uploaded successfully"}
+
+
+@app.post("/upload-with-metadata")
+def upload_file_with_metadata(
+    file: Annotated[bytes, File(description="File to upload")],
+    description: Annotated[str, Form(description="File description")],
+    tags: Annotated[str | None, Form(description="Optional tags")] = None,
+):
+    """Upload a file with additional form metadata."""
+    return {
+        "status": "uploaded",
+        "file_size": len(file),
+        "description": description,
+        "tags": tags,
+        "message": "File and metadata uploaded successfully",
+    }
+
+
+@app.post("/upload-multiple")
+def upload_multiple_files(
+    primary_file: Annotated[bytes, File(alias="primary", description="Primary file")],
+    secondary_file: Annotated[bytes, File(alias="secondary", description="Secondary file")],
+):
+    """Upload multiple files."""
+    return {
+        "status": "uploaded",
+        "primary_size": len(primary_file),
+        "secondary_size": len(secondary_file),
+        "total_size": len(primary_file) + len(secondary_file),
+        "message": "Multiple files uploaded successfully",
+    }
+
+
+@app.post("/upload-with-constraints")
+def upload_small_file(file: Annotated[bytes, File(description="Small file only", max_length=1024)]):
+    """Upload a file with size constraints (max 1KB)."""
+    return {
+        "status": "uploaded",
+        "file_size": len(file),
+        "message": f"Small file uploaded successfully ({len(file)} bytes)",
+    }
+
+
+@app.post("/upload-optional")
+def upload_optional_file(
+    message: Annotated[str, Form(description="Required message")],
+    file: Annotated[bytes | None, File(description="Optional file")] = None,
+):
+    """Upload with an optional file parameter."""
+    return {
+        "status": "processed",
+        "message": message,
+        "has_file": file is not None,
+        "file_size": len(file) if file else 0,
+    }
+
+
+# Lambda handler function
+def lambda_handler(event, context):
+    """AWS Lambda handler function."""
+    return app.resolve(event, context)
+
+
+# The File parameter provides:
+# 1. Automatic multipart/form-data parsing
+# 2. OpenAPI schema generation with proper file upload documentation
+# 3. Request validation with meaningful error messages
+# 4. Support for file constraints (max_length, etc.)
+# 5. Compatibility with WebKit and other browser boundary formats
+# 6. Base64-encoded request handling (common in AWS Lambda)
+# 7. Mixed file and form data support
+# 8. Multiple file upload support
+# 9. Optional file parameters

tests/functional/event_handler/_pydantic/test_file_form_validation.py

@@ -0,0 +1,133 @@
+"""
+Test File and Form parameter validation functionality.
+"""
+
+import json
+from typing import Annotated
+
+import pytest
+
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.event_handler.openapi.params import File, Form
+
+
+def make_request_event(method="GET", path="/", body="", headers=None, query_params=None):
+    """Create a minimal API Gateway request event for testing."""
+    return {
+        "resource": path,
+        "path": path,
+        "httpMethod": method,
+        "headers": headers or {},
+        "multiValueHeaders": {},
+        "queryStringParameters": query_params,
+        "multiValueQueryStringParameters": {},
+        "pathParameters": None,
+        "stageVariables": None,
+        "requestContext": {
+            "path": f"/stage{path}",
+            "accountId": "123456789012",
+            "resourceId": "abcdef",
+            "stage": "test",
+            "requestId": "test-request-id",
+            "identity": {
+                "cognitoIdentityPoolId": None,
+                "accountId": None,
+                "cognitoIdentityId": None,
+                "caller": None,
+                "apiKey": None,
+                "sourceIp": "127.0.0.1",
+                "cognitoAuthenticationType": None,
+                "cognitoAuthenticationProvider": None,
+                "userArn": None,
+                "userAgent": "Custom User Agent String",
+                "user": None,
+            },
+            "resourcePath": path,
+            "httpMethod": method,
+            "apiId": "abcdefghij",
+        },
+        "body": body,
+        "isBase64Encoded": False,
+    }
+
+
+def test_form_parameter_validation():
+    """Test basic form parameter validation."""
+    app = APIGatewayRestResolver(enable_validation=True)
+
+    @app.post("/contact")
+    def contact_form(
+        name: Annotated[str, Form(description="Contact name")], 
+        email: Annotated[str, Form(description="Contact email")]
+    ):
+        return {"message": f"Hello {name}, we'll contact you at {email}"}
+
+    # Create form data request
+    body = "name=John+Doe&email=john%40example.com"
+
+    event = make_request_event(
+        method="POST", 
+        path="/contact", 
+        body=body, 
+        headers={"content-type": "application/x-www-form-urlencoded"}
+    )
+
+    response = app.resolve(event, {})
+    assert response["statusCode"] == 200
+
+    response_body = json.loads(response["body"])
+    assert "John Doe" in response_body["message"]
+    assert "[email protected]" in response_body["message"]
+
+
+def test_file_parameter_basic():
+    """Test that File parameters are properly recognized (basic functionality)."""
+    app = APIGatewayRestResolver()
+
+    @app.post("/upload")
+    def upload_file(file: Annotated[bytes, File(description="File to upload")]):
+        return {"message": "File parameter recognized"}
+
+    # Test that the schema is generated correctly
+    schema = app.get_openapi_schema()
+    upload_op = schema.paths["/upload"].post
+
+    assert "multipart/form-data" in upload_op.requestBody.content
+
+    # Get the actual schema from components
+    multipart_content = upload_op.requestBody.content["multipart/form-data"]
+    ref_name = multipart_content.schema_.ref.split("/")[-1]
+    actual_schema = schema.components.schemas[ref_name]
+
+    assert "file" in actual_schema.properties
+    assert actual_schema.properties["file"].format == "binary"
+
+
+def test_mixed_file_and_form_schema():
+    """Test that mixed File and Form parameters generate correct schema."""
+    app = APIGatewayRestResolver()
+
+    @app.post("/upload")
+    def upload_with_metadata(
+        file: Annotated[bytes, File(description="File to upload")],
+        title: Annotated[str, Form(description="File title")],
+    ):
+        return {"message": "Mixed parameters recognized"}
+
+    # Test that the schema is generated correctly
+    schema = app.get_openapi_schema()
+    upload_op = schema.paths["/upload"].post
+
+    # Should use multipart/form-data when File parameters are present
+    assert "multipart/form-data" in upload_op.requestBody.content
+
+    # Get the actual schema from components
+    multipart_content = upload_op.requestBody.content["multipart/form-data"]
+    ref_name = multipart_content.schema_.ref.split("/")[-1]
+    actual_schema = schema.components.schemas[ref_name]
+
+    # Should have both file and form fields
+    assert "file" in actual_schema.properties
+    assert "title" in actual_schema.properties
+    assert actual_schema.properties["file"].format == "binary"
+    assert actual_schema.properties["title"].type == "string"