Debian Codegraph @

docs/ref/files/uploads.txt

raw
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.