200 lines
8.5 KiB
Plaintext
200 lines
8.5 KiB
Plaintext
===========================
|
|
Conditional View Processing
|
|
===========================
|
|
|
|
.. versionadded:: 1.1
|
|
|
|
HTTP clients can send a number of headers to tell the server about copies of a
|
|
resource that they have already seen. This is commonly used when retrieving a
|
|
web page (using an HTTP ``GET`` request) to avoid sending all the data for
|
|
something the client has already retrieved. However, the same headers can be
|
|
used for all HTTP methods (``POST``, ``PUT``, ``DELETE``, etc).
|
|
|
|
For each page (response) that Django sends back from a view, it might provide
|
|
two HTTP headers: the ``ETag`` header and the ``Last-Modified`` header. These
|
|
headers are optional on HTTP responses. They can be set by your view function,
|
|
or you can rely on the :class:`~django.middleware.common.CommonMiddleware`
|
|
middleware to set the ``ETag`` header.
|
|
|
|
When the client next requests the same resource, it might send along a header
|
|
such as `If-modified-since`_, containing the date of the last modification
|
|
time it was sent, or `If-none-match`_, containing the ``ETag`` it was sent.
|
|
If the current version of the page matches the ``ETag`` sent by the client, or
|
|
if the resource has not been modified, a 304 status code can be sent back,
|
|
instead of a full response, telling the client that nothing has changed.
|
|
|
|
.. _If-none-match: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26
|
|
.. _If-modified-since: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25
|
|
|
|
When you need more fine-grained control you may use per-view conditional
|
|
processing functions.
|
|
|
|
.. conditional-decorators:
|
|
|
|
The ``condition`` decorator
|
|
===========================
|
|
|
|
Sometimes (in fact, quite often) you can create functions to rapidly compute the ETag_
|
|
value or the last-modified time for a resource, **without** needing to do all
|
|
the computations needed to construct the full view. Django can then use these
|
|
functions to provide an "early bailout" option for the view processing.
|
|
Telling the client that the content has not been modified since the last
|
|
request, perhaps.
|
|
|
|
.. _ETag: http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.11
|
|
|
|
These two functions are passed as parameters the
|
|
``django.views.decorators.http.condition`` decorator. This decorator uses
|
|
the two functions (you only need to supply one, if you can't compute both
|
|
quantities easily and quickly) to work out if the headers in the HTTP request
|
|
match those on the resource. If they don't match, a new copy of the resource
|
|
must be computed and your normal view is called.
|
|
|
|
The ``condition`` decorator's signature looks like this::
|
|
|
|
condition(etag_func=None, last_modified_func=None)
|
|
|
|
The two functions, to compute the ETag and the last modified time, will be
|
|
passed the incoming ``request`` object and the same parameters, in the same
|
|
order, as the view function they are helping to wrap. The function passed
|
|
``last_modified_func`` should return a standard datetime value specifying the
|
|
last time the resource was modified, or ``None`` if the resource doesn't
|
|
exist. The function passed to the ``etag`` decorator should return a string
|
|
representing the `Etag`_ for the resource, or ``None`` if it doesn't exist.
|
|
|
|
Using this feature usefully is probably best explained with an example.
|
|
Suppose you have this pair of models, representing a simple blog system::
|
|
|
|
import datetime
|
|
from django.db import models
|
|
|
|
class Blog(models.Model):
|
|
...
|
|
|
|
class Entry(models.Model):
|
|
blog = models.ForeignKey(Blog)
|
|
published = models.DateTimeField(default=datetime.datetime.now)
|
|
...
|
|
|
|
If the front page, displaying the latest blog entries, only changes when you
|
|
add a new blog entry, you can compute the last modified time very quickly. You
|
|
need the latest ``published`` date for every entry associated with that blog.
|
|
One way to do this would be::
|
|
|
|
def latest_entry(request, blog_id):
|
|
return Entry.objects.filter(blog=blog_id).latest("published").published
|
|
|
|
You can then use this function to provide early detection of an unchanged page
|
|
for your front page view::
|
|
|
|
from django.views.decorators.http import condition
|
|
|
|
@condition(last_modified_func=latest_entry)
|
|
def front_page(request, blog_id):
|
|
...
|
|
|
|
Shortcuts for only computing one value
|
|
======================================
|
|
|
|
As a general rule, if you can provide functions to compute *both* the ETag and
|
|
the last modified time, you should do so. You don't know which headers any
|
|
given HTTP client will send you, so be prepared to handle both. However,
|
|
sometimes only one value is easy to compute and Django provides decorators
|
|
that handle only ETag or only last-modified computations.
|
|
|
|
The ``django.views.decorators.http.etag`` and
|
|
``django.views.decorators.http.last_modified`` decorators are passed the same
|
|
type of functions as the ``condition`` decorator. Their signatures are::
|
|
|
|
etag(etag_func)
|
|
last_modified(last_modified_func)
|
|
|
|
We could write the earlier example, which only uses a last-modified function,
|
|
using one of these decorators::
|
|
|
|
@last_modified(latest_entry)
|
|
def front_page(request, blog_id):
|
|
...
|
|
|
|
...or::
|
|
|
|
def front_page(request, blog_id):
|
|
...
|
|
front_page = last_modified(latest_entry)(front_page)
|
|
|
|
Use ``condition`` when testing both conditions
|
|
------------------------------------------------
|
|
|
|
It might look nicer to some people to try and chain the ``etag`` and
|
|
``last_modified`` decorators if you want to test both preconditions. However,
|
|
this would lead to incorrect behavior.
|
|
|
|
::
|
|
|
|
# Bad code. Don't do this!
|
|
@etag(etag_func)
|
|
@last_modified(last_modified_func)
|
|
def my_view(request):
|
|
# ...
|
|
|
|
# End of bad code.
|
|
|
|
The first decorator doesn't know anything about the second and might
|
|
answer that the response is not modified even if the second decorators would
|
|
determine otherwise. The ``condition`` decorator uses both callback functions
|
|
simultaneously to work out the right action to take.
|
|
|
|
Using the decorators with other HTTP methods
|
|
============================================
|
|
|
|
The ``condition`` decorator is useful for more than only ``GET`` and
|
|
``HEAD`` requests (``HEAD`` requests are the same as ``GET`` in this
|
|
situation). It can be used also to be used to provide checking for ``POST``,
|
|
``PUT`` and ``DELETE`` requests. In these situations, the idea isn't to return
|
|
a "not modified" response, but to tell the client that the resource they are
|
|
trying to change has been altered in the meantime.
|
|
|
|
For example, consider the following exchange between the client and server:
|
|
|
|
1. Client requests ``/foo/``.
|
|
2. Server responds with some content with an ETag of ``"abcd1234"``.
|
|
3. Client sends an HTTP ``PUT`` request to ``/foo/`` to update the
|
|
resource. It also sends an ``If-Match: "abcd1234"`` header to specify
|
|
the version it is trying to update.
|
|
4. Server checks to see if the resource has changed, by computing the ETag
|
|
the same way it does for a ``GET`` request (using the same function).
|
|
If the resource *has* changed, it will return a 412 status code code,
|
|
meaning "precondition failed".
|
|
5. Client sends a ``GET`` request to ``/foo/``, after receiving a 412
|
|
response, to retrieve an updated version of the content before updating
|
|
it.
|
|
|
|
The important thing this example shows is that the same functions can be used
|
|
to compute the ETag and last modification values in all situations. In fact,
|
|
you **should** use the same functions, so that the same values are returned
|
|
every time.
|
|
|
|
Comparison with middleware conditional processing
|
|
=================================================
|
|
|
|
You may notice that Django already provides simple and straightforward
|
|
conditional ``GET`` handling via the
|
|
:class:`django.middleware.http.ConditionalGetMiddleware` and
|
|
:class:`~django.middleware.common.CommonMiddleware`. Whilst certainly being
|
|
easy to use and suitable for many situations, those pieces of middleware
|
|
functionality have limitations for advanced usage:
|
|
|
|
* They are applied globally to all views in your project
|
|
* They don't save you from generating the response itself, which may be
|
|
expensive
|
|
* They are only appropriate for HTTP ``GET`` requests.
|
|
|
|
You should choose the most appropriate tool for your particular problem here.
|
|
If you have a way to compute ETags and modification times quickly and if some
|
|
view takes a while to generate the content, you should consider using the
|
|
``condition`` decorator described in this document. If everything already runs
|
|
fairly quickly, stick to using the middleware and the amount of network
|
|
traffic sent back to the clients will still be reduced if the view hasn't
|
|
changed.
|
|
|