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

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

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 раздел 5.3).

UploadedFile.charset

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

for line in uploadedfile:
    do_something_with(line)

Подклассы 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 — это имя файла в формате Unicode, предоставленное браузером.

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