Загрузка файлов

Когда Django обрабатывает загрузку файла, данные файла размещаются в request.FILES (подробнее об объекте request см. документацию по объектам запроса и ответа). В этом документе объясняется, как файлы хранятся на диске и в памяти, а также как настроить поведение по умолчанию.

Базовая загрузка файлов

Рассмотрим форму, содержащую FileField:

from django import forms


class UploadFileForm(forms.Form):
    title = forms.CharField(max_length=50)
    file = forms.FileField()

Представление, обрабатывающее эту форму, получит данные файла в request.FILES, который является словарем, содержащим ключ для каждого FileField (или ImageField, или другого подкласса FileField) в форме. Таким образом, данные из указанной выше формы будут доступны как request.FILES['file'].

Обратите внимание, что request.FILES будет содержать данные только в том случае, если метод запроса был POST, был отправлен хотя бы один поле файла, и <form> отправивший запрос имеет атрибут enctype="multipart/form-data". В противном случае, request.FILES будет пустым.

В большинстве случаев вы передадите данные файла из request в форму, как описано в Связывание загружаемых файлов с формой. Это будет выглядеть примерно так:

from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import UploadFileForm

# Imaginary function to handle an uploaded file.
from somewhere import handle_uploaded_file


def upload_file(request):
    if request.method == "POST":
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            handle_uploaded_file(request.FILES["file"])
            return HttpResponseRedirect("/success/url/")
    else:
        form = UploadFileForm()
    return render(request, "upload.html", {"form": form})

Обратите внимание, что мы должны передать request.FILES в конструктор формы; таким образом данные файла связываются с формой.

Вот распространенный способ обработки загруженного файла:

def handle_uploaded_file(f):
    with open("some/file/name.txt", "wb+") as destination:
        for chunk in f.chunks():
            destination.write(chunk)

Использование цикла по UploadedFile.chunks() вместо read() гарантирует, что большие файлы не перегрузят оперативную память вашей системы.

Доступны несколько других методов и атрибутов для объектов UploadedFile; см. UploadedFile для полной справки.

Обработка загруженных файлов с моделью

Если вы сохраняете файл в Model с FileField, использование ModelForm значительно упрощает этот процесс. Объект файла будет сохранен в указанном месте аргументом upload_to соответствующего FileField при вызове form.save();

from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import ModelFormWithFileField


def upload_file(request):
    if request.method == "POST":
        form = ModelFormWithFileField(request.POST, request.FILES)
        if form.is_valid():
            # file is saved
            form.save()
            return HttpResponseRedirect("/success/url/")
    else:
        form = ModelFormWithFileField()
    return render(request, "upload.html", {"form": form})

Если вы создаете объект вручную, вы можете присвоить объект файла из request.FILES полю файла в модели:

from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import UploadFileForm
from .models import ModelWithFileField


def upload_file(request):
    if request.method == "POST":
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            instance = ModelWithFileField(file_field=request.FILES["file"])
            instance.save()
            return HttpResponseRedirect("/success/url/")
    else:
        form = UploadFileForm()
    return render(request, "upload.html", {"form": form})

Если вы создаете объект вручную вне запроса, вы можете присвоить объект типа File полю FileField:

from django.core.management.base import BaseCommand
from django.core.files.base import ContentFile


class MyCommand(BaseCommand):
    def handle(self, *args, **options):
        content_file = ContentFile(b"Hello world!", name="hello-world.txt")
        instance = ModelWithFileField(file_field=content_file)
        instance.save()

Загрузка нескольких файлов

Если вы хотите загружать несколько файлов с помощью одного поля формы, установите атрибут multiple виджета поля:

from django import forms


class FileFieldForm(forms.Form):
    file_field = forms.FileField(
        widget=forms.ClearableFileInput(attrs={"multiple": True})
    )

Затем переопределите метод post вашего подкласса FormView для обработки многократной загрузки файлов:

from django.views.generic.edit import FormView
from .forms import FileFieldForm


class FileFieldFormView(FormView):
    form_class = FileFieldForm
    template_name = "upload.html"  # Replace with your template.
    success_url = "..."  # Replace with your URL or reverse().

    def post(self, request, *args, **kwargs):
        form_class = self.get_form_class()
        form = self.get_form(form_class)
        files = request.FILES.getlist("file_field")
        if form.is_valid():
            for f in files:
                ...  # Do something with each file.
            return self.form_valid(form)
        else:
            return self.form_invalid(form)

Обработчики загрузки

Когда пользователь загружает файл, Django передает данные файла в обработчик загрузки — небольшой класс, который обрабатывает данные файла во время загрузки. Обработчики загрузки изначально определены в настройке FILE_UPLOAD_HANDLERS, которая по умолчанию:

[
    "django.core.files.uploadhandler.MemoryFileUploadHandler",
    "django.core.files.uploadhandler.TemporaryFileUploadHandler",
]

Вместе MemoryFileUploadHandler и TemporaryFileUploadHandler обеспечивают поведение загрузки файлов по умолчанию в Django, читая небольшие файлы в память, а большие — на диск.

Вы можете написать пользовательские обработчики, которые изменят способ обработки файлов Django. Например, вы можете использовать пользовательские обработчики для соблюдения квот на уровне пользователя, сжатия данных на лету, отображения индикаторов прогресса и даже отправки данных в другое место хранения напрямую, без локального сохранения. Подробности о том, как настроить или полностью заменить поведение загрузки, см. в разделе Создание пользовательских обработчиков загрузки.

Где хранятся загруженные данные

Перед сохранением загруженных файлов данные должны быть сохранены где-то.

По умолчанию, если загружаемый файл меньше 2,5 мегабайт, Django будет хранить все содержимое загрузки в оперативной памяти. Это означает, что сохранение файла включает только чтение из памяти и запись на диск, поэтому это очень быстро.

Однако, если загружаемый файл слишком большой, Django запишет загруженный файл во временный файл, хранящийся в временном каталоге вашей системы. На платформе, подобной Unix, это означает, что Django может создать файл с именем, подобным /tmp/tmpzfp6I6.upload. Если загрузка достаточно большая, вы можете наблюдать, как размер этого файла увеличивается по мере того, как Django передает данные на диск.

Эти особенности — 2,5 мегабайта; /tmp; и т. д. — являются «разумными значениями по умолчанию», которые можно настроить, как описано в следующем разделе.

Изменение поведения обработчика загрузки

Существуют несколько настроек, которые контролируют поведение загрузки файлов в Django. Подробности см. в разделе Настройки загрузки файлов.

Изменение обработчиков загрузки на лету

Иногда для определенных представлений требуется разное поведение загрузки. В таких случаях вы можете переопределить обработчики загрузки на уровне запроса, изменив request.upload_handlers. По умолчанию этот список будет содержать обработчики загрузки, заданные в FILE_UPLOAD_HANDLERS, но вы можете изменить список как любой другой список.

Например, предположим, что вы написали ProgressBarUploadHandler для отображения обратной связи о прогрессе загрузки в какой-то виджет AJAX. Вы бы добавили этот обработчик в свой список обработчиков загрузки следующим образом:

request.upload_handlers.insert(0, ProgressBarUploadHandler(request))

В этом случае, скорее всего, вы захотите использовать list.insert() (а не append()), потому что обработчик прогресса должен работать до других обработчиков. Помните, что обработчики загрузки обрабатываются в порядке их следования.

Если вы хотите полностью заменить обработчики загрузки, вы можете присвоить новый список:

request.upload_handlers = [ProgressBarUploadHandler(request)]

from django.views.decorators.csrf import csrf_exempt, csrf_protect


@csrf_exempt
def upload_file_view(request):
    request.upload_handlers.insert(0, ProgressBarUploadHandler(request))
    return _upload_file_view(request)


@csrf_protect
def _upload_file_view(request):
    ...  # Process request

from django.utils.decorators import method_decorator
from django.views import View
from django.views.decorators.csrf import csrf_exempt, csrf_protect


@method_decorator(csrf_exempt, name="dispatch")
class UploadFileView(View):
    def setup(self, request, *args, **kwargs):
        request.upload_handlers.insert(0, ProgressBarUploadHandler(request))
        super().setup(request, *args, **kwargs)

    @method_decorator(csrf_protect)
    def post(self, request, *args, **kwargs):
        ...  # Process request