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

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

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).

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

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