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

Завантаженi файли

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

Заголовок 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)

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

Подклассы 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 ГБ (231 байт). При наличии нескольких размеров чанков, предоставляемых несколькими обработчиками, Django будет использовать наименьший размер чанка, определенный любым обработчиком.

По умолчанию это 64*210 байт, или 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()[исходный код]

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

FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding)[исходный код]

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

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

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

content_length - это длина данных в input_data. Не считывайте из content_length байт больше, чем input_data.

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

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

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

API для хранения файлов
Формы
Вернуться на верх