Uploaded Files and Upload Handlers

Uploaded files

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

UploadedFile.content_type_extra
Django 1.7中的新功能。

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

UploadedFile.charset

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

注意

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

for line in uploadedfile:
    do_something_with(line)

使用通用换行符分割线。以下被识别为结束行:Unix行尾约定'\n',Windows约定'\r\n'约定'\r'

在Django 1.8中更改:

以前的行仅在Unix行尾'\n'上拆分。

UploadedFile的子类包括:

class TemporaryUploadedFile[source]

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

TemporaryUploadedFile.temporary_file_path()[source]

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

class InMemoryUploadedFile[source]

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

Built-in upload handlers

MemoryFileUploadHandlerTemporaryFileUploadHandler一起提供Django的默认文件上传行为,将小文件读入内存,大文件读入磁盘。它们位于django.core.files.uploadhandler中。

class MemoryFileUploadHandler[source]

文件上传处理程序将流上传到内存(用于小文件)。

class TemporaryFileUploadHandler[source]

使用TemporaryUploadedFile将数据流传输到临时文件的上传处理程序。

Writing custom upload handlers

class FileUploadHandler[source]

所有文件上传处理程序应该是django.core.files.uploadhandler.FileUploadHandler的子类。你可以定义上传处理程序,无论你想要什么。

Required methods

自定义文件上传处理程序必须定义以下方法:

FileUploadHandler.receive_data_chunk(raw_data, start)[source]

从文件上传接收一个“数据块”的数据。

raw_data是包含上传数据的字节字符串。

start是文件中raw_data块开始的位置。

您返回的数据将送入后续的上传处理程序的receive_data_chunk方法。这样,一个处理程序可以是用于其他处理程序的“过滤器”。

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

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

FileUploadHandler.file_complete(file_size)[source]

文件完成上传时调用。

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

Optional methods

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

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)[source]

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

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异常,以防止未来的处理程序处理此文件。

Django 1.7中的新功能:

已添加content_type_extra参数。

FileUploadHandler.upload_complete()[source]

回调信号表示整个上传(所有文件)已完成。

FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding)[source]

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

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

METArequest.META具有相同的对象。

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

boundary是此请求的MIME边界。

encoding是请求的编码。

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