Debian Codegraph @

docs/ref/views.txt

raw
1 ==============
2 Built-in Views
3 ==============
4
5 .. module:: django.views
6 :synopsis: Django's built-in views.
7
8 Several of Django's built-in views are documented in
9 :doc:`/topics/http/views` as well as elsewhere in the documentation.
10
11 Serving files in development
12 ============================
13
14 .. function:: static.serve(request, path, document_root, show_indexes=False)
15
16 There may be files other than your project's static assets that, for
17 convenience, you'd like to have Django serve for you in local development.
18 The :func:`~django.views.static.serve` view can be used to serve any directory
19 you give it. (This view is **not** hardened for production use and should be
20 used only as a development aid; you should serve these files in production
21 using a real front-end web server).
22
23 The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`.
24 ``django.contrib.staticfiles`` is intended for static assets and has no
25 built-in handling for user-uploaded files, but you can have Django serve your
26 :setting:`MEDIA_ROOT` by appending something like this to your URLconf::
27
28 from django.conf import settings
29 from django.urls import re_path
30 from django.views.static import serve
31
32 # ... the rest of your URLconf goes here ...
33
34 if settings.DEBUG:
35 urlpatterns += [
36 re_path(
37 r"^media/(?P<path>.*)$",
38 serve,
39 {
40 "document_root": settings.MEDIA_ROOT,
41 },
42 ),
43 ]
44
45 Note, the snippet assumes your :setting:`MEDIA_URL` has a value of
46 ``'media/'``. This will call the :func:`~django.views.static.serve` view,
47 passing in the path from the URLconf and the (required) ``document_root``
48 parameter.
49
50 Since it can become a bit cumbersome to define this URL pattern, Django
51 ships with a small URL helper function :func:`~django.conf.urls.static.static`
52 that takes as parameters the prefix such as :setting:`MEDIA_URL` and a dotted
53 path to a view, such as ``'django.views.static.serve'``. Any other function
54 parameter will be transparently passed to the view.
55
56 .. _error-views:
57
58 Error views
59 ===========
60
61 Django comes with a few views by default for handling HTTP errors. To override
62 these with your own custom views, see :ref:`customizing-error-views`.
63
64 .. _http_not_found_view:
65
66 The 404 (page not found) view
67 -----------------------------
68
69 .. function:: defaults.page_not_found(request, exception, template_name='404.html')
70
71 When you raise :exc:`~django.http.Http404` from within a view, Django loads a
72 special view devoted to handling 404 errors. By default, it's the view
73 :func:`django.views.defaults.page_not_found`, which either produces a "Not
74 Found" message or loads and renders the template ``404.html`` if you created it
75 in your root template directory.
76
77 The default 404 view will pass two variables to the template: ``request_path``,
78 which is the URL that resulted in the error, and ``exception``, which is a
79 useful representation of the exception that triggered the view (e.g. containing
80 any message passed to a specific ``Http404`` instance).
81
82 Three things to note about 404 views:
83
84 * The 404 view is also called if Django doesn't find a match after
85 checking every regular expression in the URLconf.
86
87 * The 404 view is passed a :class:`~django.template.RequestContext` and
88 will have access to variables supplied by your template context
89 processors (e.g. ``MEDIA_URL``).
90
91 * If :setting:`DEBUG` is set to ``True`` (in your settings module), then
92 your 404 view will never be used, and your URLconf will be displayed
93 instead, with some debug information.
94
95 .. _http_internal_server_error_view:
96
97 The 500 (server error) view
98 ---------------------------
99
100 .. function:: defaults.server_error(request, template_name='500.html')
101
102 Similarly, Django executes special-case behavior in the case of runtime errors
103 in view code. If a view results in an exception, Django will, by default, call
104 the view ``django.views.defaults.server_error``, which either produces a
105 "Server Error" message or loads and renders the template ``500.html`` if you
106 created it in your root template directory.
107
108 The default 500 view passes no variables to the ``500.html`` template and is
109 rendered with an empty ``Context`` to lessen the chance of additional errors.
110
111 If :setting:`DEBUG` is set to ``True`` (in your settings module), then
112 your 500 view will never be used, and the traceback will be displayed
113 instead, with some debug information.
114
115 .. _http_forbidden_view:
116
117 The 403 (HTTP Forbidden) view
118 -----------------------------
119
120 .. function:: defaults.permission_denied(request, exception, template_name='403.html')
121
122 In the same vein as the 404 and 500 views, Django has a view to handle 403
123 Forbidden errors. If a view results in a 403 exception then Django will, by
124 default, call the view ``django.views.defaults.permission_denied``.
125
126 This view loads and renders the template ``403.html`` in your root template
127 directory, or if this file does not exist, instead serves the text
128 "403 Forbidden", as per :rfc:`9110#section-15.5.4` (the HTTP 1.1
129 Specification). The template context contains ``exception``, which is the
130 string representation of the exception that triggered the view.
131
132 ``django.views.defaults.permission_denied`` is triggered by a
133 :exc:`~django.core.exceptions.PermissionDenied` exception. To deny access in a
134 view you can use code like this::
135
136 from django.core.exceptions import PermissionDenied
137
138
139 def edit(request, pk):
140 if not request.user.is_staff:
141 raise PermissionDenied
142 # ...
143
144 .. _http_bad_request_view:
145
146 The 400 (bad request) view
147 --------------------------
148
149 .. function:: defaults.bad_request(request, exception, template_name='400.html')
150
151 When a :exc:`~django.core.exceptions.SuspiciousOperation` is raised in Django,
152 it may be handled by a component of Django (for example resetting the session
153 data). If not specifically handled, Django will consider the current request a
154 'bad request' instead of a server error.
155
156 ``django.views.defaults.bad_request``, is otherwise very similar to the
157 ``server_error`` view, but returns with the status code 400 indicating that
158 the error condition was the result of a client operation. By default, nothing
159 related to the exception that triggered the view is passed to the template
160 context, as the exception message might contain sensitive information like
161 filesystem paths.
162
163 ``bad_request`` views are also only used when :setting:`DEBUG` is ``False``.