Загруженные файлы и обработчики загрузки ¶
Загруженные файлы ¶
-
класс
UploadedFile
¶
Во время загрузки файлов фактические данные файла сохраняются в request.FILES
. Каждая запись в этом словаре является
UploadedFile
объектом (или подклассом) - оболочкой для загруженного файла. Обычно вы используете один из этих методов для доступа к загруженному контенту:
-
UploadedFile.
read
() ¶ Прочтите все загруженные данные из файла. Будьте осторожны с этим методом: если загруженный файл огромен, он может перегрузить вашу систему, если вы попытаетесь прочитать его в памяти. Вы, вероятно, захотите использовать
chunks()
вместо этого; см. ниже.
-
UploadedFile.
multiple_chunks
( chunk_size = Нет ) ¶ Возвращает,
True
если загруженный файл достаточно велик, чтобы его можно было прочитать несколькими фрагментами. По умолчанию это будет любой файл размером более 2,5 мегабайт, но это можно настроить; см. ниже.
-
UploadedFile.
chunks
( chunk_size = Нет ) ¶ Генератор, возвращающий фрагменты файла. Если
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
включают:
-
класс
TemporaryUploadedFile
¶ Файл, загруженный во временное расположение (например, из потока на диск). Этот класс используется классом
TemporaryFileUploadHandler
. Помимо методов изUploadedFile
, у него есть еще один метод:
-
TemporaryUploadedFile.
temporary_file_path
() ¶ Возвращает полный путь к временному загруженному файлу.
-
класс
InMemoryUploadedFile
¶ Файл, загруженный в память (т. Е. Из потока в память). Этот класс используется классом
MemoryFileUploadHandler
.
Встроенные обработчики загрузки ¶
Вместе MemoryFileUploadHandler
и
TemporaryFileUploadHandler
обеспечить поведение загрузки файла по умолчанию Джанго чтения небольших файлов в память , а крупные на диск. Они расположены в django.core.files.uploadhandler
.
-
класс
MemoryFileUploadHandler
¶
Обработчик загрузки файлов для потоковой загрузки в память (используется для небольших файлов).
-
класс
TemporaryFileUploadHandler
¶
Загрузите обработчик, который передает данные во временный файл, используя
TemporaryUploadedFile
.
Написание пользовательских обработчиков загрузки ¶
-
класс
FileUploadHandler
¶
Все обработчики загрузки файлов должны быть подклассами
django.core.files.uploadhandler.FileUploadHandler
. Вы можете определить обработчики загрузки где угодно.
Обязательные методы ¶
Пользовательские обработчики загрузки файлов должны определять следующие методы:
-
FileUploadHandler.
receive_data_chunk
( raw_data , начало ) ¶ Получает «кусок» данных из загруженного файла.
raw_data
это строка байтов, содержащая загруженные данные.start
это позиция в файле, с которойraw_data
начинается этот чанк.Возвращаемые вами данные будут переданы в
receive_data_chunk
методы последующих обработчиков загрузки . Таким образом, один обработчик может быть «фильтром» для других обработчиков.Возврат
None
отreceive_data_chunk
короткого замыкания остальных обработчиков загружаемых из получать этот кусок. Это полезно, если вы сами храните загруженные данные и не хотите, чтобы будущие обработчики хранили их копию.Если вы создадите исключение
StopUpload
илиSkipFile
исключение, загрузка будет прервана или файл будет полностью пропущен.
-
FileUploadHandler.
file_complete
( размер_файла ) ¶ Вызывается, когда загрузка файла завершена.
Обработчик должен вернуть
UploadedFile
объект, который будет храниться вrequest.FILES
. Обработчики также могут возвращаться,None
чтобы указать, чтоUploadedFile
объект должен быть получен от последующих обработчиков загрузки.
Необязательные методы ¶
Пользовательские обработчики загрузки также могут определять любой из следующих дополнительных методов или атрибутов:
-
FileUploadHandler.
chunk_size
¶ Размер в байтах «кусков», которые Django должен сохранить в памяти и передать обработчику. То есть этот атрибут контролирует размер загружаемых фрагментов
FileUploadHandler.receive_data_chunk
.Для максимальной производительности размеры фрагментов должны делиться на
4
2 ГБ (2 31 байт) и не должны превышать их . Когда несколько обработчиков предоставляют несколько размеров фрагментов, Django будет использовать наименьший размер фрагментов, определенный любым обработчиком.По умолчанию 64 * 2 10 байтов или 64 КБ.
-
FileUploadHandler.
new_file
( имя_поля , имя_файла , тип_содержимого , длина_содержимого , кодировка , тип_содержимого_экстра ) ¶ Обратный вызов, сигнализирующий о начале загрузки нового файла. Это вызывается до того, как какие-либо данные будут переданы в какие-либо обработчики загрузки.
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
( входные_данные , МЕТА , длина_содержимого , граница , кодировка ) ¶ Позволяет обработчику полностью отменять синтаксический анализ необработанного ввода HTTP.
input_data
представляет собой файловый объект, поддерживающийread()
-ing.META
тот же объект, что иrequest.META
.content_length
длина данных вinput_data
. Не читайте большеcontent_length
байтов изinput_data
.boundary
это граница MIME для этого запроса.encoding
это кодировка запроса.Верните,
None
если вы хотите, чтобы обработка загрузки продолжалась, или кортеж, если вы хотите напрямую вернуть новые структуры данных, подходящие для запроса.(POST, FILES)