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

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

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), указанный браузером. И здесь лучше всего придерживаться правила «доверяй, но проверяй».

Примечание

Как и обычные файлы Python, загруженный файл можно читать построчно, перебирая его:

for line in uploadedfile:
    do_something_with(line)

Строки разделяются с использованием универсальных символов новой строки. Концом строки считаются следующие последовательности: символ конца строки в Unix '\n', символ конца строки в Windows '\r\n' и символ конца строки в старых системах Macintosh '\r'.

К подклассам 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. Не считывайте из input_data больше content_length байт.

boundary — разделитель MIME для этого запроса.

encoding — кодировка запроса.

Верните None, если хотите продолжить обработку загрузки, или кортеж из (POST, FILES), если хотите напрямую вернуть новые структуры данных, подходящие для запроса.

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/6.0/ref/files/uploads/