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

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

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