Uploaded files¶
- class
UploadedFile[source]¶
During file uploads, the actual file data is stored in request.FILES. Each entry in this dictionary is anUploadedFile object (or a subclass) – a wrapper around an uploaded file.You’ll usually use one of these methods to access the uploaded content:
UploadedFile.read()¶Read the entire uploaded data from the file. Be careful with this method:if the uploaded file is huge it can overwhelm your system if you try toread it into memory. You’ll probably want to use
chunks()instead; seebelow.
UploadedFile.multiple_chunks(chunk_size=None)¶Returns
Trueif the uploaded file is big enough to require reading inmultiple chunks. By default this will be any file larger than 2.5 megabytes,but that’s configurable; see below.
UploadedFile.chunks(chunk_size=None)¶A generator returning chunks of the file. If
multiple_chunks()isTrue, you should use this method in a loop instead ofread().In practice, it’s often easiest to use
chunks()all the time. Loopingoverchunks()instead of usingread()ensures that large filesdon’t overwhelm your system’s memory.
Here are some useful attributes of UploadedFile:
UploadedFile.name¶The name of the uploaded file (e.g.
my_file.txt).
UploadedFile.size¶The size, in bytes, of the uploaded file.
UploadedFile.content_type¶The content-type header uploaded with the file (e.g. text/plainor application/pdf). Like any data supplied by the user, youshouldn’t trust that the uploaded file is actually this type. You’ll stillneed to validate that the file contains the content that the content-typeheader claims – “trust but verify.”
UploadedFile.content_type_extra¶A dictionary containing extra parameters passed to the
content-typeheader. This is typically provided by services, such as Google App Engine,that intercept and handle file uploads on your behalf. As a result yourhandler may not receive the uploaded file content, but instead a URL orother pointer to the file (see RFC 2388).
UploadedFile.charset¶For text/* content-types, the character set (i.e.
utf8)supplied by the browser. Again, “trust but verify” is the best policy here.
Note
Like regular Python files, you can read the file line-by-line by iteratingover the uploaded file:
for line in uploadedfile: do_something_with(line)
Lines are split using universal newlines. The following arerecognized as ending a line: the Unix end-of-line convention '\n', theWindows convention '\r\n', and the old Macintosh convention '\r'.
Subclasses of UploadedFile include:
- class
TemporaryUploadedFile[source]¶ A file uploaded to a temporary location (i.e. stream-to-disk). This classis used by theTemporaryFileUploadHandler. Inaddition to the methods from UploadedFile, it has one additionalmethod:
TemporaryUploadedFile.temporary_file_path()[source]¶Returns the full path to the temporary uploaded file.
- class
InMemoryUploadedFile[source]¶ A file uploaded into memory (i.e. stream-to-memory). This class is usedby the MemoryFileUploadHandler.
Built-in upload handlers¶
Together the MemoryFileUploadHandler andTemporaryFileUploadHandler provide Django’s default file uploadbehavior of reading small files into memory and large ones onto disk. Theyare located in django.core.files.uploadhandler.
- class
MemoryFileUploadHandler[source]¶
File upload handler to stream uploads into memory (used for small files).
- class
TemporaryFileUploadHandler[source]¶
Upload handler that streams data into a temporary file usingTemporaryUploadedFile.
Writing custom upload handlers¶
- class
FileUploadHandler[source]¶
All file upload handlers should be subclasses ofdjango.core.files.uploadhandler.FileUploadHandler. You can define uploadhandlers wherever you wish.
Required methods¶
Custom file upload handlers must define the following methods:
FileUploadHandler.receive_data_chunk(raw_data, start)[source]¶Receives a “chunk” of data from the file upload.
raw_datais a bytestring containing the uploaded data.startis the position in the file where thisraw_datachunkbegins.The data you return will get fed into the subsequent upload handlers’
receive_data_chunkmethods. In this way, one handler can be a“filter” for other handlers.Return
Nonefromreceive_data_chunkto short-circuit remainingupload handlers from getting this chunk. This is useful if you’restoring the uploaded data yourself and don’t want future handlers tostore a copy of the data.If you raise a
StopUploador aSkipFileexception, the uploadwill abort or the file will be completely skipped.
FileUploadHandler.file_complete(file_size)[source]¶Called when a file has finished uploading.
The handler should return an
UploadedFileobject that will be storedinrequest.FILES. Handlers may also returnNoneto indicate thattheUploadedFileobject should come from subsequent upload handlers.
Optional methods¶
Custom upload handlers may also define any of the following optional methods orattributes:
FileUploadHandler.chunk_size¶Size, in bytes, of the “chunks” Django should store into memory and feedinto the handler. That is, this attribute controls the size of chunksfed into
FileUploadHandler.receive_data_chunk.For maximum performance the chunk sizes should be divisible by
4andshould not exceed 2 GB (231 bytes) in size. When there aremultiple chunk sizes provided by multiple handlers, Django will use thesmallest chunk size defined by any handler.The default is 64*210 bytes, or 64 KB.
FileUploadHandler.new_file(field_name, file_name, content_type, content_length, charset, content_type_extra)[source]¶Callback signaling that a new file upload is starting. This is calledbefore any data has been fed to any upload handlers.
field_nameis a string name of the file<input>field.file_nameis the filename provided by the browser.content_typeis the MIME type provided by the browser – E.g.'image/jpeg'.content_lengthis the length of the image given by the browser.Sometimes this won’t be provided and will beNone.charsetis the character set (i.e.utf8) given by the browser.Likecontent_length, this sometimes won’t be provided.content_type_extrais extra information about the file from thecontent-typeheader. See UploadedFile.content_type_extra.This method may raise a
StopFutureHandlersexception to preventfuture handlers from handling this file.
FileUploadHandler.upload_complete()[source]¶Callback signaling that the entire upload (all files) has completed.
FileUploadHandler.upload_interrupted()[source]¶Callback signaling that the upload was interrupted, e.g. when the userclosed their browser during file upload.
FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding)[source]¶Allows the handler to completely override the parsing of the rawHTTP input.
input_datais a file-like object that supportsread()-ing.METAis the same object asrequest.META.content_lengthis the length of the data ininput_data. Don’tread more thancontent_lengthbytes frominput_data.boundaryis the MIME boundary for this request.encodingis the encoding of the request.Return
Noneif you want upload handling to continue, or a tuple of(POST, FILES)if you want to return the new data structures suitablefor the request directly.
