Téléversement de fichiers avec FastAPI

FastAPI fournitFileetUploadFileDeux façons de gérer les téléversements de fichiers, prenant en charge les téléversements de fichiers autonomes et les téléversements mixtes de formulaire et de fichier.


Installer les dépendances

Le téléversement de fichiers dépend également depython-multipart:

pip install python-multipart

Utilisation de UploadFile

UploadFileest l'approche recommandée, elle fournit une interface plus riche pour accéder aux informations du fichier :

Exemple

from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    # Propriétés et méthodes fournies par UploadFile
    return {
        "filename": file.filename,          # Nom du fichier
        "content_type": file.content_type,  # Type MIME du fichier
        "size": file.size,                  # Taille du fichier (bytes)
    }

UploadFilepropriétés et méthodes :

Attributs/MéthodesTypeDescription
filenamestr | NoneLe nom de fichier d'origine du fichier téléversé
content_typestr | NoneLe type MIME du fichier (par ex.image/png)
fileSpooledTemporaryFileUn objet de type fichier qui peut lire le contenu du fichier
sizeint | NoneTaille du fichier (bytes)
read()MéthodesLire le contenu du fichier en tant quebytes
write()MéthodesÉcrire le contenu dans un fichier
seek()MéthodesDéplacer la position du pointeur de fichier
close()MéthodesFermer un fichier

UploadFileUtilise "SpooledTemporaryFile" pour stocker le contenu du fichier. Lorsque le fichier est petit, il est conservé en mémoire ; lorsqu'il est volumineux, il est automatiquement écrit sur le disque, donc il est plusbytesPlus économe en mémoire.


Utiliser File pour recevoir le contenu du fichier

FileLire directement le contenu du fichier en tant quebytes, adapté aux petits fichiers :

Exemple

from fastapi import FastAPI, File

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File()):
    # file correspond aux données brutes en octets du fichier
    return {"file_size": len(file)}

FileetUploadFilecomparaison :

Élément de comparaisonFileUploadFile
Types de donnéesbytesObjet File
Utilisation de la mémoireCharger l'intégralité du fichier en mémoireLes fichiers volumineux sont automatiquement écrits sur le disque
Informations sur le fichierAucune (uniquement le contenu)Possède un nom de fichier, un type, une taille
Scénarios applicablespetit fichierScénarios avec des fichiers volumineux ou nécessitant des informations sur le fichier

Téléversement de fichier facultatif

Utiliser la valeur par défautNoneRendre le téléversement de fichier facultatif :

Exemple

from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile | None = Aucune):
    if not file:
        return {"message": "Aucun fichier téléversé"}
    return {"filename": file.filename}

Téléversement de plusieurs fichiers

Utilisez une liste pour recevoir plusieurs fichiers :

Exemple

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]}

Téléversement mixte de formulaire et de fichier

Vous pouvez recevoir des données de formulaire et des fichiers simultanément dans la même route :

Exemple

from fastapi import FastAPI, File, UploadFile, Form

app = FastAPI()


@app.post("/items/")
async def create_item(
    # Champs de formulaire
    name: str = Form(...),
    description: str | None = Form(None),
    # Téléversement de fichier
    file: UploadFile | None = None,
):
    result = {"name": name, "description": description}
    if file:
        result["filename"] = file.filename
    return result

Enregistrer le fichier téléversé

L'exemple suivant montre comment enregistrer les fichiers téléversés sur le disque :

Exemple

import shutil
from fastapi import FastAPI, UploadFile

app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    # Enregistrer le fichier téléversé dans le chemin spécifié
    with open(f"uploads/{file.filename}", "wb") as buffer:
        shutil.copyfileobj(file.file, buffer)
    return {"filename": file.filename, "message": "Fichier téléversé avec succès"}

Dans les projets réels, lors du téléversement de fichiers, notez : 1) Validez le type et la taille du fichier ; 2) Utilisez des noms de fichiers sûrs (évitez les attaques par traversée de chemin) ; 3) Restreignez les permissions sur le répertoire de téléversement ; 4) Pour les fichiers volumineux, utilisez le streaming au lieu de tout lire d'un coup.


Résumé

  • RecommandéUploadFile, cela économise davantage de mémoire et fournit des informations riches sur le fichier
  • FileAdapté aux scénarios de petits fichiers, lu directement commebytes
  • Utilisationlist[UploadFile]Recevoir plusieurs téléversements de fichiers
  • formulaire (Form) et fichier (UploadFile) peut être utilisé dans la même route
  • Faites attention à la sécurité lors du téléversement de fichiers : validez les types de fichiers, utilisez des noms de fichiers sûrs et limitez les tailles
autres extensions