Subida de Archivos en FastAPI con UploadFile resuelve un problema frecuente en proyectos Python: Recibe archivos sin confiar en nombres, extensiones ni tipos enviados por el cliente. Esta guía explica el mecanismo, presenta un ejemplo ejecutable y marca los límites que evitan una implementación frágil.
Concepto y caso de uso
UploadFile usa un archivo temporal con spooling y ofrece interfaz asíncrona, por lo que es preferible a bytes cuando el archivo puede crecer. Los formularios usan multipart/form-data.
Para repasar los fundamentos relacionados, consulta también la guía de APIs con FastAPI. La integración es más simple cuando cada función recibe dependencias y datos explícitamente en lugar de depender de estado global.
Ejemplo práctico
from typing import Annotated
from fastapi import FastAPI, File, HTTPException, UploadFile
app = FastAPI()
@app.post("/files")
async def upload(file: UploadFile):
if file.content_type not in {"image/png", "image/jpeg"}:
raise HTTPException(415, "Unsupported media type")
data = await file.read(2_000_001)
if len(data) > 2_000_000:
raise HTTPException(413, "File too large")
return {"name": file.filename, "size": len(data)}Lee con un límite, genera un nombre interno y guarda fuera de directorios ejecutables. content_type es solo una pista; inspecciona la firma real cuando importe el formato.
Decisiones importantes
La elección correcta depende del contrato público, del volumen y del comportamiento ante fallos.
Considera concurrencia, entradas vacías y fallos parciales. Documenta cada límite que afecte a consumidores y usa nombres que expresen intención.
Errores frecuentes
El ejemplo mínimo no sustituye límites, manejo de errores y observabilidad. No conviertas el nombre original en una ruta, no aceptes la extensión como prueba ni cargues un cuerpo ilimitado en memoria. Añade análisis cuando el riesgo lo requiera.
Evita capturar excepciones sin contexto o devolver resultados parciales como si fueran completos. Un fallo explícito suele ser más seguro que datos silenciosamente incorrectos.
Cómo validar
Valida el comportamiento y no solo el camino feliz. Prueba un archivo válido, vacío, demasiado grande, un nombre con path traversal y contenido distinto del tipo declarado. Comprueba la limpieza temporal.