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

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

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 фрагмент.

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

Верните 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, чтобы предотвратить обработку этого файла последующими обработчиками.

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