Lorsque Django gère un téléversement de fichier, les données du fichier aboutissent dans request.FILES (plus de détails sur l’objet request se trouvent dans la documentation des objets request et response). Ce document explique comment les fichiers sont stockés sur disque et en mémoire, et comment personnaliser le comportement par défaut.
Considérez un formulaire contenant un champ FileField:
forms.pyfrom django import forms\n\n\nclass UploadFileForm(forms.Form):\n title = forms.CharField(max_length=50)\n file = forms.FileField()\nUne vue gérant ce formulaire recevra les données de fichier dans request.FILES qui est un dictionnaire contenant une clé pour chaque FileField (ou ImageField, ou toute autre sous-classe de FileField) du formulaire. Ainsi, les données du formulaire ci-dessus seraient accessibles dans request.FILES['file'].
Notez que request.FILES ne contient les données que lorsque la méthode de requête est POST, qu’au moins un fichier est contenu dans l’envoi et que le formulaire``<form>`` à l’origine de la requête possède l’attribut enctype="multipart/form-data". Sinon, request.FILES est vide.
La plupart du temps, les données de fichiers seront transmises de request au formulaire comme expliqué dans Liaison de fichiers téléversés avec un formulaire. Voici ce que cela peut donner :
views.pyfrom django.http import HttpResponseRedirect\nfrom django.shortcuts import render\nfrom .forms import UploadFileForm\n\n# Imaginary function to handle an uploaded file.\nfrom somewhere import handle_uploaded_file\n\n\ndef upload_file(request):\n if request.method == "POST":\n form = UploadFileForm(request.POST, request.FILES)\n if form.is_valid():\n handle_uploaded_file(request.FILES["file"])\n return HttpResponseRedirect("/success/url/")\n else:\n form = UploadFileForm()\n return render(request, "upload.html", {"form": form})\nRemarquez que nous devons transmettre request.FILES au constructeur du formulaire ; c’est comme cela que les données de fichiers sont liées à un formulaire.
Voici une manière habituelle de gérer un fichier téléversé :
\ndef handle_uploaded_file(f):\n with open("some/file/name.txt", "wb+") as destination:\n for chunk in f.chunks():\n destination.write(chunk)\nEn bouclant sur UploadedFile.chunks() au lieu d’appeler read(), on peut s’assurer que les gros fichiers ne saturent pas la mémoire du système.
Il existe quelques autres méthodes et attributs accessibles pour les objets UploadedFile. Voir UploadedFile pour une référence complète.
Si vous enregistrez un fichier dans un Model contenant un champ FileField, l’emploi d’un formulaire ModelForm simplifie le processus. L’objet fichier sera enregistré à l’emplacement indiqué par le paramètre upload_to du champ FileField correspondant lors de l’appel à form.save():
from django.http import HttpResponseRedirect\nfrom django.shortcuts import render\nfrom .forms import ModelFormWithFileField\n\n\ndef upload_file(request):\n if request.method == "POST":\n form = ModelFormWithFileField(request.POST, request.FILES)\n if form.is_valid():\n # file is saved\n form.save()\n return HttpResponseRedirect("/success/url/")\n else:\n form = ModelFormWithFileField()\n return render(request, "upload.html", {"form": form})\nSi vous construisez manuellement un objet, vous pouvez attribuer l’objet fichier provenant de request.FILES au champ de fichier du modèle :
from django.http import HttpResponseRedirect\nfrom django.shortcuts import render\nfrom .forms import UploadFileForm\nfrom .models import ModelWithFileField\n\n\ndef upload_file(request):\n if request.method == "POST":\n form = UploadFileForm(request.POST, request.FILES)\n if form.is_valid():\n instance = ModelWithFileField(file_field=request.FILES["file"])\n instance.save()\n return HttpResponseRedirect("/success/url/")\n else:\n form = UploadFileForm()\n return render(request, "upload.html", {"form": form})\nSi vous construisez un objet manuellement en dehors d’une requête, vous pouvez attribuer un objet du genre File au champ FileField:
from django.core.management.base import BaseCommand\nfrom django.core.files.base import ContentFile\n\n\nclass MyCommand(BaseCommand):\n def handle(self, *args, **options):\n content_file = ContentFile(b"Hello world!", name="hello-world.txt")\n instance = ModelWithFileField(file_field=content_file)\n instance.save()\nSi vous souhaitez pouvoir téléverser plusieurs fichiers avec un seul champ de formulaire, créez une sous-classe du composant de champ et définissez son attribut de classe allow_multiple_selected à True.
Afin que de tels fichiers soient tous validés par votre formulaire (et que la valeur du champ les inclue tous), vous devrez aussi créer une sous-classe du champ FileField. Voir ci-dessous pour un exemple.
forms.pyfrom django import forms\n\n\nclass MultipleFileInput(forms.ClearableFileInput):\n allow_multiple_selected = True\n\n\nclass MultipleFileField(forms.FileField):\n def __init__(self, *args, **kwargs):\n kwargs.setdefault("widget", MultipleFileInput())\n super().__init__(*args, **kwargs)\n\n def clean(self, data, initial=None):\n single_file_clean = super().clean\n if isinstance(data, (list, tuple)):\n result = [single_file_clean(d, initial) for d in data]\n else:\n result = [single_file_clean(data, initial)]\n return result\n\n\nclass FileFieldForm(forms.Form):\n file_field = MultipleFileField()\nPuis surchargez la méthode form_valid() de votre sous-classe de FormView pour pouvoir gérer plusieurs fichiers reçus :
views.pyfrom django.views.generic.edit import FormView\nfrom .forms import FileFieldForm\n\n\nclass FileFieldFormView(FormView):\n form_class = FileFieldForm\n template_name = "upload.html" # Replace with your template.\n success_url = "..." # Replace with your URL or reverse().\n\n def form_valid(self, form):\n files = form.cleaned_data["file_field"]\n for f in files:\n ... # Do something with each file.\n return super().form_valid(form)\nLorsqu’un utilisateur envoie un fichier, Django transmet les données du fichier à un gestionnaire de téléversement, une petite classe qui gère les données du fichier reçu. Les gestionnaires de téléversement sont définis initialement dans le réglage FILE_UPLOAD_HANDLERS dont le contenu par défaut est :
[\n "django.core.files.uploadhandler.MemoryFileUploadHandler",\n "django.core.files.uploadhandler.TemporaryFileUploadHandler",\n]\nConjointement, MemoryFileUploadHandler et TemporaryFileUploadHandler définissent le comportement Django par défaut de téléversement de fichier en plaçant les petits fichiers en mémoire et les plus gros sur le disque.
Vous pouvez écrire des gestionnaires personnalisée qui modifient la façon de gérer les fichiers. Vous pourriez par exemple utiliser des gestionnaires personnalisés pour limiter la quantité de données par utilisateur, compresser les données à la volée, afficher des barres de progression ou même envoyer directement des données vers un autre emplacement de stockage sans les stocker localement. Voir Écriture de gestionnaires de téléversement personnalisés pour plus de détails sur la manière de personnaliser ou de remplacer complètement le comportement de téléversement.
\nAvant d’enregistrer des fichiers téléversés, les données doivent bien être stockées quelque part.
\nPar défaut, si un fichier téléversé est plus petit que 2,5 Mio, Django place la totalité du fichier en mémoire. Cela signifie que l’enregistrement du fichier correspond à une simple lecture en mémoire et à une écriture sur le disque, ce qui est très rapide.
\nCependant, si un fichier téléversé est trop gros, Django écrit le fichier dans un fichier temporaire stocké dans le répertoire des fichiers temporaires du système. Sur une plate-forme de type Unix, Django va en principe générer un fichier dont le chemin correspond à quelque chose comme /tmp/tmpzfp6I6.upload. Si le fichier est suffisamment gros, vous pouvez même voir la taille du fichier augmenter au fur et à mesure de son flux d’enregistrement vers le disque.
Ces paramètres spécifiques, 2,5 Mio, /tmp, etc. ne sont que des valeurs par défaut « raisonnables » qui peuvent être personnalisés comme expliqué dans la section suivante.
Certains réglages permettent de contrôler le comportement de téléversement de fichiers de Django. Voir Réglages de téléversement de fichiers pour plus de détails.
\nParfois, certaines vues ont besoin d’un comportement de téléversement différent. Dans ces situations, il est possible de surcharger les gestionnaires de téléversement par requête en modifiant request.upload_handlers. Par défaut, celle liste contient les gestionnaires de téléversement énumérés dans FILE_UPLOAD_HANDLERS, mais cette liste est modifiable comme n’importe quelle autre liste.
Par exemple, supposons que vous ayez écrit un gestionnaire ProgressBarUploadHandler qui renvoie des informations de progression de téléversement d’un composant AJAX quelconque. Voici comment ajouter ce gestionnaire à la liste des gestionnaires de téléversement :
request.upload_handlers.insert(0, ProgressBarUploadHandler(request))\nL’emploi de list.insert(), comme montré ci-dessus, assure que le gestionnaire de la barre de progression est placé au début de la liste. Comme les gestionnaires de téléversements sont exécutés l’un après l’autre, ce placement garantit que le gestionnaire s’exécute avant les gestionnaires par défaut, ce qui lui permet de suivre la progression durant l’entier du téléchargement.
Si vous vouliez totalement remplacer les gestionnaires de téléversement, il suffirait d’attribuer une nouvelle liste :
\nrequest.upload_handlers = [ProgressBarUploadHandler(request)]\n