PageRenderTime 165ms CodeModel.GetById 73ms app.highlight 3ms RepoModel.GetById 55ms app.codeStats 0ms

/docs/topics/http/file-uploads.txt

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