mirror of
https://github.com/django/django.git
synced 2024-11-18 15:34:16 +00:00
277 lines
11 KiB
Plaintext
277 lines
11 KiB
Plaintext
============
|
|
File Uploads
|
|
============
|
|
|
|
.. currentmodule:: django.core.files.uploadedfile
|
|
|
|
When Django handles a file upload, the file data ends up placed in
|
|
:attr:`request.FILES <django.http.HttpRequest.FILES>` (for more on the
|
|
``request`` object see the documentation for :doc:`request and response objects
|
|
</ref/request-response>`). This document explains how files are stored on disk
|
|
and in memory, and how to customize the default behavior.
|
|
|
|
.. warning::
|
|
|
|
There are security risks if you are accepting uploaded content from
|
|
untrusted users! See the security guide's topic on
|
|
:ref:`user-uploaded-content-security` for mitigation details.
|
|
|
|
Basic file uploads
|
|
==================
|
|
|
|
Consider a simple form containing a :class:`~django.forms.FileField`::
|
|
|
|
# In forms.py...
|
|
from django import forms
|
|
|
|
class UploadFileForm(forms.Form):
|
|
title = forms.CharField(max_length=50)
|
|
file = forms.FileField()
|
|
|
|
A view handling this form will receive the file data in
|
|
:attr:`request.FILES <django.http.HttpRequest.FILES>`, which is a dictionary
|
|
containing a key for each :class:`~django.forms.FileField` (or
|
|
:class:`~django.forms.ImageField`, or other :class:`~django.forms.FileField`
|
|
subclass) in the form. So the data from the above form would
|
|
be accessible as ``request.FILES['file']``.
|
|
|
|
Note that :attr:`request.FILES <django.http.HttpRequest.FILES>` will only
|
|
contain data if the request method was ``POST`` and the ``<form>`` that posted
|
|
the request has the attribute ``enctype="multipart/form-data"``. Otherwise,
|
|
``request.FILES`` will be empty.
|
|
|
|
Most of the time, you'll simply pass the file data from ``request`` into the
|
|
form as described in :ref:`binding-uploaded-files`. This would look
|
|
something like::
|
|
|
|
from django.http import HttpResponseRedirect
|
|
from django.shortcuts import render_to_response
|
|
from .forms import UploadFileForm
|
|
|
|
# Imaginary function to handle an uploaded file.
|
|
from somewhere import handle_uploaded_file
|
|
|
|
def upload_file(request):
|
|
if request.method == 'POST':
|
|
form = UploadFileForm(request.POST, request.FILES)
|
|
if form.is_valid():
|
|
handle_uploaded_file(request.FILES['file'])
|
|
return HttpResponseRedirect('/success/url/')
|
|
else:
|
|
form = UploadFileForm()
|
|
return render_to_response('upload.html', {'form': form})
|
|
|
|
Notice that we have to pass :attr:`request.FILES <django.http.HttpRequest.FILES>`
|
|
into the form's constructor; this is how file data gets bound into a form.
|
|
|
|
Here's a common way you might handle an uploaded file::
|
|
|
|
def handle_uploaded_file(f):
|
|
with open('some/file/name.txt', 'wb+') as destination:
|
|
for chunk in f.chunks():
|
|
destination.write(chunk)
|
|
|
|
Looping over ``UploadedFile.chunks()`` instead of using ``read()`` ensures that
|
|
large files don't overwhelm your system's memory.
|
|
|
|
There are a few other methods and attributes available on ``UploadedFile``
|
|
objects; see :class:`UploadedFile` for a complete reference.
|
|
|
|
Handling uploaded files with a model
|
|
------------------------------------
|
|
|
|
If you're saving a file on a :class:`~django.db.models.Model` with a
|
|
:class:`~django.db.models.FileField`, using a :class:`~django.forms.ModelForm`
|
|
makes this process much easier. The file object will be saved to the location
|
|
specified by the :attr:`~django.db.models.FileField.upload_to` argument of the
|
|
corresponding :class:`~django.db.models.FileField` when calling
|
|
``form.save()``::
|
|
|
|
from django.http import HttpResponseRedirect
|
|
from django.shortcuts import render
|
|
from .forms import ModelFormWithFileField
|
|
|
|
def upload_file(request):
|
|
if request.method == 'POST':
|
|
form = ModelFormWithFileField(request.POST, request.FILES)
|
|
if form.is_valid():
|
|
# file is saved
|
|
form.save()
|
|
return HttpResponseRedirect('/success/url/')
|
|
else:
|
|
form = ModelFormWithFileField()
|
|
return render(request, 'upload.html', {'form': form})
|
|
|
|
If you are constructing an object manually, you can simply assign the file
|
|
object from :attr:`request.FILES <django.http.HttpRequest.FILES>` to the file
|
|
field in the model::
|
|
|
|
from django.http import HttpResponseRedirect
|
|
from django.shortcuts import render
|
|
from .forms import UploadFileForm
|
|
from .models import ModelWithFileField
|
|
|
|
def upload_file(request):
|
|
if request.method == 'POST':
|
|
form = UploadFileForm(request.POST, request.FILES)
|
|
if form.is_valid():
|
|
instance = ModelWithFileField(file_field=request.FILES['file'])
|
|
instance.save()
|
|
return HttpResponseRedirect('/success/url/')
|
|
else:
|
|
form = UploadFileForm()
|
|
return render(request, 'upload.html', {'form': form})
|
|
|
|
Upload Handlers
|
|
===============
|
|
|
|
.. currentmodule:: django.core.files.uploadhandler
|
|
|
|
When a user uploads a file, Django passes off the file data to an *upload
|
|
handler* -- a small class that handles file data as it gets uploaded. Upload
|
|
handlers are initially defined in the :setting:`FILE_UPLOAD_HANDLERS` setting,
|
|
which defaults to::
|
|
|
|
("django.core.files.uploadhandler.MemoryFileUploadHandler",
|
|
"django.core.files.uploadhandler.TemporaryFileUploadHandler",)
|
|
|
|
Together :class:`MemoryFileUploadHandler` and
|
|
:class:`TemporaryFileUploadHandler` provide Django's default file upload
|
|
behavior of reading small files into memory and large ones onto disk.
|
|
|
|
You can write custom handlers that customize how Django handles files. You
|
|
could, for example, use custom handlers to enforce user-level quotas, compress
|
|
data on the fly, render progress bars, and even send data to another storage
|
|
location directly without storing it locally. See :ref:`custom_upload_handlers`
|
|
for details on how you can customize or completely replace upload behavior.
|
|
|
|
.. _modifying_upload_handlers_on_the_fly:
|
|
|
|
Where uploaded data is stored
|
|
-----------------------------
|
|
|
|
Before you save uploaded files, the data needs to be stored somewhere.
|
|
|
|
By default, if an uploaded file is smaller than 2.5 megabytes, Django will hold
|
|
the entire contents of the upload in memory. This means that saving the file
|
|
involves only a read from memory and a write to disk and thus is very fast.
|
|
|
|
However, if an uploaded file is too large, Django will write the uploaded file
|
|
to a temporary file stored in your system's temporary directory. On a Unix-like
|
|
platform this means you can expect Django to generate a file called something
|
|
like ``/tmp/tmpzfp6I6.upload``. If an upload is large enough, you can watch this
|
|
file grow in size as Django streams the data onto disk.
|
|
|
|
These specifics -- 2.5 megabytes; ``/tmp``; etc. -- are simply "reasonable
|
|
defaults" which can be customized as described in the next section.
|
|
|
|
Changing upload handler behavior
|
|
--------------------------------
|
|
|
|
There are a few settings which control Django's file upload behavior:
|
|
|
|
:setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`
|
|
The maximum size, in bytes, for files that will be uploaded into memory.
|
|
Files larger than :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE` will be
|
|
streamed to disk.
|
|
|
|
Defaults to 2.5 megabytes.
|
|
|
|
:setting:`FILE_UPLOAD_TEMP_DIR`
|
|
The directory where uploaded files larger than
|
|
:setting:`FILE_UPLOAD_MAX_MEMORY_SIZE` will be stored.
|
|
|
|
Defaults to your system's standard temporary directory (i.e. ``/tmp`` on
|
|
most Unix-like systems).
|
|
|
|
:setting:`FILE_UPLOAD_PERMISSIONS`
|
|
The numeric mode (i.e. ``0644``) to set newly uploaded files to. For
|
|
more information about what these modes mean, see the documentation for
|
|
:func:`os.chmod`.
|
|
|
|
If this isn't given or is ``None``, you'll get operating-system
|
|
dependent behavior. On most platforms, temporary files will have a mode
|
|
of ``0600``, and files saved from memory will be saved using the
|
|
system's standard umask.
|
|
|
|
For security reasons, these permissions aren't applied to the temporary
|
|
files that are stored in :setting:`FILE_UPLOAD_TEMP_DIR`.
|
|
|
|
.. warning::
|
|
|
|
If you're not familiar with file modes, please note that the leading
|
|
``0`` is very important: it indicates an octal number, which is the
|
|
way that modes must be specified. If you try to use ``644``, you'll
|
|
get totally incorrect behavior.
|
|
|
|
**Always prefix the mode with a 0.**
|
|
|
|
:setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS`
|
|
The numeric mode to apply to directories created in the process of
|
|
uploading files. This value mirrors the functionality and caveats of
|
|
the :setting:`FILE_UPLOAD_PERMISSIONS` setting.
|
|
|
|
:setting:`FILE_UPLOAD_HANDLERS`
|
|
The actual handlers for uploaded files. Changing this setting allows
|
|
complete customization -- even replacement -- of Django's upload
|
|
process.
|
|
|
|
Modifying upload handlers on the fly
|
|
------------------------------------
|
|
|
|
Sometimes particular views require different upload behavior. In these cases,
|
|
you can override upload handlers on a per-request basis by modifying
|
|
``request.upload_handlers``. By default, this list will contain the upload
|
|
handlers given by :setting:`FILE_UPLOAD_HANDLERS`, but you can modify the list
|
|
as you would any other list.
|
|
|
|
For instance, suppose you've written a ``ProgressBarUploadHandler`` that
|
|
provides feedback on upload progress to some sort of AJAX widget. You'd add this
|
|
handler to your upload handlers like this::
|
|
|
|
request.upload_handlers.insert(0, ProgressBarUploadHandler())
|
|
|
|
You'd probably want to use ``list.insert()`` in this case (instead of
|
|
``append()``) because a progress bar handler would need to run *before* any
|
|
other handlers. Remember, the upload handlers are processed in order.
|
|
|
|
If you want to replace the upload handlers completely, you can just assign a new
|
|
list::
|
|
|
|
request.upload_handlers = [ProgressBarUploadHandler()]
|
|
|
|
.. note::
|
|
|
|
You can only modify upload handlers *before* accessing
|
|
``request.POST`` or ``request.FILES`` -- it doesn't make sense to
|
|
change upload handlers after upload handling has already
|
|
started. If you try to modify ``request.upload_handlers`` after
|
|
reading from ``request.POST`` or ``request.FILES`` Django will
|
|
throw an error.
|
|
|
|
Thus, you should always modify uploading handlers as early in your view as
|
|
possible.
|
|
|
|
Also, ``request.POST`` is accessed by
|
|
:class:`~django.middleware.csrf.CsrfViewMiddleware` which is enabled by
|
|
default. This means you will need to use
|
|
:func:`~django.views.decorators.csrf.csrf_exempt` on your view to allow you
|
|
to change the upload handlers. You will then need to use
|
|
:func:`~django.views.decorators.csrf.csrf_protect` on the function that
|
|
actually processes the request. Note that this means that the handlers may
|
|
start receiving the file upload before the CSRF checks have been done.
|
|
Example code:
|
|
|
|
.. code-block:: python
|
|
|
|
from django.views.decorators.csrf import csrf_exempt, csrf_protect
|
|
|
|
@csrf_exempt
|
|
def upload_file_view(request):
|
|
request.upload_handlers.insert(0, ProgressBarUploadHandler())
|
|
return _upload_file_view(request)
|
|
|
|
@csrf_protect
|
|
def _upload_file_view(request):
|
|
... # Process request
|