3.2
5.0
6.1
Версия документации: 3.1

Загруженные файлы и обработчики загрузки¶

Загруженные файлы¶

class UploadedFile¶

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

UploadedFile.read()¶: Считайте все загруженные данные из файла. Будьте осторожны с этим методом: если загруженный файл огромен, он может перегрузить вашу систему, если вы попытаетесь прочитать его в память. Вместо этого вы, вероятно, захотите использовать chunks(); см. ниже.

UploadedFile.multiple_chunks(chunk_size=None)¶: Возвращает True, если загруженный файл достаточно велик и требует чтения несколькими частями. По умолчанию это будет любой файл размером более 2,5 мегабайт, но это можно настроить; см. ниже.

UploadedFile.chunks(chunk_size=None)¶

Генератор, возвращающий фрагменты файла. Если multiple_chunks() имеет значение True, вам следует использовать этот метод в цикле вместо read().

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

Вот некоторые полезные атрибуты UploadedFile:

UploadedFile.name¶: Имя загруженного файла (например, my_file.txt).

UploadedFile.size¶: Размер, в байтах, загруженного файла.

UploadedFile.content_type¶: Заголовок типа контента, загруженный вместе с файлом (например, text/plain или application/pdf). Как и любые данные, предоставленные пользователем, не следует доверять тому, что загруженный файл на самом деле относится к этому типу. Вам все равно необходимо будет убедиться, что файл содержит содержимое, заявленное в заголовке типа содержимого — «доверяй, но проверяй».

UploadedFile.content_type_extra¶: Словарь, содержащий дополнительные параметры, передаваемые в заголовок content-type. Обычно это обеспечивается такими службами, как Google App Engine, которые перехватывают и обрабатывают загрузку файлов от вашего имени. В результате ваш обработчик может получить не загруженное содержимое файла, а URL-адрес или другой указатель на файл (см. RFC 2388).

UploadedFile.charset¶: Для типов контента text/* — набор символов (т. е. utf8), предоставленный браузером. Опять же, «доверяй, но проверяй» — лучшая политика здесь.

Примечание

Как и в случае с обычными файлами Python, вы можете читать файл построчно, перебирая загруженный файл:

for line in uploadedfile:
    do_something_with(line)

Строки разделяются с помощью универсальных символов новой строки. Следующие символы считаются завершением строки: соглашение о конце строки Unix '\n', соглашение Windows '\r\n' и старое соглашение Macintosh '\r'.

Подклассы UploadedFile включают в себя:

class TemporaryUploadedFile¶: Файл, загруженный во временное расположение (т. е. потоковая передача на диск). Этот класс используется TemporaryFileUploadHandler. Помимо методов из UploadedFile, у него есть еще один метод:

TemporaryUploadedFile.temporary_file_path()¶: Возвращает полный путь к временному загруженному файлу.

class InMemoryUploadedFile¶: Файл, загруженный в память (т.е. поток в память). Этот класс используется MemoryFileUploadHandler.

Встроенные обработчики загрузки¶

Вместе MemoryFileUploadHandler и TemporaryFileUploadHandler обеспечивают стандартное поведение загрузки файлов Django: чтение небольших файлов в память и больших на диск. Они расположены в django.core.files.uploadhandler.

class MemoryFileUploadHandler¶

Обработчик загрузки файлов для потоковой загрузки в память (используется для небольших файлов).

class TemporaryFileUploadHandler¶

Обработчик загрузки, который передает данные во временный файл, используя TemporaryUploadedFile.

Написание пользовательских обработчиков загрузки¶

class FileUploadHandler¶

Все обработчики загрузки файлов должны быть подклассами django.core.files.uploadhandler.FileUploadHandler. Вы можете определить обработчики загрузки где угодно.

Требуемые методы¶

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

FileUploadHandler.receive_data_chunk(raw_data, start)¶

Получает «кусок» данных из загруженного файла.

raw_data — это строка байтов, содержащая загруженные данные.

start — это позиция в файле, с которой начинается этот фрагмент raw_data.

Возвращаемые вами данные будут переданы в методы receive_data_chunk последующих обработчиков загрузки. Таким образом, один обработчик может быть «фильтром» для других обработчиков.

Верните None из receive_data_chunk, чтобы отключить оставшиеся обработчики загрузки от получения этого фрагмента. Это полезно, если вы сами храните загруженные данные и не хотите, чтобы будущие обработчики сохраняли копию данных.

Если вы вызовете исключение StopUpload или SkipFile, загрузка прервется или файл будет полностью пропущен.

FileUploadHandler.file_complete(file_size)¶

Вызывается, когда загрузка файла завершена.

Обработчик должен вернуть объект UploadedFile, который будет сохранен в request.FILES. Обработчики также могут возвращать None, чтобы указать, что объект UploadedFile должен быть получен от последующих обработчиков загрузки.

Дополнительные методы¶

Пользовательские обработчики загрузки также могут определять любые из следующих дополнительных методов или атрибутов:

FileUploadHandler.chunk_size¶

Размер «кусков» в байтах, которые Django должен сохранить в памяти и передать в обработчик. То есть этот атрибут управляет размером фрагментов, передаваемых в FileUploadHandler.receive_data_chunk.

Для максимальной производительности размеры фрагментов должны быть кратны 4 и не должны превышать 2 ГБ (2³¹ байта). Если несколько обработчиков предоставляют фрагменты нескольких размеров, Django будет использовать наименьший размер фрагмента, определенный любым обработчиком.

Значение по умолчанию — 64*2¹⁰ байт или 64 КБ.

FileUploadHandler.new_file(field_name, file_name, content_type, content_length, charset, content_type_extra)¶

Обратный вызов, сигнализирующий о начале загрузки нового файла. Это вызывается до того, как какие-либо данные будут переданы обработчикам загрузки.

field_name — это строковое имя поля <input> файла.

имя_файла — это имя файла, предоставленное браузером.

content_type — это MIME-тип, предоставляемый браузером. Например. 'изображение/jpeg'.

content_length — это длина изображения, заданная браузером. Иногда это не будет предоставлено и будет «Нет».

charset — это набор символов (например, utf8), заданный браузером. Как и content_length, иногда оно не предоставляется.

content_type_extra — это дополнительная информация о файле из заголовка content-type. См. UploadedFile.content_type_extra.

Этот метод может вызвать исключение StopFutureHandlers, чтобы предотвратить обработку этого файла будущими обработчиками.

FileUploadHandler.upload_complete()¶: Обратный вызов, сигнализирующий о завершении всей загрузки (всех файлов).

FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding)¶

Позволяет обработчику полностью переопределить анализ необработанного ввода HTTP.

input_data — это файлоподобный объект, который поддерживает read().

META — это тот же объект, что и request.META.

content_length — это длина данных в input_data. Не читайте из input_data более байтов content_length.

boundary — это граница MIME для этого запроса.

encoding — это кодировка запроса.

Верните None, если вы хотите, чтобы обработка загрузки продолжалась, или кортеж (POST, FILES), если вы хотите напрямую вернуть новые структуры данных, подходящие для запроса.

API хранилища файлов

Формы

Загруженные файлы и обработчики загрузки¶