FastAPI subida de archivos

FastAPI proporcionaFileyUploadFileDos formas de manejar la subida de archivos, que admiten subir archivos individuales y una mezcla de formularios y archivos.


Instalar dependencias

La subida de archivos también depende depython-multipart:

pip install python-multipart

Usar UploadFile

UploadFileEs la forma recomendada, ya que proporciona una interfaz más rica para acceder a la información del archivo:

Ejemplo

from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    # Atributos y métodos proporcionados por UploadFile
    return {
        "filename": file.filename,          # Nombre del archivo
        "content_type": file.content_type,  # Tipo MIME del archivo
        "size": file.size,                  # Tamaño del archivo (bytes)
    }

UploadFileAtributos y métodos:

Atributo/MétodoTipoDescripción
filenamestr | NoneNombre original del archivo subido
content_typestr | NoneTipo MIME del archivo (por ejemplo,image/png)
fileSpooledTemporaryFileObjeto similar a un archivo, permite leer el contenido del archivo
sizeint | NoneTamaño del archivo (bytes)
read()MétodoLee el contenido del archivo comobytes
write()MétodoEscribe contenido en el archivo
seek()MétodoMueve la posición del puntero del archivo
close()MétodoCierra el archivo

UploadFileUsa "SpooledTemporaryFile" para almacenar el contenido del archivo. Cuando el archivo es pequeño se guarda en memoria, y cuando es grande se escribe automáticamente al disco, por lo que es másbyteseficiente en memoria.


Usar File para recibir el contenido del archivo

FileLee directamente el contenido del archivo comobytes, adecuado para archivos pequeños:

Ejemplo

from fastapi import FastAPI, File

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File()):
    # file son los datos binarios originales del archivo
    return {"file_size": len(file)}

FileyUploadFileComparación:

Elemento de comparaciónFileUploadFile
Tipo de datobytesObjeto de archivo
Uso de memoriaTodo el archivo se carga en memoriaLos archivos grandes se escriben automáticamente al disco
Información del archivoNinguna (solo contenido)Tiene nombre, tipo y tamaño
Escenario de aplicaciónArchivos pequeñosArchivos grandes, escenarios que requieren información del archivo

Subida de archivos opcional

Usar valor predeterminadoNoneHace que la subida de archivos sea opcional:

Ejemplo

from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile | None = None):
    if not file:
        return {"message": "No se subió ningún archivo"}
    return {"filename": file.filename}

Subida de múltiples archivos

Usa una lista para recibir múltiples archivos:

Ejemplo

from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfiles/")
async def create_upload_files(files: list[UploadFile]):
    return {"filenames": [file.filename for file in files]}

Subida mixta de formularios y archivos

Puedes recibir datos de formulario y archivos en la misma ruta al mismo tiempo:

Ejemplo

from fastapi import FastAPI, File, UploadFile, Form

app = FastAPI()


@app.post("/items/")
async def create_item(
    # Campo de formulario
    name: str = Form(...),
    description: str | None = Form(None),
    # Subida de archivos
    file: UploadFile | None = None,
):
    result = {"name": name, "description": description}
    if file:
        result["filename"] = file.filename
    return result

Guardar el archivo subido

El siguiente ejemplo muestra cómo guardar el archivo subido en el disco:

Ejemplo

import shutil
from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    # Guarda el archivo subido en la ruta especificada
    with open(f"uploads/{file.filename}", "wb") as buffer:
        shutil.copyfileobj(file.file, buffer)
    return {"filename": file.filename, "message": "Archivo subido exitosamente"}

En proyectos reales, al subir archivos se debe tener en cuenta: 1) Validar el tipo y tamaño del archivo; 2) Usar nombres de archivo seguros (evitar ataques de path traversal); 3) Restringir los permisos del directorio de subida; 4) Para archivos grandes, usar procesamiento por flujo en lugar de leer todo de una vez.


Resumen

  • Se recomienda usarUploadFile, es más eficiente en memoria y proporciona información completa del archivo
  • FileAdecuado para escenarios de archivos pequeños, se lee directamente comobytes
  • Usarlist[UploadFile]Recibir subida de múltiples archivos
  • Formulario (Form) y archivo (UploadFile) se pueden usar en la misma ruta
  • Al subir archivos, presta atención a la seguridad: valida el tipo de archivo, usa nombres seguros y limita el tamaño
Otras extensiones