Skip to main content

上传的文件和上传处理程序

已上传文件

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/plainapplication/pdf)。与用户提供的任何数据一样,您不应该相信上传的文件实际上是此类型。您仍然需要验证该文件包含内容类型标题声明的内容 - “信任但验证”。

UploadedFile.content_type_extra

包含传递给 content-type 标头的额外参数的字典。这通常由服务(例如Google App Engine)提供,代表您拦截和处理文件上传。因此,您的处理程序可能不会收到上传的文件内容,而是一个URL或其他指向文件的指针。 (见 RFC 2388 第5.3节)。

UploadedFile.charset

对于 text/* 内容类型,由浏览器提供的字符集(即 utf8)。再次,“信任,但验证”是这里的最好的政策。

注解

与常规Python文件一样,您可以通过遍历上传的文件逐行读取文件:

for line in uploadedfile:
    do_something_with(line)

使用 universal newlines 分割线。以下被认为是结束行:Unix行尾约定 '\n',Windows约定 '\r\n' 和旧Macintosh约定 '\r'

UploadedFile 的子类包括:

class TemporaryUploadedFile[源代码]

上传到临时位置(即流到磁盘)的文件。这个类由 TemporaryFileUploadHandler 使用。除了 UploadedFile 的方法外,还有一个额外的方法:

TemporaryUploadedFile.temporary_file_path()[源代码]

返回临时上传文件的完整路径。

class InMemoryUploadedFile[源代码]

上传到存储器中的文件(即流到存储器)。这个类由 MemoryFileUploadHandler 使用。

内置上传处理程序

MemoryFileUploadHandlerTemporaryFileUploadHandler 共同提供了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 方法。这样,一个处理程序可以是其他处理程序的“过滤器”。

receive_data_chunk 返回 None 以短路剩余的上传处理程序从获取此块。如果您自己存储上传的数据,并且不希望未来的处理程序存储数据副本,那么这是非常有用的。

如果引发 StopUploadSkipFile 异常,上传将中止或文件将被完全跳过。

FileUploadHandler.file_complete(file_size)[源代码]

文件完成上传时调用。

处理程序应返回将存储在 request.FILES 中的 UploadedFile 对象。处理程序也可以返回 None 以指示 UploadedFile 对象应来自后续的上传处理程序。

可选方法

自定义上传处理程序还可以定义以下任意可选方法或属性:

FileUploadHandler.chunk_size

Django应该存储到内存中并送入处理程序的“块”的大小(以字节为单位)。也就是说,此属性控制送入 FileUploadHandler.receive_data_chunk 的块的大小。

为了获得最佳性能,块大小应该可以被 4 整除,并且大小不能超过2 GB(2 31 字节)。当有多个处理程序提供多个块大小时,Django将使用任何处理程序定义的最小块大小。

默认值为64 * 2 10 字节,或64 KB。

FileUploadHandler.new_file(field_name, file_name, content_type, content_length, charset, content_type_extra)[源代码]

回调信号表示新文件上传正在开始。这在任何数据被馈送到任何上传处理程序之前被调用。

field_name 是文件 <input> 字段的字符串名称。

file_name 是浏览器提供的unicode文件名。

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.handle_raw_input(input_data, META, content_length, boundary, encoding)[源代码]

允许处理程序完全覆盖原始HTTP输入的解析。

input_data 是一个支持 read() 的类文件对象。

META 是与 request.META 相同的对象。

content_lengthinput_data 中数据的长度。不要从 input_data 中读取超过 content_length 字节。

boundary 是此请求的MIME边界。

encoding 是请求的编码。

如果希望继续上传处理,则返回 None,如果要直接返回适合请求的新数据结构,则返回 (POST, FILES) 的元组。