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

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

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

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