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

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

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

UploadedFile.charset: Для типов содержимого text/* кодировка символов (т.е. utf8), предоставленная браузером. Опять же, «доверяйте, но проверяйте» — лучшая политика.

Примечание

Как и обычные файлы Python, вы можете читать файл построчно, перебирая загруженный файл:

for line in uploadedfile:
    do_something_with(line)

Строки разделяются с использованием универсальных символов новой строки. Признаются следующие символы конца строки: соглашение о конце строки Unix '\n', соглашение о конце строки Windows '\r\n' и старое соглашение о конце строки Macintosh '\r'.

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

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/5.2/ref/files/uploads/