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

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

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