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

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

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) предоставленная браузером. Опять же, «доверяйте, но проверяйте» — лучшая политика.

for line in uploadedfile:
    do_something_with(line)

Подклассы 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>.

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

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

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

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

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

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

FileUploadHandler.upload_complete()

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

FileUploadHandler.upload_interrupted()

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

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

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

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

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

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

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

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

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