| 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``. |