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

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

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 раздел 5.3).

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 — это имя файла в формате Unicode, предоставленное браузером.

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

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

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

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

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

Параметр content_type_extra был добавлен.

FileUploadHandler.upload_complete() [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), чтобы вернуть новые структуры данных, подходящие для запроса непосредственно.