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

При обработке 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})

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

Если вы хотите загрузить несколько файлов, используя одно поле формы, установите атрибут 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 FileFieldView(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