Debian Codegraph @

docs/topics/http/decorators.txt

raw
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