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

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

class UploadedFile [source]

При загрузке файлов фактические данные файла хранятся в 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 [source]

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

TemporaryUploadedFile.temporary_file_path() [source]

Возвращает полный путь к временному загруженному файлу.

class InMemoryUploadedFile [source]

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

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

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

class MemoryFileUploadHandler [source]

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

class TemporaryFileUploadHandler [source]

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

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

class FileUploadHandler [source]

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

Обязательные методы

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

FileUploadHandler.receive_data_chunk(raw_data, start) [source]

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

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

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

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

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

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

FileUploadHandler.file_complete(file_size) [source]

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

Обработчик должен вернуть объект 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) [source]

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

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() [source]

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

FileUploadHandler.upload_interrupted() [source]

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

FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding) [source]

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

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

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

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

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

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

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