← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal

« back to all changes in this revision

Viewing changes to docs/topics/http/file-uploads.txt

  • Committer: Bazaar Package Importer
  • Author(s): Scott James Remnant, Eddy Mulyono
  • Date: 2008-09-16 12:18:47 UTC
  • mfrom: (1.1.5 upstream) (4.1.1 lenny)
  • Revision ID: james.westby@ubuntu.com-20080916121847-mg225rg5mnsdqzr0
Tags: 1.0-1ubuntu1
https://launchpad.net/bugs/264191
* Merge from Debian (LP: #264191), remaining changes:
  - Run test suite on build.

[Eddy Mulyono]
* Update patch to workaround network test case failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/topics/http/file-uploads.txt
 
1
.. _topics-file-uploads:
 
2
 
 
3
============
 
4
File Uploads
 
5
============
 
6
 
 
7
.. currentmodule:: django.core.files
 
8
 
 
9
.. versionadded:: 1.0
 
10
 
 
11
Most Web sites wouldn't be complete without a way to upload files. When Django
 
12
handles a file upload, the file data ends up placed in ``request.FILES`` (for
 
13
more on the ``request`` object see the documentation for :ref:`request and
 
14
response objects <ref-request-response>`). This document explains how files are
 
15
stored on disk and in memory, and how to customize the default behavior.
 
16
 
 
17
Basic file uploads
 
18
==================
 
19
 
 
20
Consider a simple form containing a ``FileField``::
 
21
 
 
22
    from django import forms
 
23
 
 
24
    class UploadFileForm(forms.Form):
 
25
        title = forms.CharField(max_length=50)
 
26
        file  = forms.FileField()
 
27
 
 
28
A view handling this form will receive the file data in ``request.FILES``, which
 
29
is a dictionary containing a key for each ``FileField`` (or ``ImageField``, or
 
30
other ``FileField`` subclass) in the form. So the data from the above form would
 
31
be accessible as ``request.FILES['file']``.
 
32
 
 
33
Most of the time, you'll simply pass the file data from ``request`` into the
 
34
form as described in :ref:`binding-uploaded-files`. This would look
 
35
something like::
 
36
 
 
37
    from django.http import HttpResponseRedirect
 
38
    from django.shortcuts import render_to_response
 
39
 
 
40
    # Imaginary function to handle an uploaded file.
 
41
    from somewhere import handle_uploaded_file
 
42
 
 
43
    def upload_file(request):
 
44
        if request.method == 'POST':
 
45
            form = UploadFileForm(request.POST, request.FILES)
 
46
            if form.is_valid():
 
47
                handle_uploaded_file(request.FILES['file'])
 
48
                return HttpResponseRedirect('/success/url/')
 
49
        else:
 
50
            form = UploadFileForm()
 
51
        return render_to_response('upload.html', {'form': form})
 
52
 
 
53
Notice that we have to pass ``request.FILES`` into the form's constructor; this
 
54
is how file data gets bound into a form.
 
55
 
 
56
Handling uploaded files
 
57
-----------------------
 
58
 
 
59
The final piece of the puzzle is handling the actual file data from
 
60
``request.FILES``. Each entry in this dictionary is an ``UploadedFile`` object
 
61
-- a simple wrapper around an uploaded file. You'll usually use one of these
 
62
methods to access the uploaded content:
 
63
 
 
64
    ``UploadedFile.read()``
 
65
        Read the entire uploaded data from the file. Be careful with this
 
66
        method: if the uploaded file is huge it can overwhelm your system if you
 
67
        try to read it into memory. You'll probably want to use ``chunks()``
 
68
        instead; see below.
 
69
 
 
70
    ``UploadedFile.multiple_chunks()``
 
71
        Returns ``True`` if the uploaded file is big enough to require
 
72
        reading in multiple chunks. By default this will be any file
 
73
        larger than 2.5 megabytes, but that's configurable; see below.
 
74
 
 
75
    ``UploadedFile.chunks()``
 
76
        A generator returning chunks of the file. If ``multiple_chunks()`` is
 
77
        ``True``, you should use this method in a loop instead of ``read()``.
 
78
 
 
79
        In practice, it's often easiest simply to use ``chunks()`` all the time;
 
80
        see the example below.
 
81
 
 
82
    ``UploadedFile.name``
 
83
        The name of the uploaded file (e.g. ``my_file.txt``).
 
84
 
 
85
    ``UploadedFile.size``
 
86
        The size, in bytes, of the uploaded file.
 
87
 
 
88
There are a few other methods and attributes available on ``UploadedFile``
 
89
objects; see `UploadedFile objects`_ for a complete reference.
 
90
 
 
91
Putting it all together, here's a common way you might handle an uploaded file::
 
92
 
 
93
    def handle_uploaded_file(f):
 
94
        destination = open('some/file/name.txt', 'wb+')
 
95
        for chunk in f.chunks():
 
96
            destination.write(chunk)
 
97
 
 
98
Looping over ``UploadedFile.chunks()`` instead of using ``read()`` ensures that
 
99
large files don't overwhelm your system's memory.
 
100
 
 
101
Where uploaded data is stored
 
102
-----------------------------
 
103
 
 
104
Before you save uploaded files, the data needs to be stored somewhere.
 
105
 
 
106
By default, if an uploaded file is smaller than 2.5 megabytes, Django will hold
 
107
the entire contents of the upload in memory. This means that saving the file
 
108
involves only a read from memory and a write to disk and thus is very fast.
 
109
 
 
110
However, if an uploaded file is too large, Django will write the uploaded file
 
111
to a temporary file stored in your system's temporary directory. On a Unix-like
 
112
platform this means you can expect Django to generate a file called something
 
113
like ``/tmp/tmpzfp6I6.upload``. If an upload is large enough, you can watch this
 
114
file grow in size as Django streams the data onto disk.
 
115
 
 
116
These specifics -- 2.5 megabytes; ``/tmp``; etc. -- are simply "reasonable
 
117
defaults". Read on for details on how you can customize or completely replace
 
118
upload behavior.
 
119
 
 
120
Changing upload handler behavior
 
121
--------------------------------
 
122
 
 
123
Three settings control Django's file upload behavior:
 
124
 
 
125
    :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`
 
126
        The maximum size, in bytes, for files that will be uploaded into memory.
 
127
        Files larger than :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE` will be
 
128
        streamed to disk.
 
129
 
 
130
        Defaults to 2.5 megabytes.
 
131
 
 
132
    :setting:`FILE_UPLOAD_TEMP_DIR`
 
133
        The directory where uploaded files larger than
 
134
        :setting:`FILE_UPLOAD_TEMP_DIR` will be stored.
 
135
 
 
136
        Defaults to your system's standard temporary directory (i.e. ``/tmp`` on
 
137
        most Unix-like systems).
 
138
        
 
139
    :setting:`FILE_UPLOAD_PERMISSIONS`
 
140
        The numeric mode (i.e. ``0644``) to set newly uploaded files to. For
 
141
        more information about what these modes mean, see the `documentation for
 
142
        os.chmod`_
 
143
        
 
144
        If this isn't given or is ``None``, you'll get operating-system
 
145
        dependent behavior. On most platforms, temporary files will have a mode
 
146
        of ``0600``, and files saved from memory will be saved using the
 
147
        system's standard umask.
 
148
        
 
149
        .. warning::
 
150
        
 
151
            If you're not familiar with file modes, please note that the leading
 
152
            ``0`` is very important: it indicates an octal number, which is the
 
153
            way that modes must be specified. If you try to use ``644``, you'll
 
154
            get totally incorrect behavior.
 
155
            
 
156
            **Always prefix the mode with a ``0``.**
 
157
 
 
158
    :setting:`FILE_UPLOAD_HANDLERS`
 
159
        The actual handlers for uploaded files. Changing this setting allows
 
160
        complete customization -- even replacement -- of Django's upload
 
161
        process. See `upload handlers`_, below, for details.
 
162
 
 
163
        Defaults to::
 
164
 
 
165
            ("django.core.files.uploadhandler.MemoryFileUploadHandler",
 
166
             "django.core.files.uploadhandler.TemporaryFileUploadHandler",)
 
167
 
 
168
        Which means "try to upload to memory first, then fall back to temporary
 
169
        files."
 
170
 
 
171
.. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html 
 
172
 
 
173
``UploadedFile`` objects
 
174
========================
 
175
 
 
176
.. class:: UploadedFile
 
177
 
 
178
In addition to those inherited from :class:`File`, all ``UploadedFile`` objects
 
179
define the following methods/attributes:
 
180
 
 
181
    ``UploadedFile.content_type``
 
182
        The content-type header uploaded with the file (e.g. ``text/plain`` or
 
183
        ``application/pdf``). Like any data supplied by the user, you shouldn't
 
184
        trust that the uploaded file is actually this type. You'll still need to
 
185
        validate that the file contains the content that the content-type header
 
186
        claims -- "trust but verify."
 
187
 
 
188
    ``UploadedFile.charset``
 
189
        For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied
 
190
        by the browser. Again, "trust but verify" is the best policy here.
 
191
 
 
192
    ``UploadedFile.temporary_file_path()``
 
193
        Only files uploaded onto disk will have this method; it returns the full
 
194
        path to the temporary uploaded file.
 
195
        
 
196
.. note::
 
197
 
 
198
    Like regular Python files, you can read the file line-by-line simply by
 
199
    iterating over the uploaded file:
 
200
    
 
201
    .. code-block:: python
 
202
        
 
203
        for line in uploadedfile:
 
204
            do_something_with(line)
 
205
            
 
206
    However, *unlike* standard Python files, :class:`UploadedFile` only
 
207
    understands ``\n`` (also known as "Unix-style") line endings. If you know
 
208
    that you need to handle uploaded files with different line endings, you'll
 
209
    need to do so in your view.
 
210
 
 
211
Upload Handlers
 
212
===============
 
213
 
 
214
When a user uploads a file, Django passes off the file data to an *upload
 
215
handler* -- a small class that handles file data as it gets uploaded. Upload
 
216
handlers are initially defined in the ``FILE_UPLOAD_HANDLERS`` setting, which
 
217
defaults to::
 
218
 
 
219
    ("django.core.files.uploadhandler.MemoryFileUploadHandler",
 
220
     "django.core.files.uploadhandler.TemporaryFileUploadHandler",)
 
221
 
 
222
Together the ``MemoryFileUploadHandler`` and ``TemporaryFileUploadHandler``
 
223
provide Django's default file upload behavior of reading small files into memory
 
224
and large ones onto disk.
 
225
 
 
226
You can write custom handlers that customize how Django handles files. You
 
227
could, for example, use custom handlers to enforce user-level quotas, compress
 
228
data on the fly, render progress bars, and even send data to another storage
 
229
location directly without storing it locally.
 
230
 
 
231
Modifying upload handlers on the fly
 
232
------------------------------------
 
233
 
 
234
Sometimes particular views require different upload behavior. In these cases,
 
235
you can override upload handlers on a per-request basis by modifying
 
236
``request.upload_handlers``. By default, this list will contain the upload
 
237
handlers given by ``FILE_UPLOAD_HANDLERS``, but you can modify the list as you
 
238
would any other list.
 
239
 
 
240
For instance, suppose you've written a ``ProgressBarUploadHandler`` that
 
241
provides feedback on upload progress to some sort of AJAX widget. You'd add this
 
242
handler to your upload handlers like this::
 
243
 
 
244
    request.upload_handlers.insert(0, ProgressBarUploadHandler())
 
245
 
 
246
You'd probably want to use ``list.insert()`` in this case (instead of
 
247
``append()``) because a progress bar handler would need to run *before* any
 
248
other handlers. Remember, the upload handlers are processed in order.
 
249
 
 
250
If you want to replace the upload handlers completely, you can just assign a new
 
251
list::
 
252
 
 
253
   request.upload_handlers = [ProgressBarUploadHandler()]
 
254
 
 
255
.. note::
 
256
 
 
257
    You can only modify upload handlers *before* accessing
 
258
    ``request.POST`` or ``request.FILES`` -- it doesn't make sense to
 
259
    change upload handlers after upload handling has already
 
260
    started. If you try to modify ``request.upload_handlers`` after
 
261
    reading from ``request.POST`` or ``request.FILES`` Django will
 
262
    throw an error.
 
263
 
 
264
    Thus, you should always modify uploading handlers as early in your view as
 
265
    possible.
 
266
 
 
267
Writing custom upload handlers
 
268
------------------------------
 
269
 
 
270
All file upload handlers should be subclasses of
 
271
``django.core.files.uploadhandler.FileUploadHandler``. You can define upload
 
272
handlers wherever you wish.
 
273
 
 
274
Required methods
 
275
~~~~~~~~~~~~~~~~
 
276
 
 
277
Custom file upload handlers **must** define the following methods:
 
278
 
 
279
    ``FileUploadHandler.receive_data_chunk(self, raw_data, start)``
 
280
        Receives a "chunk" of data from the file upload.
 
281
 
 
282
        ``raw_data`` is a byte string containing the uploaded data.
 
283
 
 
284
        ``start`` is the position in the file where this ``raw_data`` chunk
 
285
        begins.
 
286
 
 
287
        The data you return will get fed into the subsequent upload handlers'
 
288
        ``receive_data_chunk`` methods. In this way, one handler can be a
 
289
        "filter" for other handlers.
 
290
 
 
291
        Return ``None`` from ``receive_data_chunk`` to sort-circuit remaining
 
292
        upload handlers from getting this chunk.. This is useful if you're
 
293
        storing the uploaded data yourself and don't want future handlers to
 
294
        store a copy of the data.
 
295
 
 
296
        If you raise a ``StopUpload`` or a ``SkipFile`` exception, the upload
 
297
        will abort or the file will be completely skipped.
 
298
 
 
299
    ``FileUploadHandler.file_complete(self, file_size)``
 
300
        Called when a file has finished uploading.
 
301
 
 
302
        The handler should return an ``UploadedFile`` object that will be stored
 
303
        in ``request.FILES``. Handlers may also return ``None`` to indicate that
 
304
        the ``UploadedFile`` object should come from subsequent upload handlers.
 
305
 
 
306
Optional methods
 
307
~~~~~~~~~~~~~~~~
 
308
 
 
309
Custom upload handlers may also define any of the following optional methods or
 
310
attributes:
 
311
 
 
312
    ``FileUploadHandler.chunk_size``
 
313
        Size, in bytes, of the "chunks" Django should store into memory and feed
 
314
        into the handler. That is, this attribute controls the size of chunks
 
315
        fed into ``FileUploadHandler.receive_data_chunk``.
 
316
 
 
317
        For maximum performance the chunk sizes should be divisible by ``4`` and
 
318
        should not exceed 2 GB (2\ :sup:`31` bytes) in size. When there are
 
319
        multiple chunk sizes provided by multiple handlers, Django will use the
 
320
        smallest chunk size defined by any handler.
 
321
 
 
322
        The default is 64*2\ :sup:`10` bytes, or 64 KB.
 
323
 
 
324
    ``FileUploadHandler.new_file(self, field_name, file_name, content_type, content_length, charset)``
 
325
        Callback signaling that a new file upload is starting. This is called
 
326
        before any data has been fed to any upload handlers.
 
327
 
 
328
        ``field_name`` is a string name of the file ``<input>`` field.
 
329
 
 
330
        ``file_name`` is the unicode filename that was provided by the browser.
 
331
 
 
332
        ``content_type`` is the MIME type provided by the browser -- E.g.
 
333
        ``'image/jpeg'``.
 
334
 
 
335
        ``content_length`` is the length of the image given by the browser.
 
336
        Sometimes this won't be provided and will be ``None``., ``None``
 
337
        otherwise.
 
338
 
 
339
        ``charset`` is the character set (i.e. ``utf8``) given by the browser.
 
340
        Like ``content_length``, this sometimes won't be provided.
 
341
 
 
342
        This method may raise a ``StopFutureHandlers`` exception to prevent
 
343
        future handlers from handling this file.
 
344
 
 
345
    ``FileUploadHandler.upload_complete(self)``
 
346
        Callback signaling that the entire upload (all files) has completed.
 
347
 
 
348
    ``FileUploadHandler.handle_raw_input(self, input_data, META, content_length, boundary, encoding)``
 
349
        Allows the handler to completely override the parsing of the raw
 
350
        HTTP input.
 
351
 
 
352
        ``input_data`` is a file-like object that supports ``read()``-ing.
 
353
 
 
354
        ``META`` is the same object as ``request.META``.
 
355
 
 
356
        ``content_length`` is the length of the data in ``input_data``. Don't
 
357
        read more than ``content_length`` bytes from ``input_data``.
 
358
 
 
359
        ``boundary`` is the MIME boundary for this request.
 
360
 
 
361
        ``encoding`` is the encoding of the request.
 
362
 
 
363
        Return ``None`` if you want upload handling to continue, or a tuple of
 
364
        ``(POST, FILES)`` if you want to return the new data structures suitable
 
365
        for the request directly.