| 1 |
=============== |
| 2 |
View decorators |
| 3 |
=============== |
| 4 |
|
| 5 |
.. module:: django.views.decorators.http |
| 6 |
|
| 7 |
Django provides several decorators that can be applied to views to support |
| 8 |
various HTTP features. |
| 9 |
|
| 10 |
See :ref:`decorating-class-based-views` for how to use these decorators with |
| 11 |
class-based views. |
| 12 |
|
| 13 |
Allowed HTTP methods |
| 14 |
==================== |
| 15 |
|
| 16 |
The decorators in :mod:`django.views.decorators.http` can be used to restrict |
| 17 |
access to views based on the request method. These decorators will return |
| 18 |
a :class:`django.http.HttpResponseNotAllowed` if the conditions are not met. |
| 19 |
|
| 20 |
.. function:: require_http_methods(request_method_list) |
| 21 |
|
| 22 |
Decorator to require that a view only accepts particular request |
| 23 |
methods. Usage:: |
| 24 |
|
| 25 |
from django.views.decorators.http import require_http_methods |
| 26 |
|
| 27 |
|
| 28 |
@require_http_methods(["GET", "POST"]) |
| 29 |
def my_view(request): |
| 30 |
# I can assume now that only GET or POST requests make it this far |
| 31 |
# ... |
| 32 |
pass |
| 33 |
|
| 34 |
Note that request methods should be in uppercase. |
| 35 |
|
| 36 |
.. function:: require_GET() |
| 37 |
|
| 38 |
Decorator to require that a view only accepts the GET method. |
| 39 |
|
| 40 |
.. function:: require_POST() |
| 41 |
|
| 42 |
Decorator to require that a view only accepts the POST method. |
| 43 |
|
| 44 |
.. function:: require_safe() |
| 45 |
|
| 46 |
Decorator to require that a view only accepts the GET and HEAD methods. |
| 47 |
These methods are commonly considered "safe" because they should not have |
| 48 |
the significance of taking an action other than retrieving the requested |
| 49 |
resource. |
| 50 |
|
| 51 |
.. note:: |
| 52 |
Web servers should automatically strip the content of responses to HEAD |
| 53 |
requests while leaving the headers unchanged, so you may handle HEAD |
| 54 |
requests exactly like GET requests in your views. Since some software, |
| 55 |
such as link checkers, rely on HEAD requests, you might prefer |
| 56 |
using ``require_safe`` instead of ``require_GET``. |
| 57 |
|
| 58 |
Conditional view processing |
| 59 |
=========================== |
| 60 |
|
| 61 |
The following decorators in :mod:`django.views.decorators.http` can be used to |
| 62 |
control caching behavior on particular views. |
| 63 |
|
| 64 |
.. function:: condition(etag_func=None, last_modified_func=None) |
| 65 |
|
| 66 |
.. function:: conditional_page() |
| 67 |
|
| 68 |
This decorator provides the conditional GET operation handling of |
| 69 |
:class:`~django.middleware.http.ConditionalGetMiddleware` to a view. |
| 70 |
|
| 71 |
.. function:: etag(etag_func) |
| 72 |
|
| 73 |
.. function:: last_modified(last_modified_func) |
| 74 |
|
| 75 |
These decorators can be used to generate ``ETag`` and ``Last-Modified`` |
| 76 |
headers; see |
| 77 |
:doc:`conditional view processing </topics/conditional-view-processing>`. |
| 78 |
|
| 79 |
.. module:: django.views.decorators.gzip |
| 80 |
|
| 81 |
GZip compression |
| 82 |
================ |
| 83 |
|
| 84 |
The decorators in :mod:`django.views.decorators.gzip` control content |
| 85 |
compression on a per-view basis. |
| 86 |
|
| 87 |
.. function:: gzip_page() |
| 88 |
|
| 89 |
This decorator compresses content if the browser allows gzip compression. |
| 90 |
It sets the ``Vary`` header accordingly, so that caches will base their |
| 91 |
storage on the ``Accept-Encoding`` header. |
| 92 |
|
| 93 |
.. module:: django.views.decorators.vary |
| 94 |
|
| 95 |
Vary headers |
| 96 |
============ |
| 97 |
|
| 98 |
The decorators in :mod:`django.views.decorators.vary` can be used to control |
| 99 |
caching based on specific request headers. |
| 100 |
|
| 101 |
.. function:: vary_on_cookie(func) |
| 102 |
|
| 103 |
.. function:: vary_on_headers(*headers) |
| 104 |
|
| 105 |
The ``Vary`` header defines which request headers a cache mechanism should take |
| 106 |
into account when building its cache key. |
| 107 |
|
| 108 |
See :ref:`using vary headers <using-vary-headers>`. |
| 109 |
|
| 110 |
.. module:: django.views.decorators.cache |
| 111 |
|
| 112 |
Caching |
| 113 |
======= |
| 114 |
|
| 115 |
The decorators in :mod:`django.views.decorators.cache` control server and |
| 116 |
client-side caching. |
| 117 |
|
| 118 |
.. function:: cache_control(**kwargs) |
| 119 |
|
| 120 |
This decorator patches the response's ``Cache-Control`` header by adding |
| 121 |
all of the keyword arguments to it. See |
| 122 |
:func:`~django.utils.cache.patch_cache_control` for the details of the |
| 123 |
transformation. |
| 124 |
|
| 125 |
.. function:: never_cache(view_func) |
| 126 |
|
| 127 |
This decorator adds an ``Expires`` header to the current date/time. |
| 128 |
|
| 129 |
This decorator adds a ``Cache-Control: max-age=0, no-cache, no-store, |
| 130 |
must-revalidate, private`` header to a response to indicate that a page |
| 131 |
should never be cached. |
| 132 |
|
| 133 |
Each header is only added if it isn't already set. |
| 134 |
|
| 135 |
.. module:: django.views.decorators.common |
| 136 |
|
| 137 |
Common |
| 138 |
====== |
| 139 |
|
| 140 |
The decorators in :mod:`django.views.decorators.common` allow per-view |
| 141 |
customization of :class:`~django.middleware.common.CommonMiddleware` behavior. |
| 142 |
|
| 143 |
.. function:: no_append_slash() |
| 144 |
|
| 145 |
This decorator allows individual views to be excluded from |
| 146 |
:setting:`APPEND_SLASH` URL normalization. |
| 147 |
|