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

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

class UploadedFile

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

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

TemporaryUploadedFile.temporary_file_path()

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

class InMemoryUploadedFile

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

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

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

class MemoryFileUploadHandler

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

class TemporaryFileUploadHandler

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

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

class FileUploadHandler

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

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

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

FileUploadHandler.receive_data_chunk(raw_data, start)

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

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

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

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

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

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

FileUploadHandler.file_complete(file_size)

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

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

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

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()

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

FileUploadHandler.upload_interrupted()

Добавлено в Django 3.2.

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

FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding)

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

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

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

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

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

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

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