上传的文件和上传处理程序¶
上传的文件¶
-
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
方法中。通过这种方式,一个处理程序可以成为其他处理程序的 “过滤器”。从
receive_data_chunk
中返回None
,以短路剩余的上传处理程序。如果你自己存储上传的数据,并且不希望后续的处理程序存储数据的副本,这很有用。如果引发一个
StopUpload
或SkipFile
异常,上传将被中止或文件将被完全跳过。
-
FileUploadHandler.
file_complete
(file_size)¶ 当文件上传完毕时调用。
处理程序应返回一个
UploadedFile
对象,该对象将存储在request.FILES
中。处理程序也可以返回None
以表明UploadedFile
对象应来自后续的上传处理程序。
可选方法¶
自定义上传处理程序也可以定义以下任何一个可选方法或属性:
-
FileUploadHandler.
chunk_size
¶ Django 应该存储到内存中并反馈给处理程序的 “块” 的大小,以字节为单位。也就是说,这个属性控制了输入到
FileUploadHandler.receive_data_chunk
的数据块的大小。为了获得最大的性能,分块大小应该被
4
整除,并且大小不能超过 2GB(231 字节)。当有多个处理程序提供的多个分块大小时,Django 将使用任何处理程序定义的最小分块大小。默认为 64*210 字节,即 64KB。
-
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
()¶ - New in Django 3.2.
回调信号,表明上传被中断,例如,当用户在文件上传过程中关闭他们的浏览器。
-
FileUploadHandler.
handle_raw_input
(input_data, META, content_length, boundary, encoding)¶ 允许处理程序完全覆盖原始 HTTP 输入的解析。
input_data
是一个支持read()
-ing 的类文件对象。META
与request.META
是同一个对象。content_length
是input_data
中数据的长度。不要从input_data
中读取超过content_length
的字节。boundary
是本次请求的 MIME 边界。encoding
是请求的编码。如果想继续上传处理,则返回
None
,如果想直接返回适合请求的新数据结构,则返回(POST,FILES)
的元组。