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

上传的文件

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)[源代码]

文件完成上传时调用。

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

可选方法

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

FileUploadHandler.chunk_size

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

为了获得最佳性能，块大小应能被 4 整除，并且大小不应超过 2 GB（231 字节）。当多个处理程序提供多个块大小时，Django 将使用任何处理程序定义的最小块大小。

默认值为 64*210 字节，即 64 KB。

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) 元组。

文件存储 API
表单
返回顶部