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

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

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