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

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

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

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

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