File Uploads

Execution Workflow

1. Decide whether the endpoint truly needs multipart file transport.
2. Choose the input shape: single UploadFile, typed multipart model, dict[str, UploadFile], or list[UploadFile].
3. Declare multipart explicitly with Body(media_type=RequestEncodingType.MULTI_PART).
4. Validate filename, content type, size expectations, and field layout before expensive processing.
5. Stream or hand off large files to storage/services without unbounded memory use.
6. Keep upload parsing and validation at the transport edge; move persistence and scanning into services.

Core Rules

• Treat every uploaded file as untrusted input.
• Type uploads explicitly with UploadFile or multipart container models.
• Prefer typed multipart models when field names and structure are known.
• Use dict[str, UploadFile] or list[UploadFile] only when the field layout is dynamic or intentionally loose.
• Keep request size limits explicit with request_max_body_size when defaults are not sufficient.
• Avoid reading whole files into memory unless the endpoint contract is small and bounded.