| 1 |
================================== |
| 2 |
Uploaded Files and Upload Handlers |
| 3 |
================================== |
| 4 |
|
| 5 |
.. module:: django.core.files.uploadedfile |
| 6 |
:synopsis: Classes representing uploaded files. |
| 7 |
|
| 8 |
Uploaded files |
| 9 |
============== |
| 10 |
|
| 11 |
.. class:: UploadedFile |
| 12 |
|
| 13 |
During file uploads, the actual file data is stored in :attr:`request.FILES |
| 14 |
<django.http.HttpRequest.FILES>`. Each entry in this dictionary is an |
| 15 |
``UploadedFile`` object (or a subclass) -- a wrapper around an uploaded file. |
| 16 |
You'll usually use one of these methods to access the uploaded content: |
| 17 |
|
| 18 |
.. method:: UploadedFile.read() |
| 19 |
|
| 20 |
Read the entire uploaded data from the file. Be careful with this method: |
| 21 |
if the uploaded file is huge it can overwhelm your system if you try to |
| 22 |
read it into memory. You'll probably want to use ``chunks()`` instead; see |
| 23 |
below. |
| 24 |
|
| 25 |
.. method:: UploadedFile.multiple_chunks(chunk_size=None) |
| 26 |
|
| 27 |
Returns ``True`` if the uploaded file is big enough to require reading in |
| 28 |
multiple chunks. By default this will be any file larger than 2.5 megabytes, |
| 29 |
but that's configurable; see below. |
| 30 |
|
| 31 |
.. method:: UploadedFile.chunks(chunk_size=None) |
| 32 |
|
| 33 |
A generator returning chunks of the file. If ``multiple_chunks()`` is |
| 34 |
``True``, you should use this method in a loop instead of ``read()``. |
| 35 |
|
| 36 |
In practice, it's often easiest to use ``chunks()`` all the time. Looping |
| 37 |
over ``chunks()`` instead of using ``read()`` ensures that large files |
| 38 |
don't overwhelm your system's memory. |
| 39 |
|
| 40 |
Here are some useful attributes of ``UploadedFile``: |
| 41 |
|
| 42 |
.. attribute:: UploadedFile.name |
| 43 |
|
| 44 |
The name of the uploaded file (e.g. ``my_file.txt``). |
| 45 |
|
| 46 |
.. attribute:: UploadedFile.size |
| 47 |
|
| 48 |
The size, in bytes, of the uploaded file. |
| 49 |
|
| 50 |
.. attribute:: UploadedFile.content_type |
| 51 |
|
| 52 |
The content-type header uploaded with the file (e.g. :mimetype:`text/plain` |
| 53 |
or :mimetype:`application/pdf`). Like any data supplied by the user, you |
| 54 |
shouldn't trust that the uploaded file is actually this type. You'll still |
| 55 |
need to validate that the file contains the content that the content-type |
| 56 |
header claims -- "trust but verify." |
| 57 |
|
| 58 |
.. attribute:: UploadedFile.content_type_extra |
| 59 |
|
| 60 |
A dictionary containing extra parameters passed to the ``content-type`` |
| 61 |
header. This is typically provided by services, such as Google App Engine, |
| 62 |
that intercept and handle file uploads on your behalf. As a result your |
| 63 |
handler may not receive the uploaded file content, but instead a URL or |
| 64 |
other pointer to the file (see :rfc:`RFC 2388 <2388#section-5.3>`). |
| 65 |
|
| 66 |
.. attribute:: UploadedFile.charset |
| 67 |
|
| 68 |
For :mimetype:`text/*` content-types, the character set (i.e. ``utf8``) |
| 69 |
supplied by the browser. Again, "trust but verify" is the best policy here. |
| 70 |
|
| 71 |
.. note:: |
| 72 |
|
| 73 |
Like regular Python files, you can read the file line-by-line by iterating |
| 74 |
over the uploaded file:: |
| 75 |
|
| 76 |
for line in uploadedfile: |
| 77 |
do_something_with(line) |
| 78 |
|
| 79 |
Lines are split using :pep:`universal newlines <278>`. The following are |
| 80 |
recognized as ending a line: the Unix end-of-line convention ``'\n'``, the |
| 81 |
Windows convention ``'\r\n'``, and the old Macintosh convention ``'\r'``. |
| 82 |
|
| 83 |
Subclasses of ``UploadedFile`` include: |
| 84 |
|
| 85 |
.. class:: TemporaryUploadedFile |
| 86 |
|
| 87 |
A file uploaded to a temporary location (i.e. stream-to-disk). This class |
| 88 |
is used by the |
| 89 |
:class:`~django.core.files.uploadhandler.TemporaryFileUploadHandler`. In |
| 90 |
addition to the methods from :class:`UploadedFile`, it has one additional |
| 91 |
method: |
| 92 |
|
| 93 |
.. method:: TemporaryUploadedFile.temporary_file_path() |
| 94 |
|
| 95 |
Returns the full path to the temporary uploaded file. |
| 96 |
|
| 97 |
.. class:: InMemoryUploadedFile |
| 98 |
|
| 99 |
A file uploaded into memory (i.e. stream-to-memory). This class is used |
| 100 |
by the :class:`~django.core.files.uploadhandler.MemoryFileUploadHandler`. |
| 101 |
|
| 102 |
Built-in upload handlers |
| 103 |
======================== |
| 104 |
|
| 105 |
.. module:: django.core.files.uploadhandler |
| 106 |
:synopsis: Django's handlers for file uploads. |
| 107 |
|
| 108 |
Together the :class:`MemoryFileUploadHandler` and |
| 109 |
:class:`TemporaryFileUploadHandler` provide Django's default file upload |
| 110 |
behavior of reading small files into memory and large ones onto disk. They |
| 111 |
are located in ``django.core.files.uploadhandler``. |
| 112 |
|
| 113 |
.. class:: MemoryFileUploadHandler |
| 114 |
|
| 115 |
File upload handler to stream uploads into memory (used for small files). |
| 116 |
|
| 117 |
.. class:: TemporaryFileUploadHandler |
| 118 |
|
| 119 |
Upload handler that streams data into a temporary file using |
| 120 |
:class:`~django.core.files.uploadedfile.TemporaryUploadedFile`. |
| 121 |
|
| 122 |
.. _custom_upload_handlers: |
| 123 |
|
| 124 |
Writing custom upload handlers |
| 125 |
============================== |
| 126 |
|
| 127 |
.. class:: FileUploadHandler |
| 128 |
|
| 129 |
All file upload handlers should be subclasses of |
| 130 |
``django.core.files.uploadhandler.FileUploadHandler``. You can define upload |
| 131 |
handlers wherever you wish. |
| 132 |
|
| 133 |
Required methods |
| 134 |
---------------- |
| 135 |
|
| 136 |
Custom file upload handlers **must** define the following methods: |
| 137 |
|
| 138 |
.. method:: FileUploadHandler.receive_data_chunk(raw_data, start) |
| 139 |
|
| 140 |
Receives a "chunk" of data from the file upload. |
| 141 |
|
| 142 |
``raw_data`` is a bytestring containing the uploaded data. |
| 143 |
|
| 144 |
``start`` is the position in the file where this ``raw_data`` chunk |
| 145 |
begins. |
| 146 |
|
| 147 |
The data you return will get fed into the subsequent upload handlers' |
| 148 |
``receive_data_chunk`` methods. In this way, one handler can be a |
| 149 |
"filter" for other handlers. |
| 150 |
|
| 151 |
Return ``None`` from ``receive_data_chunk`` to short-circuit remaining |
| 152 |
upload handlers from getting this chunk. This is useful if you're |
| 153 |
storing the uploaded data yourself and don't want future handlers to |
| 154 |
store a copy of the data. |
| 155 |
|
| 156 |
If you raise a ``StopUpload`` or a ``SkipFile`` exception, the upload |
| 157 |
will abort or the file will be completely skipped. |
| 158 |
|
| 159 |
.. method:: FileUploadHandler.file_complete(file_size) |
| 160 |
|
| 161 |
Called when a file has finished uploading. |
| 162 |
|
| 163 |
The handler should return an ``UploadedFile`` object that will be stored |
| 164 |
in ``request.FILES``. Handlers may also return ``None`` to indicate that |
| 165 |
the ``UploadedFile`` object should come from subsequent upload handlers. |
| 166 |
|
| 167 |
Optional methods |
| 168 |
---------------- |
| 169 |
|
| 170 |
Custom upload handlers may also define any of the following optional methods or |
| 171 |
attributes: |
| 172 |
|
| 173 |
.. attribute:: FileUploadHandler.chunk_size |
| 174 |
|
| 175 |
Size, in bytes, of the "chunks" Django should store into memory and feed |
| 176 |
into the handler. That is, this attribute controls the size of chunks |
| 177 |
fed into ``FileUploadHandler.receive_data_chunk``. |
| 178 |
|
| 179 |
For maximum performance the chunk sizes should be divisible by ``4`` and |
| 180 |
should not exceed 2 GB (2\ :sup:`31` bytes) in size. When there are |
| 181 |
multiple chunk sizes provided by multiple handlers, Django will use the |
| 182 |
smallest chunk size defined by any handler. |
| 183 |
|
| 184 |
The default is 64*2\ :sup:`10` bytes, or 64 KB. |
| 185 |
|
| 186 |
.. method:: FileUploadHandler.new_file(field_name, file_name, content_type, content_length, charset, content_type_extra) |
| 187 |
|
| 188 |
Callback signaling that a new file upload is starting. This is called |
| 189 |
before any data has been fed to any upload handlers. |
| 190 |
|
| 191 |
``field_name`` is a string name of the file ``<input>`` field. |
| 192 |
|
| 193 |
``file_name`` is the filename provided by the browser. |
| 194 |
|
| 195 |
``content_type`` is the MIME type provided by the browser -- E.g. |
| 196 |
``'image/jpeg'``. |
| 197 |
|
| 198 |
``content_length`` is the length of the image given by the browser. |
| 199 |
Sometimes this won't be provided and will be ``None``. |
| 200 |
|
| 201 |
``charset`` is the character set (i.e. ``utf8``) given by the browser. |
| 202 |
Like ``content_length``, this sometimes won't be provided. |
| 203 |
|
| 204 |
``content_type_extra`` is extra information about the file from the |
| 205 |
``content-type`` header. See :attr:`UploadedFile.content_type_extra |
| 206 |
<django.core.files.uploadedfile.UploadedFile.content_type_extra>`. |
| 207 |
|
| 208 |
This method may raise a ``StopFutureHandlers`` exception to prevent |
| 209 |
future handlers from handling this file. |
| 210 |
|
| 211 |
.. method:: FileUploadHandler.upload_complete() |
| 212 |
|
| 213 |
Callback signaling that the entire upload (all files) has completed. |
| 214 |
|
| 215 |
.. method:: FileUploadHandler.upload_interrupted() |
| 216 |
|
| 217 |
Callback signaling that the upload was interrupted, e.g. when the user |
| 218 |
closed their browser during file upload. |
| 219 |
|
| 220 |
.. method:: FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding) |
| 221 |
|
| 222 |
Allows the handler to completely override the parsing of the raw |
| 223 |
HTTP input. |
| 224 |
|
| 225 |
``input_data`` is a file-like object that supports ``read()``-ing. |
| 226 |
|
| 227 |
``META`` is the same object as ``request.META``. |
| 228 |
|
| 229 |
``content_length`` is the length of the data in ``input_data``. Don't |
| 230 |
read more than ``content_length`` bytes from ``input_data``. |
| 231 |
|
| 232 |
``boundary`` is the MIME boundary for this request. |
| 233 |
|
| 234 |
``encoding`` is the encoding of the request. |
| 235 |
|
| 236 |
Return ``None`` if you want upload handling to continue, or a tuple of |
| 237 |
``(POST, FILES)`` if you want to return the new data structures suitable |
| 238 |
for the request directly. |