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

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

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 кусок начинается.

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

Верните 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.upload_interrupted()

Обратный вызов, сигнализирующий о прерывании загрузки, например, при закрытии браузера пользователем во время загрузки файла.

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