上传的文件和上传处理器

上传的文件

class UploadedFile[source]

在文件上传过程中，实际的文件数据存储在 request.FILES 中。此字典中的每个条目都是一个 UploadedFile 对象（或其子类）——上传文件的包装器。您通常会使用以下方法之一来访问上传的内容

UploadedFile.read()

读取文件中所有上传的数据。使用此方法时要小心：如果上传的文件很大，则尝试将其读入内存可能会压垮您的系统。您可能需要改用 chunks()；请参见下文。

UploadedFile.multiple_chunks(chunk_size=None)

如果上传的文件足够大，需要分块读取，则返回 True。默认情况下，任何大于 2.5 MB 的文件都将如此，但此值是可配置的；请参见下文。

UploadedFile.chunks(chunk_size=None)

返回文件的块的生成器。如果 multiple_chunks() 为 True，则应在循环中使用此方法，而不是使用 read()。

实际上，始终使用 chunks() 通常是最简单的。循环遍历 chunks() 而不是使用 read() 可确保大型文件不会压垮系统的内存。

以下是 UploadedFile 的一些有用属性

UploadedFile.name

上传文件的名称（例如 my_file.txt）。

UploadedFile.size

上传文件的大小（以字节为单位）。

UploadedFile.content_type

与文件一起上传的 content-type 标头（例如 text/plain 或 application/pdf）。与用户提供的任何数据一样，您不应相信上传的文件实际上就是此类型。您仍然需要验证文件是否包含 content-type 标头声明的内容——“信任但验证”。

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

上传到临时位置（即流到磁盘）的文件。此类由 TemporaryFileUploadHandler 使用。除了 UploadedFile 中的方法外，它还具有一个附加方法

TemporaryUploadedFile.temporary_file_path()[source]

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

class InMemoryUploadedFile[source]

上传到内存（即流到内存）的文件。此类由 MemoryFileUploadHandler 使用。

内置上传处理器

MemoryFileUploadHandler 和 TemporaryFileUploadHandler 共同提供了 Django 的默认文件上传行为，即：将小文件读取到内存中，将大文件读取到磁盘上。它们位于 django.core.files.uploadhandler 中。

class MemoryFileUploadHandler[source]

将上传流式传输到内存中的文件上传处理器（用于小文件）。

class TemporaryFileUploadHandler[source]

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

编写自定义上传处理器

class FileUploadHandler[source]

所有文件上传处理器都应是 django.core.files.uploadhandler.FileUploadHandler 的子类。您可以在任何想要的地方定义上传处理器。

必需方法

自定义文件上传处理器**必须**定义以下方法

FileUploadHandler.receive_data_chunk(raw_data, start)[source]

接收来自文件上传的“块”数据。

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

start 是此 raw_data 块在文件中的起始位置。

您返回的数据将被馈送到后续上传处理器的 receive_data_chunk 方法中。这样，一个处理程序可以作为其他处理程序的“过滤器”。

从 receive_data_chunk 返回 None 以使其余上传处理程序无法获取此块。如果您自己存储上传的数据并且不希望将来的处理程序存储数据的副本，这将很有用。

如果您引发了 StopUpload 或 SkipFile 异常，上传将中止或文件将被完全跳过。

FileUploadHandler.file_complete(file_size)[source]

当文件上传完成时调用。

处理程序应返回一个 UploadedFile 对象，该对象将存储在 request.FILES 中。处理程序也可以返回 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)[source]

回调信号，指示新的文件上传已开始。这在任何数据被馈送到任何上传处理程序之前都会被调用。

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

回调信号，指示整个上传（所有文件）已完成。

FileUploadHandler.upload_interrupted()[source]

回调信号，指示上传被中断，例如，当用户在文件上传过程中关闭浏览器时。

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

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

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

META 与 request.META 相同。

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

boundary 是此请求的 MIME 边界。

encoding 是请求的编码。

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

文件存储 API
表单
返回顶部