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

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

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 часть.

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

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